xkb_internals revision 21298544
121298544Smrg 221298544SmrgXKB introduces several uncommon data structures: 321298544Smrg - switch allows conditional inclusion of fields 421298544Smrg - several complex objects intermix variable and fixed size fields 521298544Smrg - lists with a variable number of variable size objects 621298544Smrg 721298544SmrgTo handle these objects, a number of new functions is generated: 821298544Smrg - _serialize() turns a structured object into a byte stream, 921298544Smrg (re)ordering or including fields according to the protocol 1021298544Smrg - _unserialize() rewrites data from a buffer into a structured object 1121298544Smrg - _unpack() expands a buffer representing a switch object into 1221298544Smrg a special structured type, all flags needed to resolve the switch 1321298544Smrg expression have to given as parameters 1421298544Smrg - _sizeof() calculates the size of a serialized object, often by calling 1521298544Smrg _unserialize()/_unpack() internally 1621298544Smrg 1721298544SmrgThe new structured data type for switch is special as it contains fixed 1821298544Smrgand variable size fields. Variable size fields can be accessed via pointers. 1921298544Smrg 2021298544SmrgIf switch appears in a request, an additional set of request helpers is 2121298544Smrggenerated with the suffix _aux or _aux_(un)checked. While the 'common' 2221298544Smrgrequest functions require that switch has been serialized before, the _aux 2321298544Smrgvariants take the structured data type. They are especially designed to 2421298544Smrgreplace certain functions in xcb-util/aux. 2521298544Smrg 2621298544SmrgAccessors for switch members need two parameters, where the first is usually 2721298544Smrga pointer to the respective request or reply structure, while the second 2821298544Smrgis a pointer to the unpacked switch data structure. 2921298544Smrg 3021298544SmrgFunctions from the serialize family that take a double pointer can allocate 3121298544Smrgmemory on their own, which is useful if the size of a buffer has to be 3221298544Smrgcalculated depending on the data within. These functions call malloc() when 3321298544Smrgthe double pointer is given as the address of a pointer that has been 3421298544Smrginitialized to 0. It is the responsibility of the user to free any allocated 3521298544Smrgmemory. 3621298544Smrg 3721298544SmrgIntermixed variable and fixed size fields are an important special case in XKB. 3821298544SmrgThe current implementation resolves the issue by reordering the fields before 3921298544Smrgsending them on the wire as well as before returning a reply. That means that 4021298544Smrgthese objects look like 'common' XCB data types and they can be accessed as such 4121298544Smrg(i.e. fixed size fields directly via the structured type and variable size fields 4221298544Smrgvia accessors/iterators). 4321298544Smrg 4421298544SmrgIn case a list with variable size elements needs to be accessed, it is necessary 4521298544Smrgto use iterators. The iterator functions take care of determining the actual 4621298544Smrgobject size for each element automatically. 4721298544Smrg 4821298544SmrgA small and preliminary set of auxiliary functions is available in xkb_util.c 4921298544Smrgin the check_xkb module. 50