6 XML-XCB generates C bindings to the X Window System protocol based on XML
7 descriptions of the protocol. It is designed for use with XCB, the X C
8 binding <http://xcb.freedesktop.org>. XML-XCB consists of:
10 xcb.xsd An XML Schema defining the data format for describing the X
11 protocol. Included in xcb-proto.
13 c-client.xsl An XSLT code generator that transforms the protocol descriptions
14 into C bindings. Included in xcb.
16 *.xml XML descriptions of the core X protocol and many extensions.
17 Included in xcb-proto.
23 c-client.xsl requires an XSLT processor that supports XSLT 1.0
24 <http://www.w3.org/TR/1999/REC-xslt-19991116> and the EXSLT node-set extension
25 <http://www.exslt.org/exsl/functions/node-set/index.html>. The XCB build
26 system currently uses xsltproc. You can get xsltproc through your
27 distribution's packaging system, or from <http://xmlsoft.org/XSLT/>.
33 The C bindings for the core protocol and all the currently supported
34 extensions are built as part of the xcb build system. However, for the
35 purposes of creating and debugging new protocol descriptions, it can be useful
36 to generate the bindings directly by invoking c-client.xsl to the XML protocol
39 You must provide several parameters to c-client.xsl:
41 mode: header or source; specifies which part of the C bindings to generate.
42 base-path: path to the core X protocol descriptions.
43 extension-path: path to the extension descriptions.
45 For example, using xsltproc, you can generate the header for a protocol
46 description "protocol.xml" with the command:
48 xsltproc --stringparam base-path /path/to/xcb-proto/src \
49 --stringparam extension-path /path/to/xcb-proto/src/extensions \
50 --stringparam mode header /path/to/xcb/src/c-client.xsl protocol.xml
53 Protocol Description Format
54 ===========================
59 <xcb header="string" extension-name="string" extension-xname="string">
63 This is the root element of a protocol description. The attributes are all
64 various forms of the extension name. header is the basename of the XML
65 protocol description file, which will be used as the basename for generated
66 bindings as well. extension-name is the name of the extension in InterCaps,
67 which will be used in the names of functions. extension-xname is the name
68 of the extension as passed to QueryExtension.
70 As an example, the XML-XCB description for the GO-FASTER extension would use
71 the root element <xcb header="gofaster" extension-name="GoFaster"
72 extension-xname="GO-FASTER">; as a result, C bindings will be put in
73 gofaster.h and gofaster.c, extension functions will be named
74 XCBGoFasterFunctionName, and the extension initialization will call
75 QueryExtension with the name "GO-FASTER".
77 This element can contain any number of the elements listed in the section
78 "Top-Level Elements" below.
84 <import>header_name</import>
86 The import element allows the protocol description to reference types
87 declared in another extension. The content is be the basename of the
88 extension XML file, which is also the header attribute of the extension's
89 root node. Note that types from xproto are automatically available, without
90 explicitly importing them.
92 <struct name="identifier">structure contents</struct>
94 This element represents a data structure. The name attribute gives the name
95 of the structure. The content represents the fields of the structure, and
96 consists of one or more of the field, pad, and list elements described in
97 the section "Structure Contents" below.
99 <union name="identifier">structure contents</union>
101 This element represents a union of data types, which can hold one value of
102 any of those types. The name attribute gives the name of the union. The
103 content represents the fields of the union, and consists of one or more of
104 the field and pad elements described in the section "Structure Contents
107 <xidtype name="identifier" />
109 This element represents an identifier for a particular type of resource.
110 The name attribute gives the name of the new type.
112 <enum name="identifier">
113 <item name="identifier">[optional expression]</item>
117 The enum element represents an enumeration type, which can take on any of
118 the values given by the contained item elements. The name attribute on the
119 enum gives the name of the enumerated type.
121 The item element represents one possible value of an enumerated type. The
122 name attribute on the item gives the name of that value, and the optional
123 content is an expression giving the numeric value. If the expression is
124 omitted, the value will be one more than that of the previous item, or 0 for
127 <typedef oldname="identifier" newname="identifier" />
129 The typedef element declares the type given by the newname attribute to be
130 an alias for the type given by the oldname attribute.
132 <request name="identifier" opcode="integer" [combine-adjacent="true"]>
134 [<reply>structure contents</reply>]
137 The request element represents an X protocol request. The name attribute
138 gives the name of the request, and the opcode attribute gives the numeric
139 request code. The content of the request element represents the fields in
140 the request, and consists of one or more of any of the elements listed in
141 the "Structure Contents" section below. Note that for requests in the core
142 protocol, the first field in the request goes into the one-byte gap between
143 the major opcode and the length; if the request does not have any data in
144 that gap, put a one byte pad as the first element. Extension requests
145 always have this gap filled with the minor opcode.
147 The optional reply element is present if the request has a reply. The
148 content of the reply element represents the fields in the reply, and
149 consists of zero or more of the field, pad, and list elements listed in the
150 "Structure Contents" section below. Note that the first field in the reply
151 always goes into the one-byte gap between the response type and the sequence
152 number; if the reply does not have any data in that gap, put a one byte pad
153 as the first element.
155 If the optional combine-adjacent attribute is true, multiple adjacent
156 requests of the same type may be combined into a single request without
157 affecting the semantics of the requests.
159 <event name="identifier" number="integer" [no-sequence-number="true"]>
163 This element represents an X protocol event. The name attribute gives the
164 name of the event, and the number attribute gives the event number. The
165 content of the event element represents the fields in the event, and
166 consists of zero or more of the field, pad, and list elements listed in the
167 "Structure Contents" section below.
169 If the optional no-sequence-number attribute is true, the event does not
170 include a sequence number. This is a special-case for the KeymapNotify
171 event in the core protocol, and should not be used in any other event.
173 <error name="identifier" number="integer">
177 This element represents an X protocol error. The name attribute gives the
178 name of the error, and the number attribute gives the error number. The
179 content of the error element represents the fields in the error, and
180 consists of zero or more of the field, pad, and list elements listed in the
181 "Structure Contents" section below.
183 <eventcopy name="identifier" number="identifier" ref="identifier" />
185 This element creates an alias for the event named in the ref attribute, with
186 the new name given in the name attribute, and the new event number given in
187 the number attribute.
189 <errorcopy name="identifier" number="identifier" ref="identifier" />
191 This element creates an alias for the error named in the ref attribute, with
192 the new name given in the name attribute, and the new error number given in
193 the number attribute.
199 Note: "type" attributes below refer to types defined by previous elements,
200 either in the current extension, xproto, or one of the imported extensions.
201 The type name must refer to only one possible type; if more than one type
202 matches, an error occurs. To avoid this, the type may be explicitly prefixed
203 with a namespace, which should be the value of the header attribute on the
204 protocol description containing the desired type. The namespace and type are
205 separated by a single colon. For example, to refer to the PIXMAP type defined
206 in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
209 <pad bytes="integer" />
211 This element declares some padding in a data structure. The bytes
212 attribute declares the number of bytes of padding.
214 <field type="identifier" name="identifier" />
216 This element represents a field in a data structure. The type attribute
217 declares the data type of the field, and the name attribute gives the name
220 <list type="identifier" name="identifier">expression</list>
222 This element represents an array or list of fields in a data structure. The
223 type attribute declares the data type of the field, and the name attribute
224 gives the name of the field. The content is an expression giving the length
225 of the list in terms of other fields in the structure. See the section
226 "Expressions" for details on the expression representation.
228 <localfield type="identifier" name="identifier" />
230 This element represents a parameter in a request that is not sent over the
231 wire. The field can be referenced in the length expressions of lists or in
232 an exprfield. The type attribute declares the data type of the field, and
233 the name attribute gives the name of the field.
235 <exprfield type="identifier" name="identifier">expression</exprfield>
237 This element represents a field in a request that is calculated rather than
238 supplied by the caller. The type attribute declares the data type of the
239 field, and the name attribute gives the name of the field. The content is
240 the expression giving the value of the field. See the section "Expressions"
241 for details on the expression representation.
243 <valueparam value-mask-type="identifier" value-mask-name="identifier"
244 value-list-name="identifier" />
246 This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
247 defining the set of values included, and a list containing these values.
248 value-mask-type gives the type of the bitmask; this must be CARD16 or
249 CARD32. value-mask-name gives the field name of the bitmask, and
250 value-list-name gives the field name of the list of values.
256 Expressions consist of a tree of <op> elements with leaves consisting of
257 <fieldref> or <value> elements.
259 <op op="operator">expression expression</op>
261 The op element represents an operator, with the op attribute specifying
262 which operator. The supported operations are +, -, *, /, &, and
263 <<, and their semantics are identical to the corresponding operators
264 in C. The two operand expressions may be other expression elements.
266 <fieldref>identifier</fieldref>
268 The fieldref element represents a reference to the value of another field in
269 the structure containing this expression. The identifier is the value of
270 the "name" attribute on the referenced field.
272 <value>integer</value>
274 The value element represents a literal integer value in an expression. The
275 integer may be expressed in decimal or hexadecimal.
279 The bit element represents a literal bitmask value in an expression.
280 The integer must be in the range 0..31, expanding to (1<<n) in C.