Module x11rb::cookie

Cookies are handles to future replies or errors from the X11 server.

When sending a request, you get back a cookie. There are different cookies for different kinds of requests.

For requests without a reply, you get a VoidCookie. Requests with a reply are represented by a Cookie or a CookieWithFds if the reply also contains file descriptors. Additionally, there are two special cases for requests which generate more than one reply: ListFontsWithInfoCookie and RecordEnableContextCookie.

Handling X11 errors

The X11 server can answer requests with an error packet for various reasons, e.g. because an invalid window ID was given. There are three options what can be done with errors:

• Errors can appear as X11 events in wait_for_event() (in XCB, this is called “unchecked”)
• Errors can be checked for locally after a request was sent (in XCB, this is called “checked”)
• Errors can be completely ignored (the closest analog in XCB would be xcb_discard_reply())

There is an additional difference between requests with and without replies.

Requests without a reply

For requests that do not have a reply, you get an instance of VoidCookie after sending the request. The different behaviors can be achieved via interacting with this cookie as foolows:

What?	How?
Treat as events	Just drop the cookie
Check locally	VoidCookie::check
Ignore	VoidCookie::ignore_error

Requests with a reply

For requests with a reply, an additional option is what should happen to the reply. You can get the reply, but any errors are still treated as events. This allows to centralise X11 error handling a bit in case you only want to log errors.

The following things can be done with the Cookie that you get after sending a request with an error.

Reply	Errors locally/ignored	Errors as events
Get	Cookie::reply	Cookie::reply_unchecked
Ignore	Cookie::discard_reply_and_errors	Just drop the cookie

Structs

Cookie	A handle to a response from the X11 server.
CookieWithFds	A handle to a response containing RawFd from the X11 server.
ListFontsWithInfoCookie	A handle to the replies to a ListFontsWithInfo request.
RecordEnableContextCookie	A handle to the replies to a record::EnableContext request.
VoidCookie	A handle to a possible error from the X11 server.