1xcb-requests(3) XCB examples xcb-requests(3)
2
6 xcb-requests - about request manpages
7
9 Every request in X11, like MapWindow, corresponds to a number of func‐
10 tions and data structures in XCB. For MapWindow, XCB provides the func‐
11 tion xcb_map_window, which fills the xcb_map_window_request_t data
12 structure and writes that to the X11 connection. Since the MapWindow
13 request does not have a reply, this is the most simple case.
14
17 Many requests have replies. For each reply, XCB provides at least a
18 corresponding data structure and a function to return a pointer to a
19 filled data structure. Let's take the InternAtom request as an example:
20 XCB provides the xcb_intern_atom_reply_t data structure and
21 xcb_intern_atom_reply function. For replies which are more complex (for
22 example lists, such as in xcb_list_fonts), accessor functions are pro‐
23 vided.
24
27 XCB returns a cookie for each request you send. This is an XCB-specific
28 data structure containing the sequence number with which the request
29 was sent to the X11 server. To get any reply, you have to provide that
30 cookie (so that XCB knows which of the waiting replies you want). Here
31 is an example to illustrate the use of cookies:
32 void my_example(xcb_connection *conn) {
35 xcb_intern_atom_cookie_t cookie;
36 xcb_intern_atom_reply_t *reply;
37 cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
39 /* ... do other work here if possible ... */
40 if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) {
41 printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
42 }
43 free(reply);
44 }
45
48 The checked and unchecked suffixes for functions determine which kind
49 of error handling is used for this specific request.
50 For requests which have no reply (for example xcb_map_window), errors
52 will be delivered to the event loop (you will receive an X11 event of
53 type 0 when calling xcb_poll_for_event). If you want to explicitly
54 check for errors in a blocking fashion, call the _checked version of
55 the function (for example xcb_map_window_checked) and use
56 xcb_request_check.
57 For requests which have a reply (for example xcb_intern_atom), errors
59 will be checked when calling the reply function. To get errors in the
60 event loop instead, use the _unchecked version of the function (for
61 example xcb_intern_atom_unchecked).
62 Here is an example which illustrates the four different ways of han‐
64 dling errors:
65 /*
68 * Request without a reply, handling errors in the event loop (default)
69 *
70 */
71 void my_example(xcb_connection *conn, xcb_window_t window) {
72 /* This is a request without a reply. Errors will be delivered to the event
73 * loop. Getting an error to xcb_map_window most likely is a bug in our
74 * program, so we don't need to check for that in a blocking way. */
75 xcb_map_window(conn, window);
76 /* ... of course your event loop would not be in the same function ... */
78 while ((event = xcb_wait_for_event(conn)) != NULL) {
79 if (event->response_type == 0) {
80 fprintf("Received X11 error %d\n", error->error_code);
81 free(event);
82 continue;
83 }
84 /* ... handle a normal event ... */
86 }
87 }
88 /*
90 * Request without a reply, handling errors directly
91 *
92 */
93 void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) {
94 /* A reparenting window manager wants to know whether a new window was
95 * successfully reparented. If not (because the window got destroyed
96 * already, for example), it does not make sense to map an empty window
97 * decoration at all, so we need to know this right now. */
98 xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window,
99 deco, 0, 0);
100 xcb_generic_error_t *error;
101 if ((error = xcb_request_check(conn, cookie))) {
102 fprintf(stderr, "Could not reparent the window\n");
103 free(error);
104 return;
105 }
106 /* ... do window manager stuff here ... */
108 }
109 /*
111 * Request with a reply, handling errors directly (default)
112 *
113 */
114 void my_example(xcb_connection *conn, xcb_window_t window) {
115 xcb_intern_atom_cookie_t cookie;
116 xcb_intern_atom_reply_t *reply;
117 xcb_generic_error_t *error;
118 cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
120 /* ... do other work here if possible ... */
121 if ((reply = xcb_intern_atom_reply(c, cookie, &error))) {
122 printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
123 free(reply);
124 } else {
125 fprintf(stderr, "X11 Error %d\n", error->error_code);
126 free(error);
127 }
128 }
129 /*
131 * Request with a reply, handling errors in the event loop
132 *
133 */
134 void my_example(xcb_connection *conn, xcb_window_t window) {
135 xcb_intern_atom_cookie_t cookie;
136 xcb_intern_atom_reply_t *reply;
137 cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"),
139 "_NET_WM_NAME");
140 /* ... do other work here if possible ... */
141 if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
142 printf("The _NET_WM_NAME atom has ID %u\n", reply->atom);
143 free(reply);
144 }
145 /* ... of course your event loop would not be in the same function ... */
147 while ((event = xcb_wait_for_event(conn)) != NULL) {
148 if (event->response_type == 0) {
149 fprintf("Received X11 error %d\n", error->error_code);
150 free(event);
151 continue;
152 }
153 /* ... handle a normal event ... */
155 }
156 }
157
160 xcb_map_window(3), xcb_intern_atom(3), xcb_list_fonts(3),
161 xcb_poll_for_event(3), xcb_request_check(3)
162
164 Michael Stapelberg <michael+xcb at stapelberg dot de>
165X Version 11 libxcb 1.13 xcb-requests(3)