Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/xcb/xcb.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
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__ */