|
Packit |
071ada |
.TH xcb-requests __libmansuffix__ __xorgversion__ "XCB examples"
|
|
Packit |
071ada |
.ad l
|
|
Packit |
071ada |
.SH NAME
|
|
Packit |
071ada |
xcb-requests \- about request manpages
|
|
Packit |
071ada |
.SH DESCRIPTION
|
|
Packit |
071ada |
Every request in X11, like \fIMapWindow\fP, corresponds to a number of
|
|
Packit |
071ada |
functions and data structures in XCB. For \fIMapWindow\fP, XCB provides the
|
|
Packit |
071ada |
function \fIxcb_map_window\fP, which fills the \fIxcb_map_window_request_t\fP
|
|
Packit |
071ada |
data structure and writes that to the X11 connection. Since the \fIMapWindow\fP
|
|
Packit |
071ada |
request does not have a reply, this is the most simple case.
|
|
Packit |
071ada |
|
|
Packit |
071ada |
.SH REPLIES
|
|
Packit |
071ada |
|
|
Packit |
071ada |
Many requests have replies. For each reply, XCB provides at least a
|
|
Packit |
071ada |
corresponding data structure and a function to return a pointer to a filled
|
|
Packit |
071ada |
data structure. Let's take the \fIInternAtom\fP request as an example: XCB
|
|
Packit |
071ada |
provides the \fIxcb_intern_atom_reply_t\fP data structure and
|
|
Packit |
071ada |
\fIxcb_intern_atom_reply\fP function. For replies which are more complex (for
|
|
Packit |
071ada |
example lists, such as in \fIxcb_list_fonts\fP), accessor functions are
|
|
Packit |
071ada |
provided.
|
|
Packit |
071ada |
|
|
Packit |
071ada |
.SH COOKIES
|
|
Packit |
071ada |
|
|
Packit |
071ada |
XCB returns a cookie for each request you send. This is an XCB-specific data
|
|
Packit |
071ada |
structure containing the sequence number with which the request was sent to the
|
|
Packit |
071ada |
X11 server. To get any reply, you have to provide that cookie (so that XCB
|
|
Packit |
071ada |
knows which of the waiting replies you want). Here is an example to illustrate
|
|
Packit |
071ada |
the use of cookies:
|
|
Packit |
071ada |
|
|
Packit |
071ada |
.nf
|
|
Packit |
071ada |
.sp
|
|
Packit |
071ada |
void my_example(xcb_connection *conn) {
|
|
Packit |
071ada |
xcb_intern_atom_cookie_t cookie;
|
|
Packit |
071ada |
xcb_intern_atom_reply_t *reply;
|
|
Packit |
071ada |
|
|
Packit |
071ada |
cookie = xcb_intern_atom(conn, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
|
|
Packit |
071ada |
/* ... do other work here if possible ... */
|
|
Packit |
071ada |
if ((reply = xcb_intern_atom_reply(conn, cookie, NULL))) {
|
|
Packit |
071ada |
printf("The _NET_WM_NAME atom has ID %u\\n", reply->atom);
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
free(reply);
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
.fi
|
|
Packit |
071ada |
|
|
Packit |
071ada |
.SH CHECKED VS. UNCHECKED
|
|
Packit |
071ada |
|
|
Packit |
071ada |
The checked and unchecked suffixes for functions determine which kind of error
|
|
Packit |
071ada |
handling is used for this specific request.
|
|
Packit |
071ada |
|
|
Packit |
071ada |
For requests which have no reply (for example \fIxcb_map_window\fP), errors
|
|
Packit |
071ada |
will be delivered to the event loop (you will receive an X11 event of type 0
|
|
Packit |
071ada |
when calling \fIxcb_poll_for_event\fP).
|
|
Packit |
071ada |
If you want to explicitly check for errors in a blocking fashion, call the
|
|
Packit |
071ada |
_checked version of the function (for example \fIxcb_map_window_checked\fP) and
|
|
Packit |
071ada |
use \fIxcb_request_check\fP.
|
|
Packit |
071ada |
|
|
Packit |
071ada |
For requests which have a reply (for example \fIxcb_intern_atom\fP), errors
|
|
Packit |
071ada |
will be checked when calling the reply function. To get errors in the event
|
|
Packit |
071ada |
loop instead, use the _unchecked version of the function (for example
|
|
Packit |
071ada |
\fIxcb_intern_atom_unchecked\fP).
|
|
Packit |
071ada |
|
|
Packit |
071ada |
Here is an example which illustrates the four different ways of handling errors:
|
|
Packit |
071ada |
|
|
Packit |
071ada |
.nf
|
|
Packit |
071ada |
.sp
|
|
Packit |
071ada |
/*
|
|
Packit |
071ada |
* Request without a reply, handling errors in the event loop (default)
|
|
Packit |
071ada |
*
|
|
Packit |
071ada |
*/
|
|
Packit |
071ada |
void my_example(xcb_connection *conn, xcb_window_t window) {
|
|
Packit |
071ada |
/* This is a request without a reply. Errors will be delivered to the event
|
|
Packit |
071ada |
* loop. Getting an error to xcb_map_window most likely is a bug in our
|
|
Packit |
071ada |
* program, so we don't need to check for that in a blocking way. */
|
|
Packit |
071ada |
xcb_map_window(conn, window);
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/* ... of course your event loop would not be in the same function ... */
|
|
Packit |
071ada |
while ((event = xcb_wait_for_event(conn)) != NULL) {
|
|
Packit |
071ada |
if (event->response_type == 0) {
|
|
Packit |
071ada |
fprintf("Received X11 error %d\\n", error->error_code);
|
|
Packit |
071ada |
free(event);
|
|
Packit |
071ada |
continue;
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/* ... handle a normal event ... */
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/*
|
|
Packit |
071ada |
* Request without a reply, handling errors directly
|
|
Packit |
071ada |
*
|
|
Packit |
071ada |
*/
|
|
Packit |
071ada |
void my_example(xcb_connection *conn, xcb_window_t deco, xcb_window_t window) {
|
|
Packit |
071ada |
/* A reparenting window manager wants to know whether a new window was
|
|
Packit |
071ada |
* successfully reparented. If not (because the window got destroyed
|
|
Packit |
071ada |
* already, for example), it does not make sense to map an empty window
|
|
Packit |
071ada |
* decoration at all, so we need to know this right now. */
|
|
Packit |
071ada |
xcb_void_cookie_t cookie = xcb_reparent_window_checked(conn, window,
|
|
Packit |
071ada |
deco, 0, 0);
|
|
Packit |
071ada |
xcb_generic_error_t *error;
|
|
Packit |
071ada |
if ((error = xcb_request_check(conn, cookie))) {
|
|
Packit |
071ada |
fprintf(stderr, "Could not reparent the window\\n");
|
|
Packit |
071ada |
free(error);
|
|
Packit |
071ada |
return;
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/* ... do window manager stuff here ... */
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/*
|
|
Packit |
071ada |
* Request with a reply, handling errors directly (default)
|
|
Packit |
071ada |
*
|
|
Packit |
071ada |
*/
|
|
Packit |
071ada |
void my_example(xcb_connection *conn, xcb_window_t window) {
|
|
Packit |
071ada |
xcb_intern_atom_cookie_t cookie;
|
|
Packit |
071ada |
xcb_intern_atom_reply_t *reply;
|
|
Packit |
071ada |
xcb_generic_error_t *error;
|
|
Packit |
071ada |
|
|
Packit |
071ada |
cookie = xcb_intern_atom(c, 0, strlen("_NET_WM_NAME"), "_NET_WM_NAME");
|
|
Packit |
071ada |
/* ... do other work here if possible ... */
|
|
Packit |
071ada |
if ((reply = xcb_intern_atom_reply(c, cookie, &error))) {
|
|
Packit |
071ada |
printf("The _NET_WM_NAME atom has ID %u\\n", reply->atom);
|
|
Packit |
071ada |
free(reply);
|
|
Packit |
071ada |
} else {
|
|
Packit |
071ada |
fprintf(stderr, "X11 Error %d\\n", error->error_code);
|
|
Packit |
071ada |
free(error);
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/*
|
|
Packit |
071ada |
* Request with a reply, handling errors in the event loop
|
|
Packit |
071ada |
*
|
|
Packit |
071ada |
*/
|
|
Packit |
071ada |
void my_example(xcb_connection *conn, xcb_window_t window) {
|
|
Packit |
071ada |
xcb_intern_atom_cookie_t cookie;
|
|
Packit |
071ada |
xcb_intern_atom_reply_t *reply;
|
|
Packit |
071ada |
|
|
Packit |
071ada |
cookie = xcb_intern_atom_unchecked(c, 0, strlen("_NET_WM_NAME"),
|
|
Packit |
071ada |
"_NET_WM_NAME");
|
|
Packit |
071ada |
/* ... do other work here if possible ... */
|
|
Packit |
071ada |
if ((reply = xcb_intern_atom_reply(c, cookie, NULL))) {
|
|
Packit |
071ada |
printf("The _NET_WM_NAME atom has ID %u\\n", reply->atom);
|
|
Packit |
071ada |
free(reply);
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/* ... of course your event loop would not be in the same function ... */
|
|
Packit |
071ada |
while ((event = xcb_wait_for_event(conn)) != NULL) {
|
|
Packit |
071ada |
if (event->response_type == 0) {
|
|
Packit |
071ada |
fprintf("Received X11 error %d\\n", error->error_code);
|
|
Packit |
071ada |
free(event);
|
|
Packit |
071ada |
continue;
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
|
|
Packit |
071ada |
/* ... handle a normal event ... */
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
}
|
|
Packit |
071ada |
.fi
|
|
Packit |
071ada |
|
|
Packit |
071ada |
.SH SEE ALSO
|
|
Packit |
071ada |
.BR xcb_map_window (__libmansuffix__),
|
|
Packit |
071ada |
.BR xcb_intern_atom (__libmansuffix__),
|
|
Packit |
071ada |
.BR xcb_list_fonts (__libmansuffix__),
|
|
Packit |
071ada |
.BR xcb_poll_for_event (__libmansuffix__),
|
|
Packit |
071ada |
.BR xcb_request_check (__libmansuffix__)
|
|
Packit |
071ada |
.SH AUTHOR
|
|
Packit |
071ada |
Michael Stapelberg <michael+xcb at stapelberg dot de>
|