Fix a comment for the renaming of XCBConnSetupSuccessRep to XCBSetup, and fix another...
[free-sw/xcb/libxcb] / src / 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 /* TODO: check for stdint in config? (HAVE_STDINT) fallback? */
33 #include <stdint.h>
34
35 /* FIXME: these names conflict with those defined in Xmd.h. */
36 #ifndef XMD_H
37 typedef uint8_t  BYTE;
38 typedef uint8_t  BOOL;
39 typedef uint8_t  CARD8;
40 typedef uint16_t CARD16;
41 typedef uint32_t CARD32;
42 typedef int8_t   INT8;
43 typedef int16_t  INT16;
44 typedef int32_t  INT32;
45 #endif /* XMD_H */
46
47 #include <X11/X.h>
48 #include <sys/uio.h>
49 #include <pthread.h>
50
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54
55 #if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
56 #define deprecated __attribute__((__deprecated__))
57 #else
58 #define deprecated
59 #endif
60
61
62 /**
63  * @file xcb.h
64  */
65
66 /**
67  * @defgroup XCB_Core_Api XCB Core API
68  * @brief Core API of the XCB library.
69  *
70  * @{
71  */
72
73 /* Pre-defined constants */
74
75 /** Current protocol version */
76 #define X_PROTOCOL 11
77
78 /** Current minor version */
79 #define X_PROTOCOL_REVISION 0
80
81 /** X_TCP_PORT + display number = server port for TCP transport */
82 #define X_TCP_PORT 6000
83
84 #define XCB_TYPE_PAD(T,I) (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1))
85
86
87 /** XCBNone is the universal null resource or null atom parameter value for many core X requests */
88 #define XCBNone 0L
89
90 /** XCBCopyFromParent can be used for many CreateWindow parameters */
91 #define XCBCopyFromParent 0L
92
93 /* Opaque structures */
94
95 /**
96  * @brief XCB Connection structure.
97  *
98  * A structure that contain all data that  XCB needs to communicate with an X server.
99  */
100 typedef struct XCBConnection XCBConnection;  /**< Opaque structure containing all data that  XCB needs to communicate with an X server. */
101
102
103 /* Other types */
104
105 /**
106  * @brief Generic iterator.
107  *
108  * A generic iterator structure.
109  */
110 typedef struct {
111     void *data;   /**< Data of the current iterator */
112     int rem;    /**< remaining elements */
113     int index;  /**< index of the current iterator */
114 } XCBGenericIter;
115
116 /**
117  * @brief Generic reply.
118  *
119  * A generic reply structure.
120  */
121 typedef struct {
122     BYTE   response_type;  /**< Type of the response */
123     CARD8  pad0;           /**< Padding */
124     CARD16 sequence;       /**< Sequence number */
125     CARD32 length;         /**< Length of the response */
126 } XCBGenericRep;
127
128 /**
129  * @brief Generic event.
130  *
131  * A generic event structure.
132  */
133 typedef struct {
134     BYTE   response_type;  /**< Type of the response */
135     CARD8  pad0;           /**< Padding */
136     CARD16 sequence;       /**< Sequence number */
137     CARD32 pad[7];         /**< Padding */
138     CARD32 full_sequence;
139 } XCBGenericEvent;
140
141 /**
142  * @brief Generic error.
143  *
144  * A generic error structure.
145  */
146 typedef struct {
147     BYTE   response_type;  /**< Type of the response */
148     BYTE   error_code;     /**< Error code */
149     CARD16 sequence;       /**< Sequence number */
150     CARD32 pad[7];         /**< Padding */
151     CARD32 full_sequence;
152 } XCBGenericError;
153
154 /**
155  * @brief Generic cookie.
156  *
157  * A generic cookie structure.
158  */
159 typedef struct {
160     unsigned int sequence;  /**< Sequence number */
161 } XCBVoidCookie;
162
163
164 /* Include the generated xproto and xcb_types headers. */
165 #include "xcb_types.h"
166 #include "xproto.h"
167
168
169 /* xcb_auth.c */
170
171 /**
172  * @brief Container for authorization information.
173  *
174  * A container for authorization information to be sent to the X server.
175  */
176 typedef struct XCBAuthInfo {
177     int   namelen;  /**< Length of the string name (as returned by strlen). */
178     char *name;     /**< String containing the authentication protocol name, such as "MIT-MAGIC-COOKIE-1" or "XDM-AUTHORIZATION-1". */
179     int   datalen;  /**< Length of the data member. */
180     char *data;   /**< Data interpreted in a protocol-specific manner. */
181 } XCBAuthInfo;
182
183 /**
184  * @brief Gets authorization information.
185  * @param fd: The file descriptor.
186  * @param info: The authorisation info to set.
187  * @return @c 0 on failure, 1 otherwise.
188  *
189  * @deprecated This function is deprecated. It must not be used in
190  * newly written code.
191  */
192 int XCBGetAuthInfo(int fd, XCBAuthInfo *info) deprecated;
193
194
195 /* xcb_out.c */
196
197 /**
198  * @brief Forces any buffered output to be written to the server.
199  * @param c: The connection to the X server.
200  * @return > @c 0 on success, <= @c 0 otherwise.
201  *
202  * Forces any buffered output to be written to the server. Blocks
203  * until the write is complete.
204  */
205 int XCBFlush(XCBConnection *c);
206
207 /**
208  * @brief Returns the maximum request length field from the connection
209  * setup data.
210  * @param c: The connection to the X server.
211  * @return The maximum request length field.
212  *
213  * In the absence of the BIG-REQUESTS extension, returns the
214  * maximum request length field from the connection setup data, which
215  * may be as much as 65535. If the server supports BIG-REQUESTS, then
216  * the maximum request length field from the reply to the
217  * BigRequestsEnable request will be returned instead.
218  *
219  * Note that this length is measured in four-byte units, making the
220  * theoretical maximum lengths roughly 256kB without BIG-REQUESTS and
221  * 16GB with.
222  */
223 CARD32 XCBGetMaximumRequestLength(XCBConnection *c);
224
225
226 /* xcb_in.c */
227
228 /**
229  * @brief Returns the next event or error from the server.
230  * @param c: The connection to the X server.
231  * @return The next event from the server.
232  *
233  * @deprecated This function is deprecated. It must not be used in
234  * newly written code.
235  */
236 XCBGenericEvent *XCBWaitEvent(XCBConnection *c) deprecated;
237
238 /**
239  * @brief Returns the next event or error from the server.
240  * @param c: The connection to the X server.
241  * @return The next event from the server.
242  *
243  * Returns the next event or error from the server, or returns null in
244  * the event of an I/O error. Blocks until either an event or error
245  * arrive, or an I/O error occurs.
246  */
247 XCBGenericEvent *XCBWaitForEvent(XCBConnection *c);
248
249 /**
250  * @brief Returns the next event or error from the server.
251  * @param c: The connection to the X server.
252  * @param error: A pointer to an int to be filled in with the I/O
253  * error status of the operation.
254  * @return The next event from the server.
255  *
256  * Returns the next event or error from the server, if one is
257  * available, or returns @c NULL otherwise. If no event is available, that
258  * might be because an I/O error like connection close occurred while
259  * attempting to read the next event. The @p error parameter is a
260  * pointer to an int to be filled in with the I/O error status of the
261  * operation. If @p error is @c NULL, terminates the application when an
262  * I/O error occurs.
263  */
264 XCBGenericEvent *XCBPollForEvent(XCBConnection *c, int *error);
265
266 /**
267  * @brief Returns the last sequence number that the server is known to
268  * have processed.
269  * @param c: The connection to the X server.
270  * @return The last sequence number.
271  *
272  * Returns the last sequence number that the server is known to have
273  * processed. This function enables applications to determine whether
274  * forcing a cookie is going to block.
275  *
276  * @deprecated This function is deprecated in favor of XCBPollForReply.
277  * It must not be used in newly written code.
278  */
279 unsigned int XCBGetRequestRead(XCBConnection *c) deprecated;
280
281
282 /* xcb_ext.c */
283
284 /**
285  * @typedef typedef struct XCBExtension XCBExtension
286  */
287 typedef struct XCBExtension XCBExtension;  /**< Opaque structure used as key for XCBGetExtensionData. */
288
289 /**
290  * @brief Caches reply information from QueryExtension requests.
291  * @param c: The connection.
292  * @param ext: The extension data.
293  * @return A pointer to the XCBQueryExtensionRep for the extension.
294  *
295  * This function is the primary interface to the "extension cache",
296  * which caches reply information from QueryExtension
297  * requests. Invoking this function may cause a call to
298  * XCBQueryExtension to retrieve extension information from the
299  * server, and may block until extension data is received from the
300  * server.
301  *
302  * The result must not be freed. This storage is managed by the cache
303  * itself.
304  */
305 const XCBQueryExtensionRep *XCBGetExtensionData(XCBConnection *c, XCBExtension *ext);
306
307 /**
308  * @brief Prefetch of extension data into the extension cache
309  * @param c: The connection.
310  * @param ext: The extension data.
311  *
312  * This function allows a "prefetch" of extension data into the
313  * extension cache. Invoking the function may cause a call to
314  * XCBQueryExtension, but will not block waiting for the
315  * reply. XCBGetExtensionData will return the prefetched data after
316  * possibly blocking while it is retrieved.
317  */
318 void XCBPrefetchExtensionData(XCBConnection *c, XCBExtension *ext);
319
320
321 /* xcb_conn.c */
322
323 /**
324  * @brief Access the data returned by the server.
325  * @param c: The connection.
326  * @return A pointer to an XCBSetup structure.
327  *
328  * Accessor for the data returned by the server when the XCBConnection
329  * was initialized. This data includes
330  * - the server's required format for images,
331  * - a list of available visuals,
332  * - a list of available screens,
333  * - the server's maximum request length (in the absence of the
334  * BIG-REQUESTS extension),
335  * - and other assorted information.
336  *
337  * See the X protocol specification for more details.
338  *
339  * The result must not be freed.
340  */
341 const XCBSetup *XCBGetSetup(XCBConnection *c);
342
343 /**
344  * @brief Access the file descriptor of the connection.
345  * @param c: The connection.
346  * @return The file descriptor.
347  *
348  * Accessor for the file descriptor that was passed to the
349  * XCBConnectToFD call that returned @p c.
350  */
351 int XCBGetFileDescriptor(XCBConnection *c);
352
353 /**
354  * @brief Connects to the X server.
355  * @param fd: The file descriptor.
356  * @param auth_info: Authentication data.
357  * @return A newly allocated XCBConnection structure.
358  *
359  * Connects to an X server, given the open socket @p fd and the
360  * XCBAuthInfo @p auth_info. The file descriptor @p fd is
361  * bidirectionally connected to an X server. XCBGetTCPFD and
362  * XCBGetUnixFD return appropriate file descriptors. If the connection
363  * should be unauthenticated, @p auth_info must be @c
364  * NULL. XCBGetAuthInfo returns appropriate authentication data.
365  */
366 XCBConnection *XCBConnectToFD(int fd, XCBAuthInfo *auth_info);
367
368 /**
369  * @brief Closes the connection.
370  * @param c: The connection.
371  *
372  * Closes the file descriptor and frees all memory associated with the
373  * connection @c c.
374  */
375 void XCBDisconnect(XCBConnection *c);
376
377
378 /* xcb_util.c */
379
380 /**
381  * @brief Parses a display string name in the form documented by X(7x).
382  * @param displayname: The name of the display.
383  * @param hostp: A pointer to a malloc'd copy of the hostname.
384  * @param displayp: A pointer to the display number.
385  * @param screenp: A pointer to the screen number.
386  * @return 0 on failure, non 0 otherwise.
387  *
388  * Parses the display string name @p display_name in the form
389  * documented by X(7x). Has no side effects on failure. If
390  * @p displayname is @c NULL or empty, it uses the environment
391  * variable DISPLAY. @p hostp is a pointer to a newly allocated string
392  * that contain the host name. @p displayp is set to the display
393  * number and @p screenp to the preferred screen number. @p screenp
394  * can be @c NULL. If @p displayname does not contain a screen number,
395  * it is set to @c 0.
396  */
397 int XCBParseDisplay(const char *name, char **host, int *display, int *screen);
398
399 /**
400  * @brief Open a connection to the X server.
401  * @param host: The host name.
402  * @param display: The display number.
403  * @return The file descriptor.
404  *
405  * @deprecated This function is deprecated. It must not be used in
406  * newly written code.
407  */
408 int XCBOpen(const char *host, int display) deprecated;
409
410 /**
411  * @brief Open a connection to the X server.
412  * @param host: The host name.
413  * @param port: The TCP port.
414  * @return The file descriptor.
415  *
416  * @deprecated This function is deprecated. It must not be used in
417  * newly written code.
418  */
419 int XCBOpenTCP(const char *host, unsigned short port) deprecated;
420
421 /**
422  * @brief Connects to the X server.
423  * @param file: The file name.
424  * @return The file descriptor.
425  *
426  * @deprecated This function is deprecated. It must not be used in
427  * newly written code.
428  */
429 int XCBOpenUnix(const char *file) deprecated;
430
431 /**
432  * @brief Connects to the X server.
433  * @return A newly allocated XCBConnection structure.
434  *
435  * @deprecated This function is deprecated. It must not be used in
436  * newly written code.
437  */
438 XCBConnection *XCBConnectBasic(void) deprecated;
439
440 /**
441  * @brief Connects to the X server.
442  * @param displayname: The name of the display.
443  * @param screenp: A pointer to a preferred screen number.
444  * @return A newly allocated XCBConnection structure.
445  *
446  * Connects to the X server specified by @p displayname. If @p
447  * displayname is @c NULL, uses the value of the DISPLAY environment
448  * variable. If a particular screen on that server is preferred, the
449  * int pointed to by @p screenp (if not @c NULL) will be set to that
450  * screen; otherwise the screen will be set to 0.
451  */
452 XCBConnection *XCBConnect(const char *displayname, int *screenp);
453
454 /**
455  * @brief Connects to the X server, using an authorization information.
456  * @param displayname: The name of the display.
457  * @param auth: The authorization information.
458  * @param screenp: A pointer to a preferred screen number.
459  * @return A newly allocated XCBConnection structure.
460  *
461  * Connects to the X server specified by @p displayname, using the
462  * authorization @p auth. If a particular screen on that server is
463  * preferred, the int pointed to by @p screenp (if not @c NULL) will
464  * be set to that screen; otherwise @p screenp will be set to 0.
465  */
466 XCBConnection *XCBConnectToDisplayWithAuthInfo(const char *display, XCBAuthInfo *auth, int *screen);
467
468 /**
469  * @brief Ensures that all events and errors are avalaible in XCB.
470  * @param c: The connection to the X server.
471  * @param e: A pointer to an error.
472  * @return @c 1 on success, @c 0 otherwise.
473  *
474  * Blocks the calling thread for the duration of one round trip to the
475  * server, ensuring that all events and errors caused by previous
476  * requests are available to XCB.
477  */
478 int XCBSync(XCBConnection *c, XCBGenericError **e);
479
480
481 /**
482  * @}
483  */
484
485
486 /* Old names for connection-setup types, to be removed before 1.0. */
487
488 typedef XCBSetupReq XCBConnSetupReq deprecated;
489 typedef XCBSetupReqIter XCBConnSetupReqIter deprecated;
490 typedef XCBSetupFailed XCBConnSetupFailedRep deprecated;
491 typedef XCBSetupFailedIter XCBConnSetupFailedRepIter deprecated;
492 typedef XCBSetupAuthenticate XCBConnSetupAuthenticateRep deprecated;
493 typedef XCBSetupAuthenticateIter XCBConnSetupAuthenticateRepIter deprecated;
494 typedef XCBSetup XCBConnSetupSuccessRep deprecated;
495 typedef XCBSetupIter XCBConnSetupSuccessRepIter deprecated;
496
497 char *XCBConnSetupReqAuthorizationProtocolName(XCBSetupReq *R) deprecated;
498 int XCBConnSetupReqAuthorizationProtocolNameLength(XCBSetupReq *R) deprecated;
499 XCBGenericIter XCBConnSetupReqAuthorizationProtocolNameEnd(XCBSetupReq *R) deprecated;
500 char *XCBConnSetupReqAuthorizationProtocolData(XCBSetupReq *R) deprecated;
501 int XCBConnSetupReqAuthorizationProtocolDataLength(XCBSetupReq *R) deprecated;
502 XCBGenericIter XCBConnSetupReqAuthorizationProtocolDataEnd(XCBSetupReq *R) deprecated;
503 void XCBConnSetupReqNext(XCBSetupReqIter *i) deprecated;
504 XCBGenericIter XCBConnSetupReqEnd(XCBSetupReqIter i) deprecated;
505 char *XCBConnSetupFailedRepReason(XCBSetupFailed *R) deprecated;
506 int XCBConnSetupFailedRepReasonLength(XCBSetupFailed *R) deprecated;
507 XCBGenericIter XCBConnSetupFailedRepReasonEnd(XCBSetupFailed *R) deprecated;
508 void XCBConnSetupFailedRepNext(XCBSetupFailedIter *i) deprecated;
509 XCBGenericIter XCBConnSetupFailedRepEnd(XCBSetupFailedIter i) deprecated;
510 char *XCBConnSetupAuthenticateRepReason(XCBSetupAuthenticate *R) deprecated;
511 int XCBConnSetupAuthenticateRepReasonLength(XCBSetupAuthenticate *R) deprecated;
512 XCBGenericIter XCBConnSetupAuthenticateRepReasonEnd(XCBSetupAuthenticate *R) deprecated;
513 void XCBConnSetupAuthenticateRepNext(XCBSetupAuthenticateIter *i) deprecated;
514 XCBGenericIter XCBConnSetupAuthenticateRepEnd(XCBSetupAuthenticateIter i) deprecated;
515 char *XCBConnSetupSuccessRepVendor(XCBSetup *R) deprecated;
516 int XCBConnSetupSuccessRepVendorLength(XCBSetup *R) deprecated;
517 XCBGenericIter XCBConnSetupSuccessRepVendorEnd(XCBSetup *R) deprecated;
518 XCBFORMAT *XCBConnSetupSuccessRepPixmapFormats(XCBSetup *R) deprecated;
519 int XCBConnSetupSuccessRepPixmapFormatsLength(XCBSetup *R) deprecated;
520 XCBFORMATIter XCBConnSetupSuccessRepPixmapFormatsIter(XCBSetup *R) deprecated;
521 int XCBConnSetupSuccessRepRootsLength(XCBSetup *R) deprecated;
522 XCBSCREENIter XCBConnSetupSuccessRepRootsIter(XCBSetup *R) deprecated;
523 void XCBConnSetupSuccessRepNext(XCBSetupIter *i) deprecated;
524 XCBGenericIter XCBConnSetupSuccessRepEnd(XCBSetupIter i) deprecated;
525
526
527 #ifdef __cplusplus
528 }
529 #endif
530
531 #endif