1 | /* |
2 | * Copyright (C) 2001-2006 Bart Massey, Jamey Sharp, and Josh Triplett. |
3 | * All Rights Reserved. |
4 | * |
5 | * Permission is hereby granted, free of charge, to any person obtaining a |
6 | * copy of this software and associated documentation files (the "Software"), |
7 | * to deal in the Software without restriction, including without limitation |
8 | * the rights to use, copy, modify, merge, publish, distribute, sublicense, |
9 | * and/or sell copies of the Software, and to permit persons to whom the |
10 | * Software is furnished to do so, subject to the following conditions: |
11 | * |
12 | * The above copyright notice and this permission notice shall be included in |
13 | * all copies or substantial portions of the Software. |
14 | * |
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
16 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
18 | * AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN |
19 | * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
20 | * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
21 | * |
22 | * Except as contained in this notice, the names of the authors or their |
23 | * institutions shall not be used in advertising or otherwise to promote the |
24 | * sale, use or other dealings in this Software without prior written |
25 | * authorization from the authors. |
26 | */ |
27 | |
28 | #ifndef __XCB_H__ |
29 | #define __XCB_H__ |
30 | #include <sys/types.h> |
31 | |
32 | #if defined(__solaris__) |
33 | #include <inttypes.h> |
34 | #else |
35 | #include <stdint.h> |
36 | #endif |
37 | |
38 | #ifndef _WIN32 |
39 | #include <sys/uio.h> |
40 | #else |
41 | #include "xcb_windefs.h" |
42 | #endif |
43 | #include <pthread.h> |
44 | |
45 | |
46 | #ifdef __cplusplus |
47 | extern "C" { |
48 | #endif |
49 | |
50 | /** |
51 | * @file xcb.h |
52 | */ |
53 | |
54 | #define XCB_PACKED __attribute__((__packed__)) |
55 | |
56 | /** |
57 | * @defgroup XCB_Core_API XCB Core API |
58 | * @brief Core API of the XCB library. |
59 | * |
60 | * @{ |
61 | */ |
62 | |
63 | /* Pre-defined constants */ |
64 | |
65 | /** Current protocol version */ |
66 | #define X_PROTOCOL 11 |
67 | |
68 | /** Current minor version */ |
69 | #define X_PROTOCOL_REVISION 0 |
70 | |
71 | /** X_TCP_PORT + display number = server port for TCP transport */ |
72 | #define X_TCP_PORT 6000 |
73 | |
74 | /** xcb connection errors because of socket, pipe and other stream errors. */ |
75 | #define XCB_CONN_ERROR 1 |
76 | |
77 | /** xcb connection shutdown because of extension not supported */ |
78 | #define XCB_CONN_CLOSED_EXT_NOTSUPPORTED 2 |
79 | |
80 | /** malloc(), calloc() and realloc() error upon failure, for eg ENOMEM */ |
81 | #define XCB_CONN_CLOSED_MEM_INSUFFICIENT 3 |
82 | |
83 | /** Connection closed, exceeding request length that server accepts. */ |
84 | #define XCB_CONN_CLOSED_REQ_LEN_EXCEED 4 |
85 | |
86 | /** Connection closed, error during parsing display string. */ |
87 | #define XCB_CONN_CLOSED_PARSE_ERR 5 |
88 | |
89 | /** Connection closed because the server does not have a screen matching the display. */ |
90 | #define XCB_CONN_CLOSED_INVALID_SCREEN 6 |
91 | |
92 | /** Connection closed because some FD passing operation failed */ |
93 | #define XCB_CONN_CLOSED_FDPASSING_FAILED 7 |
94 | |
95 | #define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1)) |
96 | |
97 | /* Opaque structures */ |
98 | |
99 | /** |
100 | * @brief XCB Connection structure. |
101 | * |
102 | * A structure that contain all data that XCB needs to communicate with an X server. |
103 | */ |
104 | typedef struct xcb_connection_t xcb_connection_t; /**< Opaque structure containing all data that XCB needs to communicate with an X server. */ |
105 | |
106 | |
107 | /* Other types */ |
108 | |
109 | /** |
110 | * @brief Generic iterator. |
111 | * |
112 | * A generic iterator structure. |
113 | */ |
114 | typedef struct { |
115 | void *data; /**< Data of the current iterator */ |
116 | int rem; /**< remaining elements */ |
117 | int index; /**< index of the current iterator */ |
118 | } xcb_generic_iterator_t; |
119 | |
120 | /** |
121 | * @brief Generic reply. |
122 | * |
123 | * A generic reply structure. |
124 | */ |
125 | typedef struct { |
126 | uint8_t response_type; /**< Type of the response */ |
127 | uint8_t pad0; /**< Padding */ |
128 | uint16_t sequence; /**< Sequence number */ |
129 | uint32_t length; /**< Length of the response */ |
130 | } xcb_generic_reply_t; |
131 | |
132 | /** |
133 | * @brief Generic event. |
134 | * |
135 | * A generic event structure. |
136 | */ |
137 | typedef struct { |
138 | uint8_t response_type; /**< Type of the response */ |
139 | uint8_t pad0; /**< Padding */ |
140 | uint16_t sequence; /**< Sequence number */ |
141 | uint32_t pad[7]; /**< Padding */ |
142 | uint32_t full_sequence; /**< full sequence */ |
143 | } xcb_generic_event_t; |
144 | |
145 | /** |
146 | * @brief GE event |
147 | * |
148 | * An event as sent by the XGE extension. The length field specifies the |
149 | * number of 4-byte blocks trailing the struct. |
150 | * |
151 | * @deprecated Since some fields in this struct have unfortunate names, it is |
152 | * recommended to use xcb_ge_generic_event_t instead. |
153 | */ |
154 | typedef struct { |
155 | uint8_t response_type; /**< Type of the response */ |
156 | uint8_t pad0; /**< Padding */ |
157 | uint16_t sequence; /**< Sequence number */ |
158 | uint32_t length; |
159 | uint16_t event_type; |
160 | uint16_t pad1; |
161 | uint32_t pad[5]; /**< Padding */ |
162 | uint32_t full_sequence; /**< full sequence */ |
163 | } xcb_ge_event_t; |
164 | |
165 | /** |
166 | * @brief Generic error. |
167 | * |
168 | * A generic error structure. |
169 | */ |
170 | typedef struct { |
171 | uint8_t response_type; /**< Type of the response */ |
172 | uint8_t error_code; /**< Error code */ |
173 | uint16_t sequence; /**< Sequence number */ |
174 | uint32_t resource_id; /** < Resource ID for requests with side effects only */ |
175 | uint16_t minor_code; /** < Minor opcode of the failed request */ |
176 | uint8_t major_code; /** < Major opcode of the failed request */ |
177 | uint8_t pad0; |
178 | uint32_t pad[5]; /**< Padding */ |
179 | uint32_t full_sequence; /**< full sequence */ |
180 | } xcb_generic_error_t; |
181 | |
182 | /** |
183 | * @brief Generic cookie. |
184 | * |
185 | * A generic cookie structure. |
186 | */ |
187 | typedef struct { |
188 | unsigned int sequence; /**< Sequence number */ |
189 | } xcb_void_cookie_t; |
190 | |
191 | |
192 | /* Include the generated xproto header. */ |
193 | #include "xproto.h" |
194 | |
195 | |
196 | /** XCB_NONE is the universal null resource or null atom parameter value for many core X requests */ |
197 | #define XCB_NONE 0L |
198 | |
199 | /** XCB_COPY_FROM_PARENT can be used for many xcb_create_window parameters */ |
200 | #define XCB_COPY_FROM_PARENT 0L |
201 | |
202 | /** XCB_CURRENT_TIME can be used in most requests that take an xcb_timestamp_t */ |
203 | #define XCB_CURRENT_TIME 0L |
204 | |
205 | /** XCB_NO_SYMBOL fills in unused entries in xcb_keysym_t tables */ |
206 | #define XCB_NO_SYMBOL 0L |
207 | |
208 | |
209 | /* xcb_auth.c */ |
210 | |
211 | /** |
212 | * @brief Container for authorization information. |
213 | * |
214 | * A container for authorization information to be sent to the X server. |
215 | */ |
216 | typedef struct xcb_auth_info_t { |
217 | int namelen; /**< Length of the string name (as returned by strlen). */ |
218 | char *name; /**< String containing the authentication protocol name, such as "MIT-MAGIC-COOKIE-1" or "XDM-AUTHORIZATION-1". */ |
219 | int datalen; /**< Length of the data member. */ |
220 | char *data; /**< Data interpreted in a protocol-specific manner. */ |
221 | } xcb_auth_info_t; |
222 | |
223 | |
224 | /* xcb_out.c */ |
225 | |
226 | /** |
227 | * @brief Forces any buffered output to be written to the server. |
228 | * @param c: The connection to the X server. |
229 | * @return > @c 0 on success, <= @c 0 otherwise. |
230 | * |
231 | * Forces any buffered output to be written to the server. Blocks |
232 | * until the write is complete. |
233 | */ |
234 | int xcb_flush(xcb_connection_t *c); |
235 | |
236 | /** |
237 | * @brief Returns the maximum request length that this server accepts. |
238 | * @param c: The connection to the X server. |
239 | * @return The maximum request length field. |
240 | * |
241 | * In the absence of the BIG-REQUESTS extension, returns the |
242 | * maximum request length field from the connection setup data, which |
243 | * may be as much as 65535. If the server supports BIG-REQUESTS, then |
244 | * the maximum request length field from the reply to the |
245 | * BigRequestsEnable request will be returned instead. |
246 | * |
247 | * Note that this length is measured in four-byte units, making the |
248 | * theoretical maximum lengths roughly 256kB without BIG-REQUESTS and |
249 | * 16GB with. |
250 | */ |
251 | uint32_t xcb_get_maximum_request_length(xcb_connection_t *c); |
252 | |
253 | /** |
254 | * @brief Prefetch the maximum request length without blocking. |
255 | * @param c: The connection to the X server. |
256 | * |
257 | * Without blocking, does as much work as possible toward computing |
258 | * the maximum request length accepted by the X server. |
259 | * |
260 | * Invoking this function may cause a call to xcb_big_requests_enable, |
261 | * but will not block waiting for the reply. |
262 | * xcb_get_maximum_request_length will return the prefetched data |
263 | * after possibly blocking while the reply is retrieved. |
264 | * |
265 | * Note that in order for this function to be fully non-blocking, the |
266 | * application must previously have called |
267 | * xcb_prefetch_extension_data(c, &xcb_big_requests_id) and the reply |
268 | * must have already arrived. |
269 | */ |
270 | void xcb_prefetch_maximum_request_length(xcb_connection_t *c); |
271 | |
272 | |
273 | /* xcb_in.c */ |
274 | |
275 | /** |
276 | * @brief Returns the next event or error from the server. |
277 | * @param c: The connection to the X server. |
278 | * @return The next event from the server. |
279 | * |
280 | * Returns the next event or error from the server, or returns null in |
281 | * the event of an I/O error. Blocks until either an event or error |
282 | * arrive, or an I/O error occurs. |
283 | */ |
284 | xcb_generic_event_t *xcb_wait_for_event(xcb_connection_t *c); |
285 | |
286 | /** |
287 | * @brief Returns the next event or error from the server. |
288 | * @param c: The connection to the X server. |
289 | * @return The next event from the server. |
290 | * |
291 | * Returns the next event or error from the server, if one is |
292 | * available, or returns @c NULL otherwise. If no event is available, that |
293 | * might be because an I/O error like connection close occurred while |
294 | * attempting to read the next event, in which case the connection is |
295 | * shut down when this function returns. |
296 | */ |
297 | xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c); |
298 | |
299 | /** |
300 | * @brief Returns the next event without reading from the connection. |
301 | * @param c: The connection to the X server. |
302 | * @return The next already queued event from the server. |
303 | * |
304 | * This is a version of xcb_poll_for_event that only examines the |
305 | * event queue for new events. The function doesn't try to read new |
306 | * events from the connection if no queued events are found. |
307 | * |
308 | * This function is useful for callers that know in advance that all |
309 | * interesting events have already been read from the connection. For |
310 | * example, callers might use xcb_wait_for_reply and be interested |
311 | * only of events that preceded a specific reply. |
312 | */ |
313 | xcb_generic_event_t *xcb_poll_for_queued_event(xcb_connection_t *c); |
314 | |
315 | typedef struct xcb_special_event xcb_special_event_t; |
316 | |
317 | /** |
318 | * @brief Returns the next event from a special queue |
319 | */ |
320 | xcb_generic_event_t *xcb_poll_for_special_event(xcb_connection_t *c, |
321 | xcb_special_event_t *se); |
322 | |
323 | /** |
324 | * @brief Returns the next event from a special queue, blocking until one arrives |
325 | */ |
326 | xcb_generic_event_t *xcb_wait_for_special_event(xcb_connection_t *c, |
327 | xcb_special_event_t *se); |
328 | /** |
329 | * @typedef typedef struct xcb_extension_t xcb_extension_t |
330 | */ |
331 | typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as key for xcb_get_extension_data_t. */ |
332 | |
333 | |
334 | /** |
335 | * @brief Listen for a special event |
336 | */ |
337 | xcb_special_event_t *xcb_register_for_special_xge(xcb_connection_t *c, |
338 | xcb_extension_t *ext, |
339 | uint32_t eid, |
340 | uint32_t *stamp); |
341 | |
342 | /** |
343 | * @brief Stop listening for a special event |
344 | */ |
345 | void xcb_unregister_for_special_event(xcb_connection_t *c, |
346 | xcb_special_event_t *se); |
347 | |
348 | /** |
349 | * @brief Return the error for a request, or NULL if none can ever arrive. |
350 | * @param c: The connection to the X server. |
351 | * @param cookie: The request cookie. |
352 | * @return The error for the request, or NULL if none can ever arrive. |
353 | * |
354 | * The xcb_void_cookie_t cookie supplied to this function must have resulted |
355 | * from a call to xcb_[request_name]_checked(). This function will block |
356 | * until one of two conditions happens. If an error is received, it will be |
357 | * returned. If a reply to a subsequent request has already arrived, no error |
358 | * can arrive for this request, so this function will return NULL. |
359 | * |
360 | * Note that this function will perform a sync if needed to ensure that the |
361 | * sequence number will advance beyond that provided in cookie; this is a |
362 | * convenience to avoid races in determining whether the sync is needed. |
363 | */ |
364 | xcb_generic_error_t *xcb_request_check(xcb_connection_t *c, xcb_void_cookie_t cookie); |
365 | |
366 | /** |
367 | * @brief Discards the reply for a request. |
368 | * @param c: The connection to the X server. |
369 | * @param sequence: The request sequence number from a cookie. |
370 | * |
371 | * Discards the reply for a request. Additionally, any error generated |
372 | * by the request is also discarded (unless it was an _unchecked request |
373 | * and the error has already arrived). |
374 | * |
375 | * This function will not block even if the reply is not yet available. |
376 | * |
377 | * Note that the sequence really does have to come from an xcb cookie; |
378 | * this function is not designed to operate on socket-handoff replies. |
379 | */ |
380 | void xcb_discard_reply(xcb_connection_t *c, unsigned int sequence); |
381 | |
382 | |
383 | /* xcb_ext.c */ |
384 | |
385 | /** |
386 | * @brief Caches reply information from QueryExtension requests. |
387 | * @param c: The connection. |
388 | * @param ext: The extension data. |
389 | * @return A pointer to the xcb_query_extension_reply_t for the extension. |
390 | * |
391 | * This function is the primary interface to the "extension cache", |
392 | * which caches reply information from QueryExtension |
393 | * requests. Invoking this function may cause a call to |
394 | * xcb_query_extension to retrieve extension information from the |
395 | * server, and may block until extension data is received from the |
396 | * server. |
397 | * |
398 | * The result must not be freed. This storage is managed by the cache |
399 | * itself. |
400 | */ |
401 | const xcb_query_extension_reply_t *xcb_get_extension_data(xcb_connection_t *c, xcb_extension_t *ext); |
402 | |
403 | /** |
404 | * @brief Prefetch of extension data into the extension cache |
405 | * @param c: The connection. |
406 | * @param ext: The extension data. |
407 | * |
408 | * This function allows a "prefetch" of extension data into the |
409 | * extension cache. Invoking the function may cause a call to |
410 | * xcb_query_extension, but will not block waiting for the |
411 | * reply. xcb_get_extension_data will return the prefetched data after |
412 | * possibly blocking while it is retrieved. |
413 | */ |
414 | void xcb_prefetch_extension_data(xcb_connection_t *c, xcb_extension_t *ext); |
415 | |
416 | |
417 | /* xcb_conn.c */ |
418 | |
419 | /** |
420 | * @brief Access the data returned by the server. |
421 | * @param c: The connection. |
422 | * @return A pointer to an xcb_setup_t structure. |
423 | * |
424 | * Accessor for the data returned by the server when the xcb_connection_t |
425 | * was initialized. This data includes |
426 | * - the server's required format for images, |
427 | * - a list of available visuals, |
428 | * - a list of available screens, |
429 | * - the server's maximum request length (in the absence of the |
430 | * BIG-REQUESTS extension), |
431 | * - and other assorted information. |
432 | * |
433 | * See the X protocol specification for more details. |
434 | * |
435 | * The result must not be freed. |
436 | */ |
437 | const xcb_setup_t *xcb_get_setup(xcb_connection_t *c); |
438 | |
439 | /** |
440 | * @brief Access the file descriptor of the connection. |
441 | * @param c: The connection. |
442 | * @return The file descriptor. |
443 | * |
444 | * Accessor for the file descriptor that was passed to the |
445 | * xcb_connect_to_fd call that returned @p c. |
446 | */ |
447 | int xcb_get_file_descriptor(xcb_connection_t *c); |
448 | |
449 | /** |
450 | * @brief Test whether the connection has shut down due to a fatal error. |
451 | * @param c: The connection. |
452 | * @return > 0 if the connection is in an error state; 0 otherwise. |
453 | * |
454 | * Some errors that occur in the context of an xcb_connection_t |
455 | * are unrecoverable. When such an error occurs, the |
456 | * connection is shut down and further operations on the |
457 | * xcb_connection_t have no effect. |
458 | * |
459 | * @return XCB_CONN_ERROR, because of socket errors, pipe errors or other stream errors. |
460 | * @return XCB_CONN_CLOSED_EXT_NOTSUPPORTED, when extension not supported. |
461 | * @return XCB_CONN_CLOSED_MEM_INSUFFICIENT, when memory not available. |
462 | * @return XCB_CONN_CLOSED_REQ_LEN_EXCEED, exceeding request length that server accepts. |
463 | * @return XCB_CONN_CLOSED_PARSE_ERR, error during parsing display string. |
464 | * @return XCB_CONN_CLOSED_INVALID_SCREEN, because the server does not have a screen matching the display. |
465 | */ |
466 | int xcb_connection_has_error(xcb_connection_t *c); |
467 | |
468 | /** |
469 | * @brief Connects to the X server. |
470 | * @param fd: The file descriptor. |
471 | * @param auth_info: Authentication data. |
472 | * @return A newly allocated xcb_connection_t structure. |
473 | * |
474 | * Connects to an X server, given the open socket @p fd and the |
475 | * xcb_auth_info_t @p auth_info. The file descriptor @p fd is |
476 | * bidirectionally connected to an X server. If the connection |
477 | * should be unauthenticated, @p auth_info must be @c |
478 | * NULL. |
479 | */ |
480 | xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info); |
481 | |
482 | /** |
483 | * @brief Closes the connection. |
484 | * @param c: The connection. |
485 | * |
486 | * Closes the file descriptor and frees all memory associated with the |
487 | * connection @c c. |
488 | */ |
489 | void xcb_disconnect(xcb_connection_t *c); |
490 | |
491 | |
492 | /* xcb_util.c */ |
493 | |
494 | /** |
495 | * @brief Parses a display string name in the form documented by X(7x). |
496 | * @param name: The name of the display. |
497 | * @param host: A pointer to a malloc'd copy of the hostname. |
498 | * @param display: A pointer to the display number. |
499 | * @param screen: A pointer to the screen number. |
500 | * @return 0 on failure, non 0 otherwise. |
501 | * |
502 | * Parses the display string name @p display_name in the form |
503 | * documented by X(7x). Has no side effects on failure. If |
504 | * @p displayname is @c NULL or empty, it uses the environment |
505 | * variable DISPLAY. @p hostp is a pointer to a newly allocated string |
506 | * that contain the host name. @p displayp is set to the display |
507 | * number and @p screenp to the preferred screen number. @p screenp |
508 | * can be @c NULL. If @p displayname does not contain a screen number, |
509 | * it is set to @c 0. |
510 | */ |
511 | int xcb_parse_display(const char *name, char **host, int *display, int *screen); |
512 | |
513 | /** |
514 | * @brief Connects to the X server. |
515 | * @param displayname: The name of the display. |
516 | * @param screenp: A pointer to a preferred screen number. |
517 | * @return A newly allocated xcb_connection_t structure. |
518 | * |
519 | * Connects to the X server specified by @p displayname. If @p |
520 | * displayname is @c NULL, uses the value of the DISPLAY environment |
521 | * variable. If a particular screen on that server is preferred, the |
522 | * int pointed to by @p screenp (if not @c NULL) will be set to that |
523 | * screen; otherwise the screen will be set to 0. |
524 | */ |
525 | xcb_connection_t *xcb_connect(const char *displayname, int *screenp); |
526 | |
527 | /** |
528 | * @brief Connects to the X server, using an authorization information. |
529 | * @param display: The name of the display. |
530 | * @param auth: The authorization information. |
531 | * @param screen: A pointer to a preferred screen number. |
532 | * @return A newly allocated xcb_connection_t structure. |
533 | * |
534 | * Connects to the X server specified by @p displayname, using the |
535 | * authorization @p auth. If a particular screen on that server is |
536 | * preferred, the int pointed to by @p screenp (if not @c NULL) will |
537 | * be set to that screen; otherwise @p screenp will be set to 0. |
538 | */ |
539 | xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen); |
540 | |
541 | |
542 | /* xcb_xid.c */ |
543 | |
544 | /** |
545 | * @brief Allocates an XID for a new object. |
546 | * @param c: The connection. |
547 | * @return A newly allocated XID. |
548 | * |
549 | * Allocates an XID for a new object. Typically used just prior to |
550 | * various object creation functions, such as xcb_create_window. |
551 | */ |
552 | uint32_t xcb_generate_id(xcb_connection_t *c); |
553 | |
554 | |
555 | /** |
556 | * @} |
557 | */ |
558 | |
559 | #ifdef __cplusplus |
560 | } |
561 | #endif |
562 | |
563 | |
564 | #endif /* __XCB_H__ */ |
565 | |