git.demorecorder.com Git - free-sw/xcb/libxcb/blob - doc/xkb_internals

   1
   2 XKB 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
   7 To 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
  17 The new structured data type for switch is special as it contains fixed
  18 and variable size fields. Variable size fields can be accessed via pointers.
  19
  20 If switch appears in a request, an additional set of request helpers is
  21 generated with the suffix _aux or _aux_(un)checked. While the 'common'
  22 request functions require that switch has been serialized before, the _aux
  23 variants take the structured data type. They are especially designed to
  24 replace certain functions in xcb-util/aux.
  25
  26 Accessors for switch members need two parameters, where the first is usually
  27 a pointer to the respective request or reply structure, while the second
  28 is a pointer to the unpacked switch data structure.
  29
  30 Functions from the serialize family that take a double pointer can allocate
  31 memory on their own, which is useful if the size of a buffer has to be
  32 calculated depending on the data within. These functions call malloc() when
  33 the double pointer is given as the address of a pointer that has been
  34 initialized to 0. It is the responsibility of the user to free any allocated
  35 memory.
  36
  37 Intermixed variable and fixed size fields are an important special case in XKB.
  38 The current implementation resolves the issue by reordering the fields before
  39 sending them on the wire as well as before returning a reply. That means that
  40 these 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
  42 via accessors/iterators).
  43
  44 In case a list with variable size elements needs to be accessed, it is necessary
  45 to use iterators. The iterator functions take care of determining the actual
  46 object size for each element automatically.
  47
  48 A small and preliminary set of auxiliary functions is available in xkb_util.c
  49 in the check_xkb module.