From 990bc3f015a4f8fce2eb918375defcd44980a845 Mon Sep 17 00:00:00 2001 From: marha Date: Fri, 8 Jun 2012 09:33:13 +0200 Subject: Used synchronise script to update files --- libxcb/doc/xkb_internals | 98 ++++++++++++++++++++++++------------------------ 1 file changed, 49 insertions(+), 49 deletions(-) (limited to 'libxcb/doc/xkb_internals') diff --git a/libxcb/doc/xkb_internals b/libxcb/doc/xkb_internals index 3e103910c..93c6d0170 100644 --- a/libxcb/doc/xkb_internals +++ b/libxcb/doc/xkb_internals @@ -1,49 +1,49 @@ - -XKB introduces several uncommon data structures: - - switch allows conditional inclusion of fields - - several complex objects intermix variable and fixed size fields - - lists with a variable number of variable size objects - -To handle these objects, a number of new functions is generated: - - _serialize() turns a structured object into a byte stream, - (re)ordering or including fields according to the protocol - - _unserialize() rewrites data from a buffer into a structured object - - _unpack() expands a buffer representing a switch object into - a special structured type, all flags needed to resolve the switch - expression have to given as parameters - - _sizeof() calculates the size of a serialized object, often by calling - _unserialize()/_unpack() internally - -The new structured data type for switch is special as it contains fixed -and variable size fields. Variable size fields can be accessed via pointers. - -If switch appears in a request, an additional set of request helpers is -generated with the suffix _aux or _aux_(un)checked. While the 'common' -request functions require that switch has been serialized before, the _aux -variants take the structured data type. They are especially designed to -replace certain functions in xcb-util/aux. - -Accessors for switch members need two parameters, where the first is usually -a pointer to the respective request or reply structure, while the second -is a pointer to the unpacked switch data structure. - -Functions from the serialize family that take a double pointer can allocate -memory on their own, which is useful if the size of a buffer has to be -calculated depending on the data within. These functions call malloc() when -the double pointer is given as the address of a pointer that has been -initialized to 0. It is the responsibility of the user to free any allocated -memory. - -Intermixed variable and fixed size fields are an important special case in XKB. -The current implementation resolves the issue by reordering the fields before -sending them on the wire as well as before returning a reply. That means that -these objects look like 'common' XCB data types and they can be accessed as such -(i.e. fixed size fields directly via the structured type and variable size fields -via accessors/iterators). - -In case a list with variable size elements needs to be accessed, it is necessary -to use iterators. The iterator functions take care of determining the actual -object size for each element automatically. - -A small and preliminary set of auxiliary functions is available in xkb_util.c -in the check_xkb module. + +XKB introduces several uncommon data structures: + - switch allows conditional inclusion of fields + - several complex objects intermix variable and fixed size fields + - lists with a variable number of variable size objects + +To handle these objects, a number of new functions is generated: + - _serialize() turns a structured object into a byte stream, + (re)ordering or including fields according to the protocol + - _unserialize() rewrites data from a buffer into a structured object + - _unpack() expands a buffer representing a switch object into + a special structured type, all flags needed to resolve the switch + expression have to given as parameters + - _sizeof() calculates the size of a serialized object, often by calling + _unserialize()/_unpack() internally + +The new structured data type for switch is special as it contains fixed +and variable size fields. Variable size fields can be accessed via pointers. + +If switch appears in a request, an additional set of request helpers is +generated with the suffix _aux or _aux_(un)checked. While the 'common' +request functions require that switch has been serialized before, the _aux +variants take the structured data type. They are especially designed to +replace certain functions in xcb-util/aux. + +Accessors for switch members need two parameters, where the first is usually +a pointer to the respective request or reply structure, while the second +is a pointer to the unpacked switch data structure. + +Functions from the serialize family that take a double pointer can allocate +memory on their own, which is useful if the size of a buffer has to be +calculated depending on the data within. These functions call malloc() when +the double pointer is given as the address of a pointer that has been +initialized to 0. It is the responsibility of the user to free any allocated +memory. + +Intermixed variable and fixed size fields are an important special case in XKB. +The current implementation resolves the issue by reordering the fields before +sending them on the wire as well as before returning a reply. That means that +these objects look like 'common' XCB data types and they can be accessed as such +(i.e. fixed size fields directly via the structured type and variable size fields +via accessors/iterators). + +In case a list with variable size elements needs to be accessed, it is necessary +to use iterators. The iterator functions take care of determining the actual +object size for each element automatically. + +A small and preliminary set of auxiliary functions is available in xkb_util.c +in the check_xkb module. -- cgit v1.2.3