path: root/ProtocolStubApi.mdwn

These are not single functions or types, but rather naming conventions intended to be used in the core protocol API and the public API for all extensions. All declarations associated with the core protocol are in xcb.h, while each extension provides all of its declarations in its own header file.

One of the design goals of this API is that users should be able to learn these conventions, then read documentation on the binary encoding of the core protocol or any extension, and immediately determine the correct function name and argument list to generate the desired request.

Most of the X Window Protocol documentation lives at <http://www.x.org/releases/X11R7.7/doc/index.html#protocol>.

[!] _**TODO:** link to online descriptions of the core X protocol as well as de-facto standard extension protocols._

[[!toc levels="6"]]

## Extensions

### `xcb_extension_id`

		xcb_extension_t xcb_extension_id

(xcb.h)

A unique, opaque object identifying this extension for [`xcb_get_extension_data()`](#xcb_get_extension_data).

## Fields

Several conventions apply to field names.

- Fields have underscore-separated lower-case names.
- Where a field represents an object in an X protocol specification document, the name is formed by replacing dash ("-") and space (" ") characters with underscores ("\_").
- Where a field holds the length of field "foo", its name is "foo\_len".

## Types

The C name for the X type with name "Name" is `xcb_name_t`. If the type is from an extension, then "Name" is composed by prefixing the extension name onto the type name.

[!] _**TODO:**Links to XCBProtocolLanguage should be changed to point to appropriate [[XmlXcb]] documentation._

Types are declared using the [[STRUCT|XmlXcb#STRUCT]], [[UNION|XmlXcb#UNION]], [[XIDTYPE|XmlXcb#XIDTYPE]], [[ENUM|XmlXcb#ENUM]], and [[TYPEDEF|XmlXcb#TYPEDEF]] protocol description macros.

<a name="xcb_name_iterator_t"></a>

### `xcb_name_iterator_t`

		typedef struct {
		         xcb_name_t *data;
		         int rem;
		         int index;
		} xcb_name_iterator_t;

An iterator may only be created for types declared using the [[STRUCT|XmlXcb#STRUCT]] and [[XIDTYPE|XmlXcb#XIDTYPE]] protocol description macros.

A special iterator type, `xcb_generic_iterator_t`, is declared in xcb.h.

### `xcb_name_next`

		void
		xcb_name_next (xcb_name_iterator_t *i);

Every [iterator](#xcb_name_iterator_t) has a `xcb_name_next` function.

### `xcb_name_end`

		xcb_generic_iterator_t
		xcb_name_end (xcb_name_iterator_t i);

Every [iterator](#xcb_name_iterator_t) has a `xcb_name_end` function.

### `xcb_type_name_field_iterator`

		xcb_base_type_iterator_t
		xcb_type_name_field_iterator (xcb_type_name_t *R);

Declared by the [[LISTFIELD|XmlXcb#LISTFIELD]] protocol description macro.

### `xcb_type_name_field`

		BaseType *
		xcb_type_name_field (xcb_type_name_t *R);

Declared by the [[LISTFIELD|XmlXcb#LISTFIELD]] protocol description macro.

### `xcb_type_name_field_length`

		int
		xcb_type_name_field_length (xcb_type_name_t *R);

Declared by the [[LISTFIELD|XmlXcb#LISTFIELD]] protocol description macro.

### `xcb_type_name_field_end`

		xcb_generic_iterator_t
		xcb_type_name_field_end (xcb_type_name_t *R);

Declared by the [[LISTFIELD|XmlXcb#LISTFIELD]] protocol description macro.

## Requests

Every request declared using the [[REQUEST|XmlXcb#REQUEST]] or [[VOIDREQUEST|XmlXcb#VOIDREQUEST]] protocol description macros generates an assortment of types and functions.

The base C name for all types and functions related to the X request with name "Name" is `xcb_name`. If the request is from an extension, then "Name" is composed by prefixing the extension name onto the request name.

<a name="xcb_name_cookie_t"></a>

### `xcb_name_cookie_t`

		typedef struct {
			unsigned int sequence;
		} xcb_name_cookie_t;

A special cookie type, `xcb_void_cookie_t`, is declared in xcb.h. See [`xcb_name`](#xcb_name).

### `xcb_name_request_t`

		typedef struct {
			uint8_t major_opcode;
			/* first single-byte field, uint8_t minor_opcode, or one byte of padding */
			uint16_t length;
			...
		} xcb_name_request_t;

### `xcb_name_reply_t`

		typedef struct {
			uint8_t response_type;
			/* first single-byte field or one byte of padding */
			uint16_t sequence;
			uint32_t length;
			...
			/* padding to 32 bytes */
		} xcb_name_reply_t;

`response_type` always equals 1 in a reply.

A special reply type, `xcb_generic_reply_t`, is declared in xcb.h. It contains only the fields common to all replies.

<a name="xcb_name"></a>

### `xcb_name`

		Cookie
		xcb_name (xcb_connection_t *c, ...); 

Delivers a request with the specified arguments to the X server.

If the request will cause a reply to be generated, then an [`xcb_name_cookie_t`](#xcb_name_cookie_t) will be returned and the [`xcb_name_reply_t`](#xcb_name_reply_t) function should be used to obtain the actual reply. Any error generated by the X server in response to this request will be returned through any supplied error pointer in the corresponding Reply function rather than being placed in the event queue. If no error pointer is supplied, the error will be discarded.

Otherwise, an [`xcb_void_cookie_t`](#xcb_name_cookie_t) will be returned, and no [`xcb_name_reply_t`](#xcb_name_reply_t) function will be provided. Any error generated by the X server in response to this request will be placed in the event queue.

<a name="xcb_name_checked"></a>

### `xcb_name_checked`

		xcb_void_cookie_t
		xcb_name_checked (xcb_connection_t *c, ...);

Delivers a request with the specified arguments to the X server.

This form can be used only if the request will not cause a reply to be generated. It behaves as `xcb_name`, except that any returned error will be saved for handling by [`xcb_request_check()`](#xcb_request_check) rather than being placed in the event queue.

<a name="xcb_name_unchecked"></a>

### `xcb_name_unchecked`

		Cookie
		xcb_name_unchecked (xcb_connection_t *c, ...);

Delivers a request with the specified arguments to the X server.

This form can be used only if the request will cause a reply to be generated. It behaves as `xcb_name`, except that any returned error will be placed in the event queue rather than being handled by [`xcb_name_reply()`](#xcb_name_reply).

<a name="xcb_name_reply"></a>

### `xcb_name_reply`

		xcb_name_reply_t *
		xcb_name_reply (xcb_connection_t *c,
						 xcb_name_cookie_t cookie,
						 xcb_generic_error_t **e );

The `xcb_generic_error_t **e` supplied to this function must be zero if the cookie was produced using the unchecked version of the request function; otherwise, if an error occurs and the pointer is nonzero the error will be stored into it. See [`xcb_name()`](#xcb_name) and [`xcb_name_unchecked()`](#xcb_name_unchecked).  This function returns a pointer to freshly-malloced storage that may be freed when it is no longer needed.

<a name="xcb_request_check"></a>

### `xcb_request_check`

		xcb_generic_error_t *
		xcb_request_check (xcb_connection_t *c,
						   xcb_void_cookie_t cookie );

The `xcb_void_cookie_t cookie` supplied to this function must have resulted from a call to [`xcb_name_checked()`](#xcb_name_checked). This function will block until one of two conditions happens. If an error is received, it will be returned. If no error can be received, because the sequence number has advanced beyond that provided in `cookie`, 0 will be returned.

/!\ Note that this function will perform an `xcb_aux_sync()` if needed to ensure that the sequence number will advance beyond that provided in `cookie`; this is a convenience to avoid races in determining whether the sync is needed. If you want a version of this call that never performs this implicit sync (e.g. because you are writing in a multi-threaded implementation in which another thread will eventually issue a request), please let us know, and we will consider adding it.

### `xcb_name_field_iterator`

		xcb_base_type_iterator_t
		xcb_name_field_iterator (xcb_name_reply_t *R);

### `xcb_name_field`

		BaseType *
		xcb_name_field (xcb_name_reply_t *R);

### `xcb_name_field_length`

		int
		xcb_name_field_length (xcb_name_reply_t *R);

### `xcb_name_field_end`

		xcb_generic_iterator_t
		xcb_name_field_end (xcb_name_reply_t *R);

## Events and Errors

### `xcb_event_name_event_t`

		typedef struct {
	         uint8_t response_type;
	         /* first single-byte field or one byte of padding */
	         uint16_t sequence;
	         ...
	         /* padding to 32 bytes */
		} xcb_event_name_event_t;

`response_type` equals the event number. See [`XCB_EVENT_NAME`](#XCB_EVENT_NAME).

A special event type, `xcb_generic_event_t`, is declared in xcb.h. It contains only the fields common to all events.

<a name="XCB_EVENT_NAME"></a>

### `XCB_EVENT_NAME`

		#define XCB_EVENT_NAME number

### `xcb_error_name_error_t`

		typedef struct {
			uint8_t response_type;
			uint8_t error_code;
			uint16_t sequence;
			...
			/* padding to 32 bytes */
		} xcb_error_name_error_t;

`response_type` always equals 0 for errors.

`error_code` equals the error number. See [`XCB_ERROR_NAME`](#XCB_ERROR_NAME).

A special error type, `xcb_generic_error_t`, is declared in xcb.h. It contains only the fields common to all errors.

<a name="XCB_ERROR_NAME"></a>

### `XCB_ERROR_NAME`

		#define XCB_ERROR_NAME number