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#include <sys/uio.h> 39#include <pthread.h> 40 41 42#ifdef __cplusplus 43extern "C" { 44#endif 45 46/** 47 * @file xcb.h 48 */ 49 50/** 51 * @defgroup XCB_Core_API XCB Core API 52 * @brief Core API of the XCB library. 53 * 54 * @{ 55 */ 56 57/* Pre-defined constants */ 58 59/** Current protocol version */ 60#define X_PROTOCOL 11 61 62/** Current minor version */ 63#define X_PROTOCOL_REVISION 0 64 65/** X_TCP_PORT + display number = server port for TCP transport */ 66#define X_TCP_PORT 6000 67 68#define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1)) 69 70/* Opaque structures */ 71 72/** 73 * @brief XCB Connection structure. 74 * 75 * A structure that contain all data that XCB needs to communicate with an X server. 76 */ 77typedef struct xcb_connection_t xcb_connection_t; /**< Opaque structure containing all data that XCB needs to communicate with an X server. */ 78 79 80/* Other types */ 81 82/** 83 * @brief Generic iterator. 84 * 85 * A generic iterator structure. 86 */ 87typedef struct { 88 void *data; /**< Data of the current iterator */ 89 int rem; /**< remaining elements */ 90 int index; /**< index of the current iterator */ 91} xcb_generic_iterator_t; 92 93/** 94 * @brief Generic reply. 95 * 96 * A generic reply structure. 97 */ 98typedef struct { 99 uint8_t response_type; /**< Type of the response */ 100 uint8_t pad0; /**< Padding */ 101 uint16_t sequence; /**< Sequence number */ 102 uint32_t length; /**< Length of the response */ 103} xcb_generic_reply_t; 104 105/** 106 * @brief Generic event. 107 * 108 * A generic event structure. 109 */ 110typedef struct { 111 uint8_t response_type; /**< Type of the response */ 112 uint8_t pad0; /**< Padding */ 113 uint16_t sequence; /**< Sequence number */ 114 uint32_t pad[7]; /**< Padding */ 115 uint32_t full_sequence; /**< full sequence */ 116} xcb_generic_event_t; 117 118/** 119 * @brief GE event 120 * 121 * An event as sent by the XGE extension. The length field specifies the 122 * number of 4-byte blocks trailing the struct. 123 */ 124typedef struct { 125 uint8_t response_type; /**< Type of the response */ 126 uint8_t pad0; /**< Padding */ 127 uint16_t sequence; /**< Sequence number */ 128 uint32_t length; 129 uint16_t event_type; 130 uint16_t pad1; 131 uint32_t pad[5]; /**< Padding */ 132 uint32_t full_sequence; /**< full sequence */ 133} xcb_ge_event_t; 134 135/** 136 * @brief Generic error. 137 * 138 * A generic error structure. 139 */ 140typedef struct { 141 uint8_t response_type; /**< Type of the response */ 142 uint8_t error_code; /**< Error code */ 143 uint16_t sequence; /**< Sequence number */ 144 uint32_t resource_id; /** < Resource ID for requests with side effects only */ 145 uint16_t minor_code; /** < Minor opcode of the failed request */ 146 uint8_t major_code; /** < Major opcode of the failed request */ 147 uint8_t pad0; 148 uint32_t pad[5]; /**< Padding */ 149 uint32_t full_sequence; /**< full sequence */ 150} xcb_generic_error_t; 151 152/** 153 * @brief Generic cookie. 154 * 155 * A generic cookie structure. 156 */ 157typedef struct { 158 unsigned int sequence; /**< Sequence number */ 159} xcb_void_cookie_t; 160 161 162/* Include the generated xproto header. */ 163#include "xproto.h" 164 165 166/** XCB_NONE is the universal null resource or null atom parameter value for many core X requests */ 167#define XCB_NONE 0L 168 169/** XCB_COPY_FROM_PARENT can be used for many xcb_create_window parameters */ 170#define XCB_COPY_FROM_PARENT 0L 171 172/** XCB_CURRENT_TIME can be used in most requests that take an xcb_timestamp_t */ 173#define XCB_CURRENT_TIME 0L 174 175/** XCB_NO_SYMBOL fills in unused entries in xcb_keysym_t tables */ 176#define XCB_NO_SYMBOL 0L 177 178 179/* xcb_auth.c */ 180 181/** 182 * @brief Container for authorization information. 183 * 184 * A container for authorization information to be sent to the X server. 185 */ 186typedef struct xcb_auth_info_t { 187 int namelen; /**< Length of the string name (as returned by strlen). */ 188 char *name; /**< String containing the authentication protocol name, such as "MIT-MAGIC-COOKIE-1" or "XDM-AUTHORIZATION-1". */ 189 int datalen; /**< Length of the data member. */ 190 char *data; /**< Data interpreted in a protocol-specific manner. */ 191} xcb_auth_info_t; 192 193 194/* xcb_out.c */ 195 196/** 197 * @brief Forces any buffered output to be written to the server. 198 * @param c: The connection to the X server. 199 * @return > @c 0 on success, <= @c 0 otherwise. 200 * 201 * Forces any buffered output to be written to the server. Blocks 202 * until the write is complete. 203 */ 204int xcb_flush(xcb_connection_t *c); 205 206/** 207 * @brief Returns the maximum request length that this server accepts. 208 * @param c: The connection to the X server. 209 * @return The maximum request length field. 210 * 211 * In the absence of the BIG-REQUESTS extension, returns the 212 * maximum request length field from the connection setup data, which 213 * may be as much as 65535. If the server supports BIG-REQUESTS, then 214 * the maximum request length field from the reply to the 215 * BigRequestsEnable request will be returned instead. 216 * 217 * Note that this length is measured in four-byte units, making the 218 * theoretical maximum lengths roughly 256kB without BIG-REQUESTS and 219 * 16GB with. 220 */ 221uint32_t xcb_get_maximum_request_length(xcb_connection_t *c); 222 223/** 224 * @brief Prefetch the maximum request length without blocking. 225 * @param c: The connection to the X server. 226 * 227 * Without blocking, does as much work as possible toward computing 228 * the maximum request length accepted by the X server. 229 * 230 * Invoking this function may cause a call to xcb_big_requests_enable, 231 * but will not block waiting for the reply. 232 * xcb_get_maximum_request_length will return the prefetched data 233 * after possibly blocking while the reply is retrieved. 234 * 235 * Note that in order for this function to be fully non-blocking, the 236 * application must previously have called 237 * xcb_prefetch_extension_data(c, &xcb_big_requests_id) and the reply 238 * must have already arrived. 239 */ 240void xcb_prefetch_maximum_request_length(xcb_connection_t *c); 241 242 243/* xcb_in.c */ 244 245/** 246 * @brief Returns the next event or error from the server. 247 * @param c: The connection to the X server. 248 * @return The next event from the server. 249 * 250 * Returns the next event or error from the server, or returns null in 251 * the event of an I/O error. Blocks until either an event or error 252 * arrive, or an I/O error occurs. 253 */ 254xcb_generic_event_t *xcb_wait_for_event(xcb_connection_t *c); 255 256/** 257 * @brief Returns the next event or error from the server. 258 * @param c: The connection to the X server. 259 * error status of the operation. 260 * @return The next event from the server. 261 * 262 * Returns the next event or error from the server, if one is 263 * available, or returns @c NULL otherwise. If no event is available, that 264 * might be because an I/O error like connection close occurred while 265 * attempting to read the next event, in which case the connection is 266 * shut down when this function returns. 267 */ 268xcb_generic_event_t *xcb_poll_for_event(xcb_connection_t *c); 269 270/** 271 * @brief Return the error for a request, or NULL if none can ever arrive. 272 * @param c: The connection to the X server. 273 * @param cookie: The request cookie. 274 * @return The error for the request, or NULL if none can ever arrive. 275 * 276 * The xcb_void_cookie_t cookie supplied to this function must have resulted 277 * from a call to xcb_[request_name]_checked(). This function will block 278 * until one of two conditions happens. If an error is received, it will be 279 * returned. If a reply to a subsequent request has already arrived, no error 280 * can arrive for this request, so this function will return NULL. 281 * 282 * Note that this function will perform a sync if needed to ensure that the 283 * sequence number will advance beyond that provided in cookie; this is a 284 * convenience to avoid races in determining whether the sync is needed. 285 */ 286xcb_generic_error_t *xcb_request_check(xcb_connection_t *c, xcb_void_cookie_t cookie); 287 288 289/* xcb_ext.c */ 290 291/** 292 * @typedef typedef struct xcb_extension_t xcb_extension_t 293 */ 294typedef struct xcb_extension_t xcb_extension_t; /**< Opaque structure used as key for xcb_get_extension_data_t. */ 295 296/** 297 * @brief Caches reply information from QueryExtension requests. 298 * @param c: The connection. 299 * @param ext: The extension data. 300 * @return A pointer to the xcb_query_extension_reply_t for the extension. 301 * 302 * This function is the primary interface to the "extension cache", 303 * which caches reply information from QueryExtension 304 * requests. Invoking this function may cause a call to 305 * xcb_query_extension to retrieve extension information from the 306 * server, and may block until extension data is received from the 307 * server. 308 * 309 * The result must not be freed. This storage is managed by the cache 310 * itself. 311 */ 312const xcb_query_extension_reply_t *xcb_get_extension_data(xcb_connection_t *c, xcb_extension_t *ext); 313 314/** 315 * @brief Prefetch of extension data into the extension cache 316 * @param c: The connection. 317 * @param ext: The extension data. 318 * 319 * This function allows a "prefetch" of extension data into the 320 * extension cache. Invoking the function may cause a call to 321 * xcb_query_extension, but will not block waiting for the 322 * reply. xcb_get_extension_data will return the prefetched data after 323 * possibly blocking while it is retrieved. 324 */ 325void xcb_prefetch_extension_data(xcb_connection_t *c, xcb_extension_t *ext); 326 327 328/* xcb_conn.c */ 329 330/** 331 * @brief Access the data returned by the server. 332 * @param c: The connection. 333 * @return A pointer to an xcb_setup_t structure. 334 * 335 * Accessor for the data returned by the server when the xcb_connection_t 336 * was initialized. This data includes 337 * - the server's required format for images, 338 * - a list of available visuals, 339 * - a list of available screens, 340 * - the server's maximum request length (in the absence of the 341 * BIG-REQUESTS extension), 342 * - and other assorted information. 343 * 344 * See the X protocol specification for more details. 345 * 346 * The result must not be freed. 347 */ 348const xcb_setup_t *xcb_get_setup(xcb_connection_t *c); 349 350/** 351 * @brief Access the file descriptor of the connection. 352 * @param c: The connection. 353 * @return The file descriptor. 354 * 355 * Accessor for the file descriptor that was passed to the 356 * xcb_connect_to_fd call that returned @p c. 357 */ 358int xcb_get_file_descriptor(xcb_connection_t *c); 359 360/** 361 * @brief Test whether the connection has shut down due to a fatal error. 362 * @param c: The connection. 363 * @return 1 if the connection is in an error state; 0 otherwise. 364 * 365 * Some errors that occur in the context of an xcb_connection_t 366 * are unrecoverable. When such an error occurs, the 367 * connection is shut down and further operations on the 368 * xcb_connection_t have no effect. 369 * 370 * @todo Other functions should document the conditions in 371 * which they shut down the connection. 372 */ 373int xcb_connection_has_error(xcb_connection_t *c); 374 375/** 376 * @brief Connects to the X server. 377 * @param fd: The file descriptor. 378 * @param auth_info: Authentication data. 379 * @return A newly allocated xcb_connection_t structure. 380 * 381 * Connects to an X server, given the open socket @p fd and the 382 * xcb_auth_info_t @p auth_info. The file descriptor @p fd is 383 * bidirectionally connected to an X server. If the connection 384 * should be unauthenticated, @p auth_info must be @c 385 * NULL. 386 */ 387xcb_connection_t *xcb_connect_to_fd(int fd, xcb_auth_info_t *auth_info); 388 389/** 390 * @brief Closes the connection. 391 * @param c: The connection. 392 * 393 * Closes the file descriptor and frees all memory associated with the 394 * connection @c c. 395 */ 396void xcb_disconnect(xcb_connection_t *c); 397 398 399/* xcb_util.c */ 400 401/** 402 * @brief Parses a display string name in the form documented by X(7x). 403 * @param name: The name of the display. 404 * @param host: A pointer to a malloc'd copy of the hostname. 405 * @param display: A pointer to the display number. 406 * @param screen: A pointer to the screen number. 407 * @return 0 on failure, non 0 otherwise. 408 * 409 * Parses the display string name @p display_name in the form 410 * documented by X(7x). Has no side effects on failure. If 411 * @p displayname is @c NULL or empty, it uses the environment 412 * variable DISPLAY. @p hostp is a pointer to a newly allocated string 413 * that contain the host name. @p displayp is set to the display 414 * number and @p screenp to the preferred screen number. @p screenp 415 * can be @c NULL. If @p displayname does not contain a screen number, 416 * it is set to @c 0. 417 */ 418int xcb_parse_display(const char *name, char **host, int *display, int *screen); 419 420/** 421 * @brief Connects to the X server. 422 * @param displayname: The name of the display. 423 * @param screenp: A pointer to a preferred screen number. 424 * @return A newly allocated xcb_connection_t structure. 425 * 426 * Connects to the X server specified by @p displayname. If @p 427 * displayname is @c NULL, uses the value of the DISPLAY environment 428 * variable. If a particular screen on that server is preferred, the 429 * int pointed to by @p screenp (if not @c NULL) will be set to that 430 * screen; otherwise the screen will be set to 0. 431 */ 432xcb_connection_t *xcb_connect(const char *displayname, int *screenp); 433 434/** 435 * @brief Connects to the X server, using an authorization information. 436 * @param display: The name of the display. 437 * @param auth: The authorization information. 438 * @param screen: A pointer to a preferred screen number. 439 * @return A newly allocated xcb_connection_t structure. 440 * 441 * Connects to the X server specified by @p displayname, using the 442 * authorization @p auth. If a particular screen on that server is 443 * preferred, the int pointed to by @p screenp (if not @c NULL) will 444 * be set to that screen; otherwise @p screenp will be set to 0. 445 */ 446xcb_connection_t *xcb_connect_to_display_with_auth_info(const char *display, xcb_auth_info_t *auth, int *screen); 447 448 449/* xcb_xid.c */ 450 451/** 452 * @brief Allocates an XID for a new object. 453 * @param c: The connection. 454 * @return A newly allocated XID. 455 * 456 * Allocates an XID for a new object. Typically used just prior to 457 * various object creation functions, such as xcb_create_window. 458 */ 459uint32_t xcb_generate_id(xcb_connection_t *c); 460 461 462/** 463 * @} 464 */ 465 466#ifdef __cplusplus 467} 468#endif 469 470 471#endif /* __XCB_H__ */ 472