1
2XKB introduces several uncommon data structures:
3 - switch allows conditional inclusion of fields
4 - several complex objects intermix variable and fixed size fields
5 - lists with a variable number of variable size objects
6
7To handle these objects, a number of new functions is generated:
8 - _serialize() turns a structured object into a byte stream, 
9   (re)ordering or including fields according to the protocol
10 - _unserialize() rewrites data from a buffer into a structured object
11 - _unpack() expands a buffer representing a switch object into 
12   a special structured type, all flags needed to resolve the switch
13   expression have to given as parameters
14 - _sizeof() calculates the size of a serialized object, often by calling
15   _unserialize()/_unpack() internally
16
17The new structured data type for switch is special as it contains fixed 
18and variable size fields. Variable size fields can be accessed via pointers. 
19
20If switch appears in a request, an additional set of request helpers is 
21generated with the suffix _aux or _aux_(un)checked. While the 'common'
22request functions require that switch has been serialized before, the _aux
23variants take the structured data type. They are especially designed to 
24replace certain functions in xcb-util/aux. 
25
26Accessors for switch members need two parameters, where the first is usually
27a pointer to the respective request or reply structure, while the second 
28is a pointer to the unpacked switch data structure. 
29
30Functions from the serialize family that take a double pointer can allocate 
31memory on their own, which is useful if the size of a buffer has to be 
32calculated depending on the data within. These functions call malloc() when 
33the double pointer is given as the address of a pointer that has been 
34initialized to 0. It is the responsibility of the user to free any allocated
35memory. 
36
37Intermixed variable and fixed size fields are an important special case in XKB. 
38The current implementation resolves the issue by reordering the fields before
39sending them on the wire as well as before returning a reply. That means that 
40these objects look like 'common' XCB data types and they can be accessed as such 
41(i.e. fixed size fields directly via the structured type and variable size fields
42via accessors/iterators).  
43
44In case a list with variable size elements needs to be accessed, it is necessary 
45to use iterators. The iterator functions take care of determining the actual 
46object size for each element automatically. 
47
48A small and preliminary set of auxiliary functions is available in xkb_util.c 
49in the check_xkb module.  
50