/usr/include/mirclient/mir_toolkit/mir_connection.h is in libmirclient-dev 0.26.3+16.04.20170605-0ubuntu1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 | /*
* Copyright © 2012-2014 Canonical Ltd.
*
* This program is free software: you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License version 3,
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
#ifndef MIR_TOOLKIT_MIR_CONNECTION_H_
#define MIR_TOOLKIT_MIR_CONNECTION_H_
#include <mir_toolkit/client_types.h>
#include <mir_toolkit/common.h>
#include <mir_toolkit/deprecations.h>
#include <stdbool.h>
#ifdef __cplusplus
/**
* \addtogroup mir_toolkit
* @{
*/
extern "C" {
#endif
/**
* Request a connection to the Mir server. The supplied callback is called when
* the connection is established, or fails. The returned wait handle remains
* valid until the connection has been released.
* \warning callback could be called from another thread. You must do any
* locking appropriate to protect your data accessed in the
* callback.
* \param [in] server File path of the server socket to connect to, or
* NULL to choose the default server (can be set by
* the $MIR_SOCKET environment variable)
* \param [in] app_name A name referring to the application
* \param [in] callback Callback function to be invoked when request
* completes
* \param [in,out] context User data passed to the callback function
* \return A handle that can be passed to mir_wait_for
*/
MirWaitHandle *mir_connect(
char const *server,
char const *app_name,
MirConnectedCallback callback,
void *context);
/**
* Perform a mir_connect() but also wait for and return the result.
* \param [in] server File path of the server socket to connect to, or
* NULL to choose the default server
* \param [in] app_name A name referring to the application
* \return The resulting MirConnection
*/
MirConnection *mir_connect_sync(char const *server, char const *app_name);
/**
* Test for a valid connection
* \param [in] connection The connection
* \return True if the supplied connection is valid, or
* false otherwise.
*/
bool mir_connection_is_valid(MirConnection *connection);
/**
* Retrieve a text description of the last error. The returned string is owned
* by the library and remains valid until the connection has been released.
* \param [in] connection The connection
* \return A text description of any error resulting in an
* invalid connection, or the empty string "" if the
* connection is valid.
*/
char const *mir_connection_get_error_message(MirConnection *connection);
/**
* Release a connection to the Mir server
* \param [in] connection The connection
*/
void mir_connection_release(MirConnection *connection);
/**
* Query platform-specific data and/or file descriptors that are required to
* initialize GL/EGL features.
* \param [in] connection The connection
* \param [out] platform_package Structure to be populated
*/
void mir_connection_get_platform(MirConnection *connection, MirPlatformPackage *platform_package)
MIR_FOR_REMOVAL_IN_VERSION_1("use platform extensions instead");
/**
* Query graphics platform module.
*
* \note The char pointers in MirModuleProperties are owned by the connection and should not be
* freed. They remain valid until the connection is released.
*
* \param [in] connection The connection
* \param [out] properties Structure to be populated
*/
void mir_connection_get_graphics_module(MirConnection *connection, MirModuleProperties *properties)
MIR_FOR_REMOVAL_IN_VERSION_1("use graphics module extension instead");
/**
* Register a callback to be called when a Lifecycle state change occurs.
* \param [in] connection The connection
* \param [in] callback The function to be called when the state change occurs
* \param [in,out] context User data passed to the callback function
*/
void mir_connection_set_lifecycle_event_callback(MirConnection* connection,
MirLifecycleEventCallback callback, void* context);
/**
* Register a callback for server ping events.
*
* The server may send ping requests to detect unresponsive applications. Clients should
* process this with their regular event handling, and call mir_connection_pong() in response.
*
* The shell may treat a client which fails to pong in a timely fashion differently; a common
* response is to overlay the surface with an unresponsive application message.
*
* A default implementation that immediately calls pong is provided; toolkits SHOULD override
* this default implementation to more accurately reflect the state of their event processing
* loop.
*
* \param [in] connection The connection
* \param [in] callback The function to be called on ping events.
* \param [in] context User data passed to the callback function
*/
void mir_connection_set_ping_event_callback(MirConnection* connection,
MirPingEventCallback callback, void* context);
/**
* Respond to a ping event
* \param [in] connection The connection
* \param [in] serial Serial from the ping event
*/
void mir_connection_pong(MirConnection* connection, int32_t serial);
/**
* Query the display
*
* \deprecated Use mir_connection_create_display_configuration() instead.
*
* \warning return value must be destroyed via mir_display_config_destroy()
* \warning may return null if connection is invalid
* \param [in] connection The connection
* \return structure that describes the display configuration
*/
MirDisplayConfiguration* mir_connection_create_display_config(MirConnection *connection)
MIR_FOR_REMOVAL_IN_VERSION_1("use mir_connection_create_display_configuration instead");
/**
* Query the display
*
* \pre mir_connection_is_valid(connection) == true
* \warning return value must be destroyed via mir_display_config_release()
*
* \param [in] connection The connection
* \return structure that describes the display configuration
*/
MirDisplayConfig* mir_connection_create_display_configuration(MirConnection* connection);
/**
* Register a callback to be called when the hardware display configuration changes
*
* Once a change has occurred, you can use mir_connection_create_display_configuration to see
* the new configuration.
*
* \param [in] connection The connection
* \param [in] callback The function to be called when a display change occurs
* \param [in,out] context User data passed to the callback function
*/
void mir_connection_set_display_config_change_callback(
MirConnection* connection,
MirDisplayConfigCallback callback, void* context);
/**
* Destroy the DisplayConfiguration resource acquired from mir_connection_create_display_config
* \param [in] display_configuration The display_configuration information resource to be destroyed
*/
void mir_display_config_destroy(MirDisplayConfiguration* display_configuration)
MIR_FOR_REMOVAL_IN_VERSION_1("use mir_display_config_release instead");
/**
* Apply the display configuration
*
* The display configuration is applied to this connection only (per-connection
* configuration) and is invalidated when a hardware change occurs. Clients should
* register a callback with mir_connection_set_display_config_change_callback()
* to get notified about hardware changes, so that the can apply a new configuration.
*
* \warning This request may be denied. Check that the request succeeded with mir_connection_get_error_message.
* \param [in] connection The connection
* \param [in] display_configuration The display_configuration to apply
* \return A handle that can be passed to mir_wait_for
*/
MirWaitHandle* mir_connection_apply_display_config(MirConnection *connection, MirDisplayConfiguration* display_configuration)
MIR_FOR_REMOVAL_IN_VERSION_1("use mir_connection_apply_session_display_config instead");
/**
* Apply the display config for the connection
*
* The display config is applied to this connection only (per-connection
* config) and is invalidated when a hardware change occurs. Clients should
* register a callback with mir_connection_set_display_config_change_callback()
* to get notified about hardware changes, so that they can apply a new config.
*
* \param [in] connection The connection
* \param [in] display_config The display_config to apply
*/
void mir_connection_apply_session_display_config(MirConnection* connection, MirDisplayConfig const* display_config);
/**
* Remove the display configuration for the connection
*
* If a session display config is applied to the connection it is removed, and
* the base display config is used. If there was no previous call to
* mir_connection_apply_session_display_config this will do nothing.
*
* \param [in] connection The connection
*/
void mir_connection_remove_session_display_config(MirConnection* connection);
/**
* Set the base display configuration
*
* The base display configuration is the configuration the server applies when
* there is no active per-connection configuration.
*
* When the wait handle returned by this function becomes ready, clients can use
* mir_connection_get_error_message() to check if an authorization error occurred.
* Only authorization errors are guaranteed to return an error message for this
* operation.
*
* A successful result (i.e. no error) does not guarantee that the base display
* configuration has been changed to the desired value. Clients should register
* a callback with mir_connection_set_display_config_change_callback() to monitor
* actual base display configuration changes.
*
* \warning This request may be denied. Check that the request succeeded with mir_connection_get_error_message.
* \param [in] connection The connection
* \param [in] display_configuration The display_configuration to set as base
* \return A handle that can be passed to mir_wait_for
*/
MirWaitHandle* mir_connection_set_base_display_config(
MirConnection* connection,
MirDisplayConfiguration const* display_configuration)
MIR_FOR_REMOVAL_IN_VERSION_1("use mir_connection_preview_base_display_configuration/mir_connection_confirm_base_display_configuration");
/**
* Preview a new base display configuration
*
* The base display configuration is the configuration the server applies when
* there is no active per-connection configuration.
*
* The display configuration will automatically revert to the previous
* settings after timeout_seconds unless confirmed by a call to
* mir_connection_confirm_base_display_configuration(), or is reverted
* immediately after a call to mir_connection_cancel_display_configuration_preview().
*
* If this request succeeds a configuration change event is sent to the
* client. Clients should register a callback with
* mir_connection_set_display_config_change_callback() in order to determine
* when this call succeeds.
*
* If the configuration is not confirmed before timeout_seconds have elapsed
* a second configuration change event is sent, with the old config.
*
* \param [in] connection The connection
* \param [in] configuration The MirDisplayConfig to set as base
* \param [in] timeout_seconds The time the server should wait, in seconds,
* for the change to be confirmed before
* reverting to the previous configuration.
*/
void mir_connection_preview_base_display_configuration(
MirConnection* connection,
MirDisplayConfig const* configuration,
int timeout_seconds);
/**
* Confirm a base configuration change initiated by mir_connection_preview_base_display_configuration()
*
* The base display configuration is the configuration the server applies when
* there is no active per-connection configuration.
*
* If this request succeeds a second configuration change event is sent to the
* client, identical to the one sent after
* mir_connection_preview_base_display_configuration(). Clients should
* register a callback with mir_connection_set_display_config_change_callback()
* in order to determine when this call succeeds.
*
* The MirDisplayConfig must be the same as the one passed to
* mir_connection_preview_base_display_configuration().
*
* \param [in] connection The connection
* \param [in] configuration The MirDisplayConfig to confirm as base
* configuration.
*/
void mir_connection_confirm_base_display_configuration(
MirConnection* connection,
MirDisplayConfig const* configuration);
/**
* Cancel a pending base display configuration preview.
*
* If this request succeeds a configuration change event is sent to the client,
* with the now-current base display configuration.
*
* This call will fail if there is no display configuration preview current.
* A client can detect this by registering a callback with
* mir_connection_set_error_callback() and checking for
* mir_display_configuration_error_no_preview_in_progress.
*
* \param [in] connection The connection
*/
void mir_connection_cancel_base_display_configuration_preview(
MirConnection* connection);
/**
* Get a display type that can be used for OpenGL ES 2.0 acceleration.
* \param [in] connection The connection
* \return An EGLNativeDisplayType that the client can use
*/
MirEGLNativeDisplayType mir_connection_get_egl_native_display(MirConnection *connection);
/**
* Get the exact MirPixelFormat to use in creating a surface for a chosen
* EGLConfig.
* \param [in] connection The connection
* \param [in] egldisplay The EGLDisplay for the given config
* \param [in] eglconfig The EGLConfig you have chosen to use
* \return The MirPixelFormat to use in surface creation
*/
MirPixelFormat mir_connection_get_egl_pixel_format(
MirConnection *connection, void *egldisplay, void *eglconfig);
/**
* Get the list of possible formats that a surface can be created with.
* \param [in] connection The connection
* \param [out] formats List of valid formats to create surfaces with
* \param [in] formats_size size of formats list
* \param [out] num_valid_formats number of valid formats returned in formats
*
* \note Users of EGL should call mir_connection_get_egl_pixel_format instead,
* as it will take the guesswork out of choosing between similar pixel
* formats. At the moment, this function returns a compatible list of
* formats likely to work for either software or hardware rendering.
* However it is not the full or accurate list and will be replaced in
* future by a function that takes the intended MirBufferUsage into
* account.
*/
void mir_connection_get_available_surface_formats(
MirConnection* connection, MirPixelFormat* formats,
unsigned const int formats_size, unsigned int *num_valid_formats);
/**
* Perform a platform specific operation.
*
* The MirPlatformMessage used for the request needs to remain valid
* until this operation finishes.
*
* \param [in] connection The connection
* \param [in] request The message used for this operation
* \param [in] callback The callback to call when the operation finishes
* \param [in,out] context User data passed to the callback function
* \return A handle that can be passed to mir_wait_for
*/
MirWaitHandle* mir_connection_platform_operation(
MirConnection* connection,
MirPlatformMessage const* request,
MirPlatformOperationCallback callback, void* context)
MIR_FOR_REMOVAL_IN_VERSION_1("use platform specific extensions instead");
/**
* Create a snapshot of the attached input devices and device configurations.
* \warning return value must be destroyed via mir_input_config_release()
* \warning may return null if connection is invalid
* \param [in] connection The connection
* \return structure that describes the input configuration
*/
MirInputConfig* mir_connection_create_input_config(MirConnection *connection);
/**
* \deprecated Use mir_input_config_release() instead.
*
* Release this snapshot of the input configuration.
* This invalidates any pointers retrieved from this structure.
*
* \param [in] config The input configuration
*/
void mir_input_config_destroy(MirInputConfig const* config)
MIR_FOR_REMOVAL_IN_VERSION_1("use mir_input_config_release instead");
/**
* Release this snapshot of the input configuration.
* This invalidates any pointers retrieved from this structure.
*
* \param [in] config The input configuration
*/
void mir_input_config_release(MirInputConfig const* config);
/**
* Register a callback to be called when the input devices change.
*
* Once a change has occurred, you can use mir_connection_create_input_config
* to get an updated snapshot of the input device configuration.
*
* \param [in] connection The connection
* \param [in] callback The function to be called when a change occurs
* \param [in,out] context User data passed to the callback function
*/
void mir_connection_set_input_config_change_callback(
MirConnection* connection,
MirInputConfigCallback callback, void* context);
/**
* Register a callback to be called on non-fatal errors
*
* \param [in] connection The connection
* \param [in] callback The function to be called when an error occurs
* \param [in,out] context User data passed to the callback function
*/
void mir_connection_set_error_callback(
MirConnection* connection,
MirErrorCallback callback,
void* context);
#ifdef __cplusplus
}
/**@}*/
#endif
#endif /* MIR_TOOLKIT_MIR_CONNECTION_H_ */
|