Add element to specify expression that defines length of a struct

Currently the layout of a struct is used to compute its size. This works
fine in case of structs of fixed size. However this introduces
forwards-compatibility problems in cases when the struct has multiple
variants and the exact variant is specified by the value of some field
(e.g. in the case of <switch> elements). Future revisions of protocols
may introduce new layout variants, in which case the old code does not
know the size of the struct variant and can't parse the incoming byte
stream.

Instead of relying on knowledge about the layout of data structures we
should instead use the length field for length information. This way
when old client libxcb communicates with newer server it can at least
ignore unknown struct variants.

1 files changed, 19 insertions, 2 deletions

diff --git a/doc/xml-xcb.txt b/doc/xml-xcb.txt
index f5b9aed..baef734 100644
--- a/doc/xml-xcb.txt
+++ b/doc/xml-xcb.txt
@@ -65,8 +65,8 @@ Top-Level Elements
 
   This element represents a data structure.  The name attribute gives the name
   of the structure.  The content represents the fields of the structure, and
-  consists of one or more of the field, pad, and list elements described in
-  the section "Structure Contents" below.
+  consists of one or more of the length, field, pad, and list elements described
+  in the section "Structure Contents" below.
 
 <union name="identifier">structure contents</union>
 
@@ -215,6 +215,23 @@ enum; the value is restricted to one of the constants named in the enum.
   declares the data type of the field, and the name attribute gives the name
   of the field.
 
+<length>expression</length>
+  This element overrides the length of the data structure by specifying it
+  explicitly instead of it being defined by the layout of the structure.
+  This makes it possible to handle structures with conditional fields
+  (see the <switch> element) where the future revisions of protocols may
+  introduce new variants and old code must still properly ignore them.
+
+  The content is an expression giving the length of the data structure in terms
+  of other fields in the structure.  See the section "Expressions" for details
+  on the expression representation.
+
+  The expression must not depend on conditional fields.
+
+  Additionally, the length of the data structure must be at least such that it
+  includes the fields that the expression depends on. Smaller length is
+  considered a violation of the protocol.
+
 <fd name="identifier" />
 
   This element represents a file descriptor field passed with the request.  The