/usr/include/mirclient/mir_toolkit/mir_connection.h is in libmirclient-dev 0.21.0+16.04.20160330-0ubuntu1.
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 | /*
* 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 <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,
mir_connected_callback 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);
/**
* 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);
/**
* 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,
mir_lifecycle_event_callback 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,
mir_ping_event_callback 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);
/**
* 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,
mir_display_config_callback 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);
/**
* 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);
/**
* 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);
/**
* 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 format_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,
mir_platform_operation_callback callback, void* context);
/**
* Create a snapshot of the attached input devices and device configurations.
* \warning return value must be destroyed via mir_input_config_destroy()
* \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);
/**
* Release this snapshot of the input configuration.
* This invalidates any pointers retrieved from this structure.
*
* \param [in] devices The input configuration
*/
void mir_input_config_destroy(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,
mir_input_config_callback callback, void* context);
#ifdef __cplusplus
}
/**@}*/
#endif
#endif /* MIR_TOOLKIT_MIR_CONNECTION_H_ */
|