1xcb-requests(3)                  XCB examples                  xcb-requests(3)
2
3
4

NAME

6       xcb-requests - about request manpages
7

DESCRIPTION

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
15

REPLIES

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
25

COOKIES

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
33
34       void my_example(xcb_connection *conn) {
35           xcb_intern_atom_cookie_t cookie;
36           xcb_intern_atom_reply_t *reply;
37
38           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
46

CHECKED VS. UNCHECKED

48       The checked and unchecked suffixes for functions determine which kind
49       of error handling is used for this specific request.
50
51       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
58       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
63       Here is an example which illustrates the four different ways of han‐
64       dling errors:
65
66
67       /*
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
77           /* ... 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
85               /* ... handle a normal event ... */
86           }
87       }
88
89       /*
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
107           /* ... do window manager stuff here ... */
108       }
109
110       /*
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
119           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
130       /*
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
138           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
146           /* ... 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
154               /* ... handle a normal event ... */
155           }
156       }
157
158

SEE ALSO

160       xcb_map_window(3), xcb_intern_atom(3), xcb_list_fonts(3),
161       xcb_poll_for_event(3), xcb_request_check(3)
162

AUTHOR

164       Michael Stapelberg <michael+xcb at stapelberg dot de>
165
166
167
168X Version 11                      libxcb 1.13                  xcb-requests(3)
Impressum