6 xcb/proto is a set of XML files describing the X Window System protocol
7 It is designed for use with libxcb, the X C binding
8 <http://xcb.freedesktop.org/>. xcb/proto consists of:
10 xcb.xsd An XML Schema defining the data format for describing the X
13 *.py Code generator helpers that read the protocol descriptions
14 into python structures. See libxcb for example usage.
16 *.xml XML descriptions of the core X protocol and many extensions.
22 See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
25 Protocol Description Format
26 ===========================
31 <xcb header="string" extension-name="string" extension-xname="string">
35 This is the root element of a protocol description. The attributes are all
36 various forms of the extension name. header is the basename of the XML
37 protocol description file, which will be used as the basename for generated
38 bindings as well. extension-name is the name of the extension in InterCaps,
39 which will be used in the names of functions. extension-xname is the name
40 of the extension as passed to QueryExtension.
42 As an example, the XML-XCB description for the GO-FASTER extension would use
43 the root element <xcb header="gofaster" extension-name="GoFaster"
44 extension-xname="GO-FASTER">; as a result, C bindings will be put in
45 gofaster.h and gofaster.c, extension functions will be named
46 XCBGoFasterFunctionName, and the extension initialization will call
47 QueryExtension with the name "GO-FASTER".
49 This element can contain any number of the elements listed in the section
50 "Top-Level Elements" below.
56 <import>header_name</import>
58 The import element allows the protocol description to reference types
59 declared in another extension. The content is be the basename of the
60 extension XML file, which is also the header attribute of the extension's
61 root node. Note that types from xproto are automatically available, without
62 explicitly importing them.
64 <struct name="identifier">structure contents</struct>
66 This element represents a data structure. The name attribute gives the name
67 of the structure. The content represents the fields of the structure, and
68 consists of one or more of the field, pad, and list elements described in
69 the section "Structure Contents" below.
71 <union name="identifier">structure contents</union>
73 This element represents a union of data types, which can hold one value of
74 any of those types. The name attribute gives the name of the union. The
75 content represents the fields of the union, and consists of one or more of
76 the field and pad elements described in the section "Structure Contents
79 <xidtype name="identifier" />
81 This element represents an identifier for a particular type of resource.
82 The name attribute gives the name of the new type.
84 <enum name="identifier">
85 <item name="identifier">[optional expression]</item>
89 The enum element represents an enumeration type, which can take on any of
90 the values given by the contained item elements. The name attribute on the
91 enum gives the name of the enumerated type.
93 The item element represents one possible value of an enumerated type. The
94 name attribute on the item gives the name of that value, and the optional
95 content is an expression giving the numeric value. If the expression is
96 omitted, the value will be one more than that of the previous item, or 0 for
99 <typedef oldname="identifier" newname="identifier" />
101 The typedef element declares the type given by the newname attribute to be
102 an alias for the type given by the oldname attribute.
104 <request name="identifier" opcode="integer" [combine-adjacent="true"]>
106 [<reply>structure contents</reply>]
109 The request element represents an X protocol request. The name attribute
110 gives the name of the request, and the opcode attribute gives the numeric
111 request code. The content of the request element represents the fields in
112 the request, and consists of one or more of any of the elements listed in
113 the "Structure Contents" section below. Note that for requests in the core
114 protocol, the first field in the request goes into the one-byte gap between
115 the major opcode and the length; if the request does not have any data in
116 that gap, put a one byte pad as the first element. Extension requests
117 always have this gap filled with the minor opcode.
119 The optional reply element is present if the request has a reply. The
120 content of the reply element represents the fields in the reply, and
121 consists of zero or more of the field, pad, and list elements listed in the
122 "Structure Contents" section below. Note that the first field in the reply
123 always goes into the one-byte gap between the response type and the sequence
124 number; if the reply does not have any data in that gap, put a one byte pad
125 as the first element.
127 If the optional combine-adjacent attribute is true, multiple adjacent
128 requests of the same type may be combined into a single request without
129 affecting the semantics of the requests.
131 <event name="identifier" number="integer"
132 [[no-sequence-number="true"] | [xge="true"]]>
136 This element represents an X protocol event. The name attribute gives the
137 name of the event, and the number attribute gives the event number. The
138 content of the event element represents the fields in the event, and
139 consists of zero or more of the field, pad, and list elements listed in the
140 "Structure Contents" section below.
142 If the optional no-sequence-number attribute is true, the event does not
143 include a sequence number. This is a special-case for the KeymapNotify
144 event in the core protocol, and should not be used in any other event.
146 If the optional xge attribute is true, the event is an X Generic Event and
147 will be treated as such.
149 The no-sequence-number and xge attribute can not be combined.
151 <error name="identifier" number="integer">
155 This element represents an X protocol error. The name attribute gives the
156 name of the error, and the number attribute gives the error number. The
157 content of the error element represents the fields in the error, and
158 consists of zero or more of the field, pad, and list elements listed in the
159 "Structure Contents" section below.
161 <eventcopy name="identifier" number="identifier" ref="identifier" />
163 This element creates an alias for the event named in the ref attribute, with
164 the new name given in the name attribute, and the new event number given in
165 the number attribute.
167 <errorcopy name="identifier" number="identifier" ref="identifier" />
169 This element creates an alias for the error named in the ref attribute, with
170 the new name given in the name attribute, and the new error number given in
171 the number attribute.
177 Note: "type" attributes below refer to types defined by previous elements,
178 either in the current extension, xproto, or one of the imported extensions.
179 The type name must refer to only one possible type; if more than one type
180 matches, an error occurs. To avoid this, the type may be explicitly prefixed
181 with a namespace, which should be the value of the header attribute on the
182 protocol description containing the desired type. The namespace and type are
183 separated by a single colon. For example, to refer to the PIXMAP type defined
184 in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
187 Note: Most of the below may optionally contain an enum, altenum, mask or altmask
188 attribute, which follows the above rules for "type". "enum" is an exhaustive
189 enum; the value is restricted to one of the constants named in the enum.
190 "altenum" may be one of the values contained in the enum, but it need not be.
191 "mask" refers to an exhaustive enum to be used as a bitmask.
192 "altmask" may be a mask from the referred enum, but it need not be.
194 <pad bytes="integer" />
196 This element declares some padding in a data structure. The bytes
197 attribute declares the number of bytes of padding.
199 <field type="identifier" name="identifier" />
201 This element represents a field in a data structure. The type attribute
202 declares the data type of the field, and the name attribute gives the name
205 <fd name="identifier" />
207 This element represents a file descriptor field passed with the request. The
208 name attribute gives the name of the field.
210 While ordinary fields are encoded as part of the request, file descriptor
211 fields are generally passed via an out-of-band mechanism.
213 <list type="identifier" name="identifier">expression</list>
215 This element represents an array or list of fields in a data structure. The
216 type attribute declares the data type of the field, and the name attribute
217 gives the name of the field. The content is an expression giving the length
218 of the list in terms of other fields in the structure. See the section
219 "Expressions" for details on the expression representation.
221 <localfield type="identifier" name="identifier" />
223 This element represents a parameter in a request that is not sent over the
224 wire. The field can be referenced in the length expressions of lists or in
225 an exprfield. The type attribute declares the data type of the field, and
226 the name attribute gives the name of the field.
228 <exprfield type="identifier" name="identifier">expression</exprfield>
230 This element represents a field in a request that is calculated rather than
231 supplied by the caller. The type attribute declares the data type of the
232 field, and the name attribute gives the name of the field. The content is
233 the expression giving the value of the field. See the section "Expressions"
234 for details on the expression representation.
236 <valueparam value-mask-type="identifier" value-mask-name="identifier"
237 value-list-name="identifier" />
239 This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
240 defining the set of values included, and a list containing these values.
241 value-mask-type gives the type of the bitmask; this must be CARD16 or
242 CARD32. value-mask-name gives the field name of the bitmask, and
243 value-list-name gives the field name of the list of values. Please use
244 <switch> instead for new protocol definitions.
246 <switch name="identifier"> switch expression
247 <bitcase> bitcase expression(s), fields </bitcase>
248 <case> case expression(s), fields </case>
251 This element represents conditional inclusion of fields. It can be viewed
252 as sequence of multiple ifs:
255 if ( switch expression & bitcase expression ) is non-zero,
256 bitcase fields are included in structure.
259 if ( switch expression == case expression ) is true,
260 then case fields are included in structure.
262 It can be used only as the last field of a structure.
264 When a bitcase or case includes multiple <enumref> clauses, the contents
265 of the bitcase or case are only present once regardless of the number of
266 bitcase or case expressions that match.
268 <enumref> inside <bitcase> can only refer to an enum's <bit> members.
269 <enumref> inside <case> can only refer to an enum's <value> members.
271 A switch may contain multiple <bitcase> or <case> elements.
272 Usually it will only contain <bitcase> elements
273 or only contain <case> elements.
274 That is, mixing of <case> and <bitcase> usually doesn't make any sense.
276 The same value may appear in multiple <case> or <bitcase> elements.
278 New protocol definitions should prefer to use this instead of <valueparam>
279 and instead of <union>.
285 Expressions consist of a tree of <op> elements with leaves consisting of
286 <fieldref> or <value> elements.
288 <op op="operator">expression expression</op>
290 The op element represents an operator, with the op attribute specifying
291 which operator. The supported operations are +, -, *, /, &, and
292 <<, and their semantics are identical to the corresponding operators
293 in C. The two operand expressions may be other expression elements.
295 <fieldref>identifier</fieldref>
297 The fieldref element represents a reference to the value of another field in
298 the structure containing this expression. The identifier is the value of
299 the "name" attribute on the referenced field.
301 <value>integer</value>
303 The value element represents a literal integer value in an expression. The
304 integer may be expressed in decimal or hexadecimal.
308 The bit element represents a literal bitmask value in an expression.
309 The integer must be in the range 0..31, expanding to (1<<n) in C.
311 <enumref ref="identifier">enum item identifier</enumref>
313 This element represents a reference to item of enum.
315 <unop op="operator">expression</unop>
317 This element represents a unary operator, with the op attribute specifying
318 which operator. The only supported operation so far is ~, and its semantic
319 is identical to the corresponding operator in C.
321 <sumof ref="identifier" />
323 This element represents a sumation of the elements of the referenced list.
325 <popcount>expression</popcount>
327 This element represents the number of bits set in the expression.
332 Documentation for each request, reply or event is stored in the appropriate
333 element using a <doc> element. The <doc> element can contain the following
336 <brief>brief description</brief>
338 A short description of the request, reply or event. For example "makes a
339 window visible" for MapWindow. This will end up in the manpage NAME section
340 and in the doxygen @brief description.
342 <description><![CDATA[longer description]]></description>
344 The full description. Use `` to highlight words, such as "Draws
345 `points_len`-1 lines between each pair of points…"
347 <example><![CDATA[example code]]</description>
349 Example C code illustrating the usage of the particular request, reply or
352 <field name="name">field description</field>
354 The full description for the specified field. Depending on the context, this
355 is either a request parameter or a reply/event datastructure field.
357 <error type="type">error description</field>
359 The full description for an error which can occur due to this request.
361 <see type="request" name="name" />
363 A reference to another relevant program, function, request or event.