xml-xcb spec: describe switch-case

[free-sw/xcb/proto] / doc / xml-xcb.txt

                                  xcb/proto

Description
===========

xcb/proto is a set of XML files describing the  X Window System protocol
It is designed for use with libxcb, the X C binding
<http://xcb.freedesktop.org/>.  xcb/proto consists of:

xcb.xsd      An XML Schema defining the data format for describing the X
             protocol.

*.py         Code generator helpers that read the protocol descriptions
             into python structures. See libxcb for example usage.

*.xml        XML descriptions of the core X protocol and many extensions.


Generating C bindings
=====================

See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.


Protocol Description Format
===========================

Root element
------------

<xcb header="string" extension-name="string" extension-xname="string">
  top-level elements
</xcb>

  This is the root element of a protocol description.  The attributes are all
  various forms of the extension name.  header is the basename of the XML
  protocol description file, which will be used as the basename for generated
  bindings as well.  extension-name is the name of the extension in InterCaps,
  which will be used in the names of functions.  extension-xname is the name
  of the extension as passed to QueryExtension.

  As an example, the XML-XCB description for the GO-FASTER extension would use
  the root element <xcb header="gofaster" extension-name="GoFaster"
  extension-xname="GO-FASTER">; as a result, C bindings will be put in
  gofaster.h and gofaster.c, extension functions will be named
  XCBGoFasterFunctionName, and the extension initialization will call
  QueryExtension with the name "GO-FASTER".

  This element can contain any number of the elements listed in the section
  "Top-Level Elements" below.


Top-Level Elements
------------------

<import>header_name</import>

  The import element allows the protocol description to reference types
  declared in another extension.  The content is be the basename of the
  extension XML file, which is also the header attribute of the extension's
  root node.  Note that types from xproto are automatically available, without
  explicitly importing them.

<struct name="identifier">structure contents</struct>

  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.

<union name="identifier">structure contents</union>

  This element represents a union of data types, which can hold one value of
  any of those types.  The name attribute gives the name of the union.  The
  content represents the fields of the union, and consists of one or more of
  the field and pad elements described in the section "Structure Contents
  below".

<xidtype name="identifier" />

  This element represents an identifier for a particular type of resource.
  The name attribute gives the name of the new type.

<enum name="identifier">
  <item name="identifier">[optional expression]</item>
  ...
</enum>

  The enum element represents an enumeration type, which can take on any of
  the values given by the contained item elements.  The name attribute on the
  enum gives the name of the enumerated type.

  The item element represents one possible value of an enumerated type.  The
  name attribute on the item gives the name of that value, and the optional
  content is an expression giving the numeric value.  If the expression is
  omitted, the value will be one more than that of the previous item, or 0 for
  the first item.

<typedef oldname="identifier" newname="identifier" />

  The typedef element declares the type given by the newname attribute to be
  an alias for the type given by the oldname attribute.

<request name="identifier" opcode="integer" [combine-adjacent="true"]>
  structure contents
  [<reply>structure contents</reply>]
</request>

  The request element represents an X protocol request.  The name attribute
  gives the name of the request, and the opcode attribute gives the numeric
  request code.  The content of the request element represents the fields in
  the request, and consists of one or more of any of the elements listed in
  the "Structure Contents" section below.  Note that for requests in the core
  protocol, the first field in the request goes into the one-byte gap between
  the major opcode and the length; if the request does not have any data in
  that gap, put a one byte pad as the first element.  Extension requests
  always have this gap filled with the minor opcode.

  The optional reply element is present if the request has a reply.  The
  content of the reply element represents the fields in the reply, and
  consists of zero or more of the field, pad, and list elements listed in the
  "Structure Contents" section below.  Note that the first field in the reply
  always goes into the one-byte gap between the response type and the sequence
  number; if the reply does not have any data in that gap, put a one byte pad
  as the first element.

  If the optional combine-adjacent attribute is true, multiple adjacent
  requests of the same type may be combined into a single request without
  affecting the semantics of the requests.

<event name="identifier" number="integer"
       [[no-sequence-number="true"] | [xge="true"]]>
  structure contents
</event>

  This element represents an X protocol event.  The name attribute gives the
  name of the event, and the number attribute gives the event number.  The
  content of the event element represents the fields in the event, and
  consists of zero or more of the field, pad, and list elements listed in the
  "Structure Contents" section below.

  If the optional no-sequence-number attribute is true, the event does not
  include a sequence number.  This is a special-case for the KeymapNotify
  event in the core protocol, and should not be used in any other event.

  If the optional xge attribute is true, the event is an X Generic Event and
  will be treated as such.

  The no-sequence-number and xge attribute can not be combined.

<error name="identifier" number="integer">
  structure contents
</error>

  This element represents an X protocol error.  The name attribute gives the
  name of the error, and the number attribute gives the error number.  The
  content of the error element represents the fields in the error, and
  consists of zero or more of the field, pad, and list elements listed in the
  "Structure Contents" section below.

<eventcopy name="identifier" number="identifier" ref="identifier" />

  This element creates an alias for the event named in the ref attribute, with
  the new name given in the name attribute, and the new event number given in
  the number attribute.

<errorcopy name="identifier" number="identifier" ref="identifier" />

  This element creates an alias for the error named in the ref attribute, with
  the new name given in the name attribute, and the new error number given in
  the number attribute.


Structure Contents
------------------

Note: "type" attributes below refer to types defined by previous elements,
either in the current extension, xproto, or one of the imported extensions.
The type name must refer to only one possible type; if more than one type
matches, an error occurs.  To avoid this, the type may be explicitly prefixed
with a namespace, which should be the value of the header attribute on the
protocol description containing the desired type.  The namespace and type are
separated by a single colon.  For example, to refer to the PIXMAP type defined
in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
than type="PIXMAP".

Note: Most of the below may optionally contain an enum, altenum, mask or altmask
attribute, which follows the above rules for "type". "enum" is an exhaustive
enum; the value is restricted to one of the constants named in the enum.
"altenum" may be one of the values contained in the enum, but it need not be.
"mask" refers to an exhaustive enum to be used as a bitmask.
"altmask" may be a mask from the referred enum, but it need not be.

<pad bytes="integer" />

  This element declares some padding in a data structure.  The bytes
  attribute declares the number of bytes of padding.

<field type="identifier" name="identifier" />

  This element represents a field in a data structure.  The type attribute
  declares the data type of the field, and the name attribute gives the name
  of the field.

<fd name="identifier" />

  This element represents a file descriptor field passed with the request.  The
  name attribute gives the name of the field.

  While ordinary fields are encoded as part of the request, file descriptor
  fields are generally passed via an out-of-band mechanism.

<list type="identifier" name="identifier">expression</list>

  This element represents an array or list of fields in a data structure.  The
  type attribute declares the data type of the field, and the name attribute
  gives the name of the field.  The content is an expression giving the length
  of the list in terms of other fields in the structure.  See the section
  "Expressions" for details on the expression representation.

<localfield type="identifier" name="identifier" />

  This element represents a parameter in a request that is not sent over the
  wire.  The field can be referenced in the length expressions of lists or in
  an exprfield.  The type attribute declares the data type of the field, and
  the name attribute gives the name of the field.

<exprfield type="identifier" name="identifier">expression</exprfield>

  This element represents a field in a request that is calculated rather than
  supplied by the caller.  The type attribute declares the data type of the
  field, and the name attribute gives the name of the field.  The content is
  the expression giving the value of the field.  See the section "Expressions"
  for details on the expression representation.

<valueparam value-mask-type="identifier" value-mask-name="identifier"
            value-list-name="identifier" />

  This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
  defining the set of values included, and a list containing these values.
  value-mask-type gives the type of the bitmask; this must be CARD16 or
  CARD32.  value-mask-name gives the field name of the bitmask, and
  value-list-name gives the field name of the list of values. Please use
  <switch> instead for new protocol definitions.

<switch name="identifier"> switch expression
    <bitcase> bitcase expression(s), fields </bitcase>
    <case> case expression(s), fields </case>
</switch>

  This element represents conditional inclusion of fields. It can be viewed
  as sequence of multiple ifs:

  <bitcase>:
    if ( switch expression & bitcase expression ) is non-zero,
    bitcase fields are included in structure.

  <case>:
    if ( switch expression == case expression ) is true,
    then case fields are included in structure.

  It can be used only as the last field of a structure.

  When a bitcase or case includes multiple <enumref> clauses, the contents
  of the bitcase or case are only present once regardless of the number of
  bitcase or case expressions that match.

  <enumref> inside <bitcase> can only refer to an enum's <bit> members.
  <enumref> inside <case> can only refer to an enum's <value> members.

  A switch may contain multiple <bitcase> or <case> elements.
  Usually it will only contain <bitcase> elements
  or only contain <case> elements.
  That is, mixing of <case> and <bitcase> usually doesn't make any sense.

  The same value may appear in multiple <case> or <bitcase> elements.

  New protocol definitions should prefer to use this instead of <valueparam>
  and instead of <union>.


Expressions
-----------

  Expressions consist of a tree of <op> elements with leaves consisting of
  <fieldref> or <value> elements.

<op op="operator">expression expression</op>

  The op element represents an operator, with the op attribute specifying
  which operator.  The supported operations are +, -, *, /, &amp;, and
  &lt;&lt;, and their semantics are identical to the corresponding operators
  in C.  The two operand expressions may be other expression elements.

<fieldref>identifier</fieldref>

  The fieldref element represents a reference to the value of another field in
  the structure containing this expression.  The identifier is the value of
  the "name" attribute on the referenced field.

<value>integer</value>

  The value element represents a literal integer value in an expression.  The
  integer may be expressed in decimal or hexadecimal.

<bit>integer</bit>

  The bit element represents a literal bitmask value in an expression.
  The integer must be in the range 0..31, expanding to (1<<n) in C.

<enumref ref="identifier">enum item identifier</enumref>

  This element represents a reference to item of enum.

<unop op="operator">expression</unop>

  This element represents a unary operator, with the op attribute specifying
  which operator. The only supported operation so far is ~, and its semantic
  is identical to the corresponding operator in C.

<sumof ref="identifier" />

  This element represents a sumation of the elements of the referenced list.

<popcount>expression</popcount>

  This element represents the number of bits set in the expression.

Documentation
-------------

  Documentation for each request, reply or event is stored in the appropriate
  element using a <doc> element. The <doc> element can contain the following
  elements:

<brief>brief description</brief>

  A short description of the request, reply or event. For example "makes a
  window visible" for MapWindow. This will end up in the manpage NAME section
  and in the doxygen @brief description.

<description><![CDATA[longer description]]></description>

  The full description. Use `` to highlight words, such as "Draws
  `points_len`-1 lines between each pair of points…"

<example><![CDATA[example code]]</description>

  Example C code illustrating the usage of the particular request, reply or
  event.

<field name="name">field description</field>

  The full description for the specified field. Depending on the context, this
  is either a request parameter or a reply/event datastructure field.

<error type="type">error description</field>

  The full description for an error which can occur due to this request.

<see type="request" name="name" />

  A reference to another relevant program, function, request or event.