1 /* 2 * Copyright © 2008 Kristian Høgsberg 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining 5 * a copy of this software and associated documentation files (the 6 * "Software"), to deal in the Software without restriction, including 7 * without limitation the rights to use, copy, modify, merge, publish, 8 * distribute, sublicense, and/or sell copies of the Software, and to 9 * permit persons to whom the Software is furnished to do so, subject to 10 * the following conditions: 11 * 12 * The above copyright notice and this permission notice (including the 13 * next paragraph) shall be included in all copies or substantial 14 * portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 20 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 21 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 */ 25 26 #ifndef WAYLAND_CLIENT_CORE_H 27 #define WAYLAND_CLIENT_CORE_H 28 29 #include <stdint.h> 30 #include "wayland-util.h" 31 #include "wayland-version.h" 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /** \class wl_proxy 38 * 39 * \brief Represents a protocol object on the client side. 40 * 41 * A wl_proxy acts as a client side proxy to an object existing in the 42 * compositor. The proxy is responsible for converting requests made by the 43 * clients with \ref wl_proxy_marshal() into Wayland's wire format. Events 44 * coming from the compositor are also handled by the proxy, which will in 45 * turn call the handler set with \ref wl_proxy_add_listener(). 46 * 47 * \note With the exception of function \ref wl_proxy_set_queue(), functions 48 * accessing a wl_proxy are not normally used by client code. Clients 49 * should normally use the higher level interface generated by the scanner to 50 * interact with compositor objects. 51 * 52 */ 53 struct wl_proxy; 54 55 /** \class wl_display 56 * 57 * \brief Represents a connection to the compositor and acts as a proxy to 58 * the wl_display singleton object. 59 * 60 * A wl_display object represents a client connection to a Wayland 61 * compositor. It is created with either \ref wl_display_connect() or 62 * \ref wl_display_connect_to_fd(). A connection is terminated using 63 * \ref wl_display_disconnect(). 64 * 65 * A wl_display is also used as the \ref wl_proxy for the wl_display 66 * singleton object on the compositor side. 67 * 68 * A wl_display object handles all the data sent from and to the 69 * compositor. When a \ref wl_proxy marshals a request, it will write its wire 70 * representation to the display's write buffer. The data is sent to the 71 * compositor when the client calls \ref wl_display_flush(). 72 * 73 * Incoming data is handled in two steps: queueing and dispatching. In the 74 * queue step, the data coming from the display fd is interpreted and 75 * added to a queue. On the dispatch step, the handler for the incoming 76 * event set by the client on the corresponding \ref wl_proxy is called. 77 * 78 * A wl_display has at least one event queue, called the <em>default 79 * queue</em>. Clients can create additional event queues with \ref 80 * wl_display_create_queue() and assign \ref wl_proxy's to it. Events 81 * occurring in a particular proxy are always queued in its assigned queue. 82 * A client can ensure that a certain assumption, such as holding a lock 83 * or running from a given thread, is true when a proxy event handler is 84 * called by assigning that proxy to an event queue and making sure that 85 * this queue is only dispatched when the assumption holds. 86 * 87 * The default queue is dispatched by calling \ref wl_display_dispatch(). 88 * This will dispatch any events queued on the default queue and attempt 89 * to read from the display fd if it's empty. Events read are then queued 90 * on the appropriate queues according to the proxy assignment. 91 * 92 * A user created queue is dispatched with \ref wl_display_dispatch_queue(). 93 * This function behaves exactly the same as wl_display_dispatch() 94 * but it dispatches given queue instead of the default queue. 95 * 96 * A real world example of event queue usage is Mesa's implementation of 97 * eglSwapBuffers() for the Wayland platform. This function might need 98 * to block until a frame callback is received, but dispatching the default 99 * queue could cause an event handler on the client to start drawing 100 * again. This problem is solved using another event queue, so that only 101 * the events handled by the EGL code are dispatched during the block. 102 * 103 * This creates a problem where a thread dispatches a non-default 104 * queue, reading all the data from the display fd. If the application 105 * would call \em poll(2) after that it would block, even though there 106 * might be events queued on the default queue. Those events should be 107 * dispatched with \ref wl_display_dispatch_pending() or \ref 108 * wl_display_dispatch_queue_pending() before flushing and blocking. 109 */ 110 struct wl_display; 111 112 /** \class wl_event_queue 113 * 114 * \brief A queue for \ref wl_proxy object events. 115 * 116 * Event queues allows the events on a display to be handled in a thread-safe 117 * manner. See \ref wl_display for details. 118 * 119 */ 120 struct wl_event_queue; 121 122 /** Destroy proxy after marshalling 123 * @ingroup wl_proxy 124 */ 125 #define WL_MARSHAL_FLAG_DESTROY (1 << 0) 126 127 void 128 wl_event_queue_destroy(struct wl_event_queue *queue); 129 130 struct wl_proxy * 131 wl_proxy_marshal_flags(struct wl_proxy *proxy, uint32_t opcode, 132 const struct wl_interface *interface, 133 uint32_t version, 134 uint32_t flags, ...); 135 136 struct wl_proxy * 137 wl_proxy_marshal_array_flags(struct wl_proxy *proxy, uint32_t opcode, 138 const struct wl_interface *interface, 139 uint32_t version, 140 uint32_t flags, 141 union wl_argument *args); 142 143 void 144 wl_proxy_marshal(struct wl_proxy *p, uint32_t opcode, ...); 145 146 void 147 wl_proxy_marshal_array(struct wl_proxy *p, uint32_t opcode, 148 union wl_argument *args); 149 150 struct wl_proxy * 151 wl_proxy_create(struct wl_proxy *factory, 152 const struct wl_interface *interface); 153 154 void * 155 wl_proxy_create_wrapper(void *proxy); 156 157 void 158 wl_proxy_wrapper_destroy(void *proxy_wrapper); 159 160 struct wl_proxy * 161 wl_proxy_marshal_constructor(struct wl_proxy *proxy, 162 uint32_t opcode, 163 const struct wl_interface *interface, 164 ...); 165 166 struct wl_proxy * 167 wl_proxy_marshal_constructor_versioned(struct wl_proxy *proxy, 168 uint32_t opcode, 169 const struct wl_interface *interface, 170 uint32_t version, 171 ...); 172 173 struct wl_proxy * 174 wl_proxy_marshal_array_constructor(struct wl_proxy *proxy, 175 uint32_t opcode, union wl_argument *args, 176 const struct wl_interface *interface); 177 178 struct wl_proxy * 179 wl_proxy_marshal_array_constructor_versioned(struct wl_proxy *proxy, 180 uint32_t opcode, 181 union wl_argument *args, 182 const struct wl_interface *interface, 183 uint32_t version); 184 185 void 186 wl_proxy_destroy(struct wl_proxy *proxy); 187 188 int 189 wl_proxy_add_listener(struct wl_proxy *proxy, 190 void (**implementation)(void), void *data); 191 192 const void * 193 wl_proxy_get_listener(struct wl_proxy *proxy); 194 195 int 196 wl_proxy_add_dispatcher(struct wl_proxy *proxy, 197 wl_dispatcher_func_t dispatcher_func, 198 const void * dispatcher_data, void *data); 199 200 void 201 wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data); 202 203 void * 204 wl_proxy_get_user_data(struct wl_proxy *proxy); 205 206 uint32_t 207 wl_proxy_get_version(struct wl_proxy *proxy); 208 209 uint32_t 210 wl_proxy_get_id(struct wl_proxy *proxy); 211 212 void 213 wl_proxy_set_tag(struct wl_proxy *proxy, 214 const char * const *tag); 215 216 const char * const * 217 wl_proxy_get_tag(struct wl_proxy *proxy); 218 219 const char * 220 wl_proxy_get_class(struct wl_proxy *proxy); 221 222 void 223 wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue); 224 225 struct wl_proxy * 226 wl_proxy_from_object(struct wl_object *object); 227 228 struct wl_display * 229 wl_display_connect(const char *name); 230 231 struct wl_display * 232 wl_display_connect_to_fd(int fd); 233 234 void 235 wl_display_disconnect(struct wl_display *display); 236 237 int 238 wl_display_get_fd(struct wl_display *display); 239 240 int 241 wl_display_dispatch(struct wl_display *display); 242 243 int 244 wl_display_dispatch_queue(struct wl_display *display, 245 struct wl_event_queue *queue); 246 247 int 248 wl_display_dispatch_queue_pending(struct wl_display *display, 249 struct wl_event_queue *queue); 250 251 int 252 wl_display_dispatch_pending(struct wl_display *display); 253 254 int 255 wl_display_get_error(struct wl_display *display); 256 257 uint32_t 258 wl_display_get_protocol_error(struct wl_display *display, 259 const struct wl_interface **interface, 260 uint32_t *id); 261 262 int 263 wl_display_flush(struct wl_display *display); 264 265 int 266 wl_display_roundtrip_queue(struct wl_display *display, 267 struct wl_event_queue *queue); 268 269 int 270 wl_display_roundtrip(struct wl_display *display); 271 272 struct wl_event_queue * 273 wl_display_create_queue(struct wl_display *display); 274 275 int 276 wl_display_prepare_read_queue(struct wl_display *display, 277 struct wl_event_queue *queue); 278 279 int 280 wl_display_prepare_read(struct wl_display *display); 281 282 void 283 wl_display_cancel_read(struct wl_display *display); 284 285 int 286 wl_display_read_events(struct wl_display *display); 287 288 void 289 wl_log_set_handler_client(wl_log_func_t handler); 290 291 /** 292 * The message type. 293 */ 294 enum wl_client_message_type { 295 /** The message is a request */ 296 WL_CLIENT_MESSAGE_REQUEST, 297 298 /** The message is an event */ 299 WL_CLIENT_MESSAGE_EVENT, 300 }; 301 302 /** 303 * The message discard reason codes. 304 */ 305 enum wl_client_message_discarded_reason { 306 /** The message was handled normally, and not discarded. */ 307 WL_CLIENT_MESSAGE_NOT_DISCARDED = 0, 308 309 /** The target was not alive at dispatch time */ 310 WL_CLIENT_MESSAGE_DISCARD_DEAD_PROXY_ON_DISPATCH, 311 312 /** The target had no listener or dispatcher */ 313 WL_CLIENT_MESSAGE_DISCARD_NO_LISTENER_ON_DISPATCH, 314 315 /** The target was not valid when the event was demarshalled */ 316 WL_CLIENT_MESSAGE_DISCARD_UNKNOWN_ID_ON_DEMARSHAL, 317 }; 318 319 /** 320 * The structure used to communicate details about an observed message to the 321 * registered observers. 322 */ 323 struct wl_client_observed_message { 324 /** The target for the message */ 325 struct wl_proxy *proxy; 326 327 /** The message opcode */ 328 int message_opcode; 329 330 /** The protocol message structure */ 331 const struct wl_message *message; 332 333 /** The count of arguments to the message */ 334 int arguments_count; 335 336 /** The argument array for the messagge */ 337 const union wl_argument *arguments; 338 339 /** The discard reason code */ 340 enum wl_client_message_discarded_reason discarded_reason; 341 342 /** 343 * The discard reason string, or NULL if the event was not discarded. 344 * 345 * This string is only for convenience for a observer that does 346 * logging. The string values should not be considered stable, and 347 * are not localized. 348 */ 349 const char *discarded_reason_str; 350 }; 351 352 /** 353 * The signature for a client message observer function, as registered with 354 * wl_display_add_client_observer(). 355 * 356 * \param user_data \c user_data pointer given when the observer was 357 * registered with \c wl_display_create_client_observer 358 * \param type type of message 359 * \param message details for the message 360 */ 361 typedef void (*wl_client_message_observer_func_t)( 362 void *user_data, enum wl_client_message_type type, 363 const struct wl_client_observed_message *message); 364 365 /** \class wl_client_observer 366 * 367 * \brief Represents a client message observer 368 * 369 * A client observer allows the client to observe all request and event 370 * message traffic to and from the client. For events, the observer is 371 * also given a discard reason if the event wasn't handled. 372 * 373 * The typical use for the observer is to allow the client implementation to 374 * do its own debug logging, as the default when setting WAYLAND_DEBUG is to 375 * log to stderr. 376 * 377 * With this runtime call, the client can also enable and disable the observer 378 * at any time. 379 * 380 * The protocol-logger-test.c file has an example of a logger implementation. 381 */ 382 struct wl_client_observer; 383 384 struct wl_client_observer * 385 wl_display_create_client_observer(struct wl_display *display, 386 wl_client_message_observer_func_t observer, 387 void *user_data); 388 389 void 390 wl_client_observer_destroy(struct wl_client_observer *observer); 391 392 #ifdef __cplusplus 393 } 394 #endif 395 396 #endif 397