Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/xcb/xcb.h
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 #ifdef __GNUC__ 55 #define XCB_PACKED __attribute__((__packed__)) 56 #else 57 #define XCB_PACKED 58 #endif 59 60 /** 61 * @defgroup XCB_Core_API XCB Core API 62 * @brief Core API of the XCB library. 63 * 64 * @{ 65 */ 66 67 /* Pre-defined constants */ 68 69 /** Current protocol version */ 70 #define X_PROTOCOL 11 71 72 /** Current minor version */ 73 #define X_PROTOCOL_REVISION 0 74 75 /** X_TCP_PORT + display number = server port for TCP transport */ 76 #define X_TCP_PORT 6000 77 78 /** xcb connection errors because of socket, pipe and other stream errors. */ 79 #define XCB_CONN_ERROR 1 80 81 /** xcb connection shutdown because of extension not supported */ 82 #define XCB_CONN_CLOSED_EXT_NOTSUPPORTED 2 83 84 /** malloc(), calloc() and realloc() error upon failure, for eg ENOMEM */ 85 #define XCB_CONN_CLOSED_MEM_INSUFFICIENT 3 86 87 /** Connection closed, exceeding request length that server accepts. */ 88 #define XCB_CONN_CLOSED_REQ_LEN_EXCEED 4 89 90 /** Connection closed, error during parsing display string. */ 91 #define XCB_CONN_CLOSED_PARSE_ERR 5 92 93 /** Connection closed because the server does not have a screen matching the display. */ 94 #define XCB_CONN_CLOSED_INVALID_SCREEN 6 95 96 /** Connection closed because some FD passing operation failed */ 97 #define XCB_CONN_CLOSED_FDPASSING_FAILED 7 98 99 #define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1)) 100 101 /* Opaque structures */ 102 103 /** 104 * @brief XCB Connection structure. 105 * 106 * A structure that contain all data that XCB needs to communicate with an X server. 107 */ 108 typedef struct xcb_connection_t xcb_connection_t; /**< Opaque structure containing all data that XCB needs to communicate with an X server. */ 109 110 111 /* Other types */ 112 113 /** 114 * @brief Generic iterator. 115 * 116 * A generic iterator structure. 117 */ 118 typedef struct { 119 void *data; /**< Data of the current iterator */ 120 int rem; /**< remaining elements */ 121 int index; /**< index of the current iterator */ 122 } xcb_generic_iterator_t; 123 124 /** 125 * @brief Generic reply. 126 * 127 * A generic reply structure. 128 */ 129 typedef struct { 130 uint8_t response_type; /**< Type of the response */ 131 uint8_t pad0; /**< Padding */ 132 uint16_t sequence; /**< Sequence number */ 133 uint32_t length; /**< Length of the response */ 134 } xcb_generic_reply_t; 135 136 /** 137 * @brief Generic event. 138 * 139 * A generic event structure. 140 */ 141 typedef struct { 142 uint8_t response_type; /**< Type of the response */ 143 uint8_t pad0; /**< Padding */ 144 uint16_t sequence; /**< Sequence number */ 145 uint32_t pad[7]; /**< Padding */ 146 uint32_t full_sequence; /**< full sequence */ 147 } xcb_generic_event_t; 148 149 /** 150 * @brief Raw Generic event. 151 * 152 * A generic event structure as used on the wire, i.e., without the full_sequence field 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 pad[7]; /**< Padding */ 159 } xcb_raw_generic_event_t; 160 161 /** 162 * @brief GE event 163 * 164 * An event as sent by the XGE extension. The length field specifies the 165 * number of 4-byte blocks trailing the struct. 166 * 167 * @deprecated Since some fields in this struct have unfortunate names, it is 168 * recommended to use xcb_ge_generic_event_t instead. 169 */ 170 typedef struct { 171 uint8_t response_type; /**< Type of the response */ 172 uint8_t pad0; /**< Padding */ 173 uint16_t sequence; /**< Sequence number */ 174 uint32_t length; 175 uint16_t event_type; 176 uint16_t pad1; 177 uint32_t pad[5]; /**< Padding */ 178 uint32_t full_sequence; /**< full sequence */ 179 } xcb_ge_event_t; 180 181 /** 182 * @brief Generic error. 183 * 184 * A generic error structure. 185 */ 186 typedef struct { 187 uint8_t response_type; /**< Type of the response */ 188 uint8_t error_code; /**< Error code */ 189 uint16_t sequence; /**< Sequence number */ 190 uint32_t resource_id; /** < Resource ID for requests with side effects only */ 191 uint16_t minor_code; /** < Minor opcode of the failed request */ 192 uint8_t major_code; /** < Major opcode of the failed request */ 193 uint8_t pad0; 194 uint32_t pad[5]; /**< Padding */ 195 uint32_t full_sequence; /**< full sequence */ 196 } xcb_generic_error_t; 197 198 /** 199 * @brief Generic cookie. 200 * 201 * A generic cookie structure. 202 */ 203 typedef struct { 204 unsigned int sequence; /**< Sequence number */ 205 } xcb_void_cookie_t; 206 207 208 /* Include the generated xproto header. */ 209 #include "xproto.h" 210 211 212 /** XCB_NONE is the universal null resource or null atom parameter value for many core X requests */ 213 #define XCB_NONE 0L 214 215 /** XCB_COPY_FROM_PARENT can be used for many xcb_create_window parameters */ 216 #define XCB_COPY_FROM_PARENT 0L 217 218 /** XCB_CURRENT_TIME can be used in most requests that take an xcb_timestamp_t */ 219 #define XCB_CURRENT_TIME 0L 220 221 /** XCB_NO_SYMBOL fills in unused entries in xcb_keysym_t tables */ 222 #define XCB_NO_SYMBOL 0L 223 224 225 /* xcb_auth.c */ 226 227 /** 228 * @brief Container for authorization information. 229 * 230 * A container for authorization information to be sent to the X server. 231 */ 232 typedef struct xcb_auth_info_t { 233 int namelen; /**< Length of the string name (as returned by strlen). */ 234 char *name; /**< String containing the authentication protocol name, such as "MIT-MAGIC-COOKIE-1" or "XDM-AUTHORIZATION-1". */ 235 int datalen; /**< Length of the data member. */ 236 char *data; /**< Data interpreted in a protocol-specific manner. */ 237 } xcb_auth_info_t; 238 239 240 /* xcb_out.c */ 241 242 /** 243 * @brief Forces any buffered output to be written to the server. 244 * @param c The connection to the X server. 245 * @return > @c 0 on success, <= @c 0 otherwise. 246 * 247 * Forces any buffered output to be written to the server. Blocks 248 * until the write is complete. 249 */ 250 int xcb_flush(xcb_connection_t *c); 251 252 /** 253 * @brief Returns the maximum request length that this server accepts. 254 * @param c The connection to the X server. 255 * @return The maximum request length field. 256 * 257 * In the absence of the BIG-REQUESTS extension, returns the 258 * maximum request length field from the connection setup data, which 259 * may be as much as 65535. If the server supports BIG-REQUESTS, then 260 * the maximum request length field from the reply to the 261 * BigRequestsEnable request will be returned instead. 262 * 263 * Note that this length is measured in four-byte units, making the 264 * theoretical maximum lengths roughly 256kB without BIG-REQUESTS and 265 * 16GB with. 266 */ 267 uint32_t xcb_get_maximum_request_length(xcb_connection_t *c); 268 269 /** 270 * @brief Prefetch the maximum request length without blocking. 271 * @param c The connection to the X server. 272 * 273 * Without blocking, does as much work as possible toward computing 274 * the maximum request length accepted by the X server. 275 * 276 * Invoking this function may cause a call to xcb_big_requests_enable, 277 * but will not block waiting for the reply. 278 * xcb_get_maximum_request_length will return the prefetched data 279 * after possibly blocking while the reply is retrieved. 280 * 281 * Note that in order for this function to be fully non-blocking, the 282 * application must previously have called 283 * xcb_prefetch_extension_data(c, &xcb_big_requests_id) and the reply 284 * must have already arrived. 285 */ 286 void xcb_prefetch_maximum_request_length(xcb_connection_t *c); 287 288 289 /* xcb_in.c */ 290 291 /** 292 * @brief Returns the next event or error from the server. 293 * @param c The connection to the X server. 294 * @return The next event from the server. 295 * 296 * Returns the next event or error from the server, or returns null in 297 * the event of an I/O error. Blocks until either an event or error 298 * arrive, or an I/O error occurs. 299 */ 300 xcb_generic_event_t *xcb_wait_for_event(xcb_connection_t *c); 301 302 /** 303 * @brief Returns the next event or error from the server. 304 * @param c The connection to the X server. 305 * @return The next event from the server. 306 * 307 * Returns the next event or error from the server, if one is 308 * available, or returns @c NULL otherwise. If no event is available, that 309 * might be because an I/O error like connection close occurred while 310 * attempting to read the next event, in which case the connection is 311 * shut down when this function returns. 312 */ 313 xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c); 314 315 /** 316 * @brief Returns the next event without reading from the connection. 317 * @param c The connection to the X server. 318 * @return The next already queued event from the server. 319 * 320 * This is a version of xcb_poll_for_event that only examines the 321 * event queue for new events. The function doesn't try to read new 322 * events from the connection if no queued events are found. 323 * 324 * This function is useful for callers that know in advance that all 325 * interesting events have already been read from the connection. For 326 * example, callers might use xcb_wait_for_reply and be interested 327 * only of events that preceded a specific reply. 328 */ 329 xcb_generic_event_t *xcb_poll_for_queued_event(xcb_connection_t *c); 330 331 typedef struct xcb_special_event xcb_special_event_t; 332 333 /** 334 * @brief Returns the next event from a special queue 335 */ 336 xcb_generic_event_t *xcb_poll_for_special_event(xcb_connection_t *c, 337 xcb_special_event_t *se); 338 339 /** 340 * @brief Returns the next event from a special queue, blocking until one arrives 341 */ 342 xcb_generic_event_t *xcb_wait_for_special_event(xcb_connection_t *c, 343 xcb_special_event_t *se); 344 /** 345 * @typedef typedef struct xcb_extension_t xcb_extension_t 346 */ 347 typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as key for xcb_get_extension_data_t. */ 348 349 /** 350 * @brief Listen for a special event 351 */ 352 xcb_special_event_t *xcb_register_for_special_xge(xcb_connection_t *c, 353 xcb_extension_t *ext, 354 uint32_t eid, 355 uint32_t *stamp); 356 357 /** 358 * @brief Stop listening for a special event 359 */ 360 void xcb_unregister_for_special_event(xcb_connection_t *c, 361 xcb_special_event_t *se); 362 363 /** 364 * @brief Return the error for a request, or NULL if none can ever arrive. 365 * @param c The connection to the X server. 366 * @param cookie The request cookie. 367 * @return The error for the request, or NULL if none can ever arrive. 368 * 369 * The xcb_void_cookie_t cookie supplied to this function must have resulted 370 * from a call to xcb_[request_name]_checked(). This function will block 371 * until one of two conditions happens. If an error is received, it will be 372 * returned. If a reply to a subsequent request has already arrived, no error 373 * can arrive for this request, so this function will return NULL. 374 * 375 * Note that this function will perform a sync if needed to ensure that the 376 * sequence number will advance beyond that provided in cookie; this is a 377 * convenience to avoid races in determining whether the sync is needed. 378 */ 379 xcb_generic_error_t *xcb_request_check(xcb_connection_t *c, xcb_void_cookie_t cookie); 380 381 /** 382 * @brief Discards the reply for a request. 383 * @param c The connection to the X server. 384 * @param sequence The request sequence number from a cookie. 385 * 386 * Discards the reply for a request. Additionally, any error generated 387 * by the request is also discarded (unless it was an _unchecked request 388 * and the error has already arrived). 389 * 390 * This function will not block even if the reply is not yet available. 391 * 392 * Note that the sequence really does have to come from an xcb cookie; 393 * this function is not designed to operate on socket-handoff replies. 394 */ 395 void xcb_discard_reply(xcb_connection_t *c, unsigned int sequence); 396 397 /** 398 * @brief Discards the reply for a request, given by a 64bit sequence number 399 * @param c The connection to the X server. 400 * @param sequence 64-bit sequence number as returned by xcb_send_request64(). 401 * 402 * Discards the reply for a request. Additionally, any error generated 403 * by the request is also discarded (unless it was an _unchecked request 404 * and the error has already arrived). 405 * 406 * This function will not block even if the reply is not yet available. 407 * 408 * Note that the sequence really does have to come from xcb_send_request64(); 409 * the cookie sequence number is defined as "unsigned" int and therefore 410 * not 64-bit on all platforms. 411 * This function is not designed to operate on socket-handoff replies. 412 * 413 * Unlike its xcb_discard_reply() counterpart, the given sequence number is not 414 * automatically "widened" to 64-bit. 415 */ 416 void xcb_discard_reply64(xcb_connection_t *c, uint64_t sequence); 417 418 /* xcb_ext.c */ 419 420 /** 421 * @brief Caches reply information from QueryExtension requests. 422 * @param c The connection. 423 * @param ext The extension data. 424 * @return A pointer to the xcb_query_extension_reply_t for the extension. 425 * 426 * This function is the primary interface to the "extension cache", 427 * which caches reply information from QueryExtension 428 * requests. Invoking this function may cause a call to 429 * xcb_query_extension to retrieve extension information from the 430 * server, and may block until extension data is received from the 431 * server. 432 * 433 * The result must not be freed. This storage is managed by the cache 434 * itself. 435 */ 436 const struct xcb_query_extension_reply_t *xcb_get_extension_data(xcb_connection_t *c, xcb_extension_t *ext); 437 438 /** 439 * @brief Prefetch of extension data into the extension cache 440 * @param c The connection. 441 * @param ext The extension data. 442 * 443 * This function allows a "prefetch" of extension data into the 444 * extension cache. Invoking the function may cause a call to 445 * xcb_query_extension, but will not block waiting for the 446 * reply. xcb_get_extension_data will return the prefetched data after 447 * possibly blocking while it is retrieved. 448 */ 449 void xcb_prefetch_extension_data(xcb_connection_t *c, xcb_extension_t *ext); 450 451 452 /* xcb_conn.c */ 453 454 /** 455 * @brief Access the data returned by the server. 456 * @param c The connection. 457 * @return A pointer to an xcb_setup_t structure. 458 * 459 * Accessor for the data returned by the server when the xcb_connection_t 460 * was initialized. This data includes 461 * - the server's required format for images, 462 * - a list of available visuals, 463 * - a list of available screens, 464 * - the server's maximum request length (in the absence of the 465 * BIG-REQUESTS extension), 466 * - and other assorted information. 467 * 468 * See the X protocol specification for more details. 469 * 470 * The result must not be freed. 471 */ 472 const struct xcb_setup_t *xcb_get_setup(xcb_connection_t *c); 473 474 /** 475 * @brief Access the file descriptor of the connection. 476 * @param c The connection. 477 * @return The file descriptor. 478 * 479 * Accessor for the file descriptor that was passed to the 480 * xcb_connect_to_fd call that returned @p c. 481 */ 482 int xcb_get_file_descriptor(xcb_connection_t *c); 483 484 /** 485 * @brief Test whether the connection has shut down due to a fatal error. 486 * @param c The connection. 487 * @return > 0 if the connection is in an error state; 0 otherwise. 488 * 489 * Some errors that occur in the context of an xcb_connection_t 490 * are unrecoverable. When such an error occurs, the 491 * connection is shut down and further operations on the 492 * xcb_connection_t have no effect, but memory will not be freed until 493 * xcb_disconnect() is called on the xcb_connection_t. 494 * 495 * @return XCB_CONN_ERROR, because of socket errors, pipe errors or other stream errors. 496 * @return XCB_CONN_CLOSED_EXT_NOTSUPPORTED, when extension not supported. 497 * @return XCB_CONN_CLOSED_MEM_INSUFFICIENT, when memory not available. 498 * @return XCB_CONN_CLOSED_REQ_LEN_EXCEED, exceeding request length that server accepts. 499 * @return XCB_CONN_CLOSED_PARSE_ERR, error during parsing display string. 500 * @return XCB_CONN_CLOSED_INVALID_SCREEN, because the server does not have a screen matching the display. 501 */ 502 int xcb_connection_has_error(xcb_connection_t *c); 503 504 /** 505 * @brief Connects to the X server. 506 * @param fd The file descriptor. 507 * @param auth_info Authentication data. 508 * @return A newly allocated xcb_connection_t structure. 509 * 510 * Connects to an X server, given the open socket @p fd and the 511 * xcb_auth_info_t @p auth_info. The file descriptor @p fd is 512 * bidirectionally connected to an X server. If the connection 513 * should be unauthenticated, @p auth_info must be @c 514 * NULL. 515 * 516 * Always returns a non-NULL pointer to a xcb_connection_t, even on failure. 517 * Callers need to use xcb_connection_has_error() to check for failure. 518 * When finished, use xcb_disconnect() to close the connection and free 519 * the structure. 520 */ 521 xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info); 522 523 /** 524 * @brief Closes the connection. 525 * @param c The connection. 526 * 527 * Closes the file descriptor and frees all memory associated with the 528 * connection @c c. If @p c is @c NULL, nothing is done. 529 */ 530 void xcb_disconnect(xcb_connection_t *c); 531 532 533 /* xcb_util.c */ 534 535 /** 536 * @brief Parses a display string name in the form documented by X(7x). 537 * @param name The name of the display. 538 * @param host A pointer to a malloc'd copy of the hostname. 539 * @param display A pointer to the display number. 540 * @param screen A pointer to the screen number. 541 * @return 0 on failure, non 0 otherwise. 542 * 543 * Parses the display string name @p display_name in the form 544 * documented by X(7x). Has no side effects on failure. If 545 * @p displayname is @c NULL or empty, it uses the environment 546 * variable DISPLAY. @p hostp is a pointer to a newly allocated string 547 * that contain the host name. @p displayp is set to the display 548 * number and @p screenp to the preferred screen number. @p screenp 549 * can be @c NULL. If @p displayname does not contain a screen number, 550 * it is set to @c 0. 551 */ 552 int xcb_parse_display(const char *name, char **host, int *display, int *screen); 553 554 /** 555 * @brief Connects to the X server. 556 * @param displayname The name of the display. 557 * @param screenp A pointer to a preferred screen number. 558 * @return A newly allocated xcb_connection_t structure. 559 * 560 * Connects to the X server specified by @p displayname. If @p 561 * displayname is @c NULL, uses the value of the DISPLAY environment 562 * variable. If a particular screen on that server is preferred, the 563 * int pointed to by @p screenp (if not @c NULL) will be set to that 564 * screen; otherwise the screen will be set to 0. 565 * 566 * Always returns a non-NULL pointer to a xcb_connection_t, even on failure. 567 * Callers need to use xcb_connection_has_error() to check for failure. 568 * When finished, use xcb_disconnect() to close the connection and free 569 * the structure. 570 */ 571 xcb_connection_t *xcb_connect(const char *displayname, int *screenp); 572 573 /** 574 * @brief Connects to the X server, using an authorization information. 575 * @param display The name of the display. 576 * @param auth The authorization information. 577 * @param screen A pointer to a preferred screen number. 578 * @return A newly allocated xcb_connection_t structure. 579 * 580 * Connects to the X server specified by @p displayname, using the 581 * authorization @p auth. If a particular screen on that server is 582 * preferred, the int pointed to by @p screenp (if not @c NULL) will 583 * be set to that screen; otherwise @p screenp will be set to 0. 584 * 585 * Always returns a non-NULL pointer to a xcb_connection_t, even on failure. 586 * Callers need to use xcb_connection_has_error() to check for failure. 587 * When finished, use xcb_disconnect() to close the connection and free 588 * the structure. 589 */ 590 xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen); 591 592 593 /* xcb_xid.c */ 594 595 /** 596 * @brief Allocates an XID for a new object. 597 * @param c The connection. 598 * @return A newly allocated XID, or -1 on failure. 599 * 600 * Allocates an XID for a new object. Typically used just prior to 601 * various object creation functions, such as xcb_create_window. 602 */ 603 uint32_t xcb_generate_id(xcb_connection_t *c); 604 605 606 /** 607 * @brief Obtain number of bytes read from the connection. 608 * @param c The connection 609 * @return Number of bytes read from the server. 610 * 611 * Returns cumulative number of bytes received from the connection. 612 * 613 * This retrieves the total number of bytes read from this connection, 614 * to be used for diagnostic/monitoring/informative purposes. 615 */ 616 617 uint64_t 618 xcb_total_read(xcb_connection_t *c); 619 620 /** 621 * 622 * @brief Obtain number of bytes written to the connection. 623 * @param c The connection 624 * @return Number of bytes written to the server. 625 * 626 * Returns cumulative number of bytes sent to the connection. 627 * 628 * This retrieves the total number of bytes written to this connection, 629 * to be used for diagnostic/monitoring/informative purposes. 630 */ 631 632 uint64_t 633 xcb_total_written(xcb_connection_t *c); 634 635 /** 636 * @} 637 */ 638 639 #ifdef __cplusplus 640 } 641 #endif 642 643 644 #endif /* __XCB_H__ */
