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 void 123 wl_event_queue_destroy(struct wl_event_queue *queue); 124 125 void 126 wl_proxy_marshal(struct wl_proxy *p, uint32_t opcode, ...); 127 128 void 129 wl_proxy_marshal_array(struct wl_proxy *p, uint32_t opcode, 130 union wl_argument *args); 131 132 struct wl_proxy * 133 wl_proxy_create(struct wl_proxy *factory, 134 const struct wl_interface *interface); 135 136 void * 137 wl_proxy_create_wrapper(void *proxy); 138 139 void 140 wl_proxy_wrapper_destroy(void *proxy_wrapper); 141 142 struct wl_proxy * 143 wl_proxy_marshal_constructor(struct wl_proxy *proxy, 144 uint32_t opcode, 145 const struct wl_interface *interface, 146 ...); 147 148 struct wl_proxy * 149 wl_proxy_marshal_constructor_versioned(struct wl_proxy *proxy, 150 uint32_t opcode, 151 const struct wl_interface *interface, 152 uint32_t version, 153 ...); 154 155 struct wl_proxy * 156 wl_proxy_marshal_array_constructor(struct wl_proxy *proxy, 157 uint32_t opcode, union wl_argument *args, 158 const struct wl_interface *interface); 159 160 struct wl_proxy * 161 wl_proxy_marshal_array_constructor_versioned(struct wl_proxy *proxy, 162 uint32_t opcode, 163 union wl_argument *args, 164 const struct wl_interface *interface, 165 uint32_t version); 166 167 void 168 wl_proxy_destroy(struct wl_proxy *proxy); 169 170 int 171 wl_proxy_add_listener(struct wl_proxy *proxy, 172 void (**implementation)(void), void *data); 173 174 const void * 175 wl_proxy_get_listener(struct wl_proxy *proxy); 176 177 int 178 wl_proxy_add_dispatcher(struct wl_proxy *proxy, 179 wl_dispatcher_func_t dispatcher_func, 180 const void * dispatcher_data, void *data); 181 182 void 183 wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data); 184 185 void * 186 wl_proxy_get_user_data(struct wl_proxy *proxy); 187 188 uint32_t 189 wl_proxy_get_version(struct wl_proxy *proxy); 190 191 uint32_t 192 wl_proxy_get_id(struct wl_proxy *proxy); 193 194 void 195 wl_proxy_set_tag(struct wl_proxy *proxy, 196 const char * const *tag); 197 198 const char * const * 199 wl_proxy_get_tag(struct wl_proxy *proxy); 200 201 const char * 202 wl_proxy_get_class(struct wl_proxy *proxy); 203 204 void 205 wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue); 206 207 struct wl_proxy * 208 wl_proxy_from_object(struct wl_object *object); 209 210 struct wl_display * 211 wl_display_connect(const char *name); 212 213 struct wl_display * 214 wl_display_connect_to_fd(int fd); 215 216 void 217 wl_display_disconnect(struct wl_display *display); 218 219 int 220 wl_display_get_fd(struct wl_display *display); 221 222 int 223 wl_display_dispatch(struct wl_display *display); 224 225 int 226 wl_display_dispatch_queue(struct wl_display *display, 227 struct wl_event_queue *queue); 228 229 int 230 wl_display_dispatch_queue_pending(struct wl_display *display, 231 struct wl_event_queue *queue); 232 233 int 234 wl_display_dispatch_pending(struct wl_display *display); 235 236 int 237 wl_display_get_error(struct wl_display *display); 238 239 uint32_t 240 wl_display_get_protocol_error(struct wl_display *display, 241 const struct wl_interface **interface, 242 uint32_t *id); 243 244 int 245 wl_display_flush(struct wl_display *display); 246 247 int 248 wl_display_roundtrip_queue(struct wl_display *display, 249 struct wl_event_queue *queue); 250 251 int 252 wl_display_roundtrip(struct wl_display *display); 253 254 struct wl_event_queue * 255 wl_display_create_queue(struct wl_display *display); 256 257 int 258 wl_display_prepare_read_queue(struct wl_display *display, 259 struct wl_event_queue *queue); 260 261 int 262 wl_display_prepare_read(struct wl_display *display); 263 264 void 265 wl_display_cancel_read(struct wl_display *display); 266 267 int 268 wl_display_read_events(struct wl_display *display); 269 270 void 271 wl_log_set_handler_client(wl_log_func_t handler); 272 273 enum wl_protocol_logger_client_type { 274 WL_PROTOCOL_LOGGER_CLIENT_REQUEST, 275 WL_PROTOCOL_LOGGER_CLIENT_EVENT, 276 }; 277 278 struct wl_protocol_logger_client_message { 279 struct wl_proxy *proxy; 280 int message_opcode; 281 const struct wl_message *message; 282 int arguments_count; 283 const union wl_argument *arguments; 284 }; 285 286 typedef void (*wl_protocol_logger_client_func_t)( 287 void *user_data, 288 enum wl_protocol_logger_client_type direction, 289 const struct wl_protocol_logger_client_message *message); 290 291 struct wl_protocol_logger_client * 292 wl_display_add_protocol_logger_client(struct wl_display *display, 293 wl_protocol_logger_client_func_t, 294 void *user_data); 295 296 void 297 wl_protocol_logger_client_destroy(struct wl_protocol_logger_client *logger); 298 299 #ifdef __cplusplus 300 } 301 #endif 302 303 #endif 304