1 /* 2 * Copyright 2008 Kristian Hgsberg 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 const char * 195 wl_proxy_get_class(struct wl_proxy *proxy); 196 197 void 198 wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue); 199 200 struct wl_display * 201 wl_display_connect(const char *name); 202 203 struct wl_display * 204 wl_display_connect_to_fd(int fd); 205 206 void 207 wl_display_disconnect(struct wl_display *display); 208 209 int 210 wl_display_get_fd(struct wl_display *display); 211 212 int 213 wl_display_dispatch(struct wl_display *display); 214 215 int 216 wl_display_dispatch_queue(struct wl_display *display, 217 struct wl_event_queue *queue); 218 219 int 220 wl_display_dispatch_queue_pending(struct wl_display *display, 221 struct wl_event_queue *queue); 222 223 int 224 wl_display_dispatch_pending(struct wl_display *display); 225 226 int 227 wl_display_get_error(struct wl_display *display); 228 229 uint32_t 230 wl_display_get_protocol_error(struct wl_display *display, 231 const struct wl_interface **interface, 232 uint32_t *id); 233 234 int 235 wl_display_flush(struct wl_display *display); 236 237 int 238 wl_display_roundtrip_queue(struct wl_display *display, 239 struct wl_event_queue *queue); 240 241 int 242 wl_display_roundtrip(struct wl_display *display); 243 244 struct wl_event_queue * 245 wl_display_create_queue(struct wl_display *display); 246 247 int 248 wl_display_prepare_read_queue(struct wl_display *display, 249 struct wl_event_queue *queue); 250 251 int 252 wl_display_prepare_read(struct wl_display *display); 253 254 void 255 wl_display_cancel_read(struct wl_display *display); 256 257 int 258 wl_display_read_events(struct wl_display *display); 259 260 void 261 wl_log_set_handler_client(wl_log_func_t handler); 262 263 #ifdef __cplusplus 264 } 265 #endif 266 267 #endif 268
