specs: convert protocol geproto.txt to DocBook XML

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

1 files changed, 97 insertions, 0 deletions

diff --git a/specs/geproto.xml b/specs/geproto.xml
new file mode 100644
index 0000000..7bba357
--- /dev/null
+++ b/specs/geproto.xml
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<book>
+  <bookinfo>
+    <title>X Generic Event Extension</title>
+
+    <author>
+      <firstname>Peter</firstname>
+
+      <surname>Hutterer</surname>
+
+      <affiliation>
+        <orgname>peter.hutterer@who-t.net</orgname>
+      </affiliation>
+    </author>
+  </bookinfo>
+
+  <chapter>
+    <title>Introduction</title>
+
+    <para>X was designed to provide 64 event opcodes for all extensions. These
+    events are limited to 32 bytes.</para>
+
+    <para>The Generic Event Extension provides a template event for extensions
+    to re-use a single event opcode. GE only provide headers and the most
+    basic functionality, leaving the extensions to interpret the events in
+    their specific context.</para>
+
+    <para>GenericEvents may be longer than 32 bytes. If so, the number of 4
+    byte units following the initial 32 bytes must be specified in the length
+    field of the event.</para>
+  </chapter>
+
+  <chapter>
+    <title>Extension Initialization</title>
+
+    <para>The name of this extension is "Generic Event Extension"</para>
+
+    <programlisting>GEQueryVersion
+    client-major-version: CARD16
+    client-minor-version: CARD16
+==&gt;
+    major-version:        CARD16
+    minor-version:        CARD16</programlisting>
+
+    <para>The client sends the highest supported version to the server and the
+    server sends the highest version it supports, but no higher than the
+    requested version. Major versions changes can introduce incompatibilities
+    in existing functionality, minor version changes introduce only backward
+    compatible changes. It is the clients responsibility to ensure that the
+    server supports a version which is compatible with its
+    expectations.</para>
+
+    <para>As of version 1.0, no other requests are provided by this extension.
+    </para>
+  </chapter>
+
+  <chapter>
+    <title>Events</title>
+
+    <para>GE defines a single event, to be used by all extensions. The event's
+    structure is similar to a reply. This is a core protocol event, ID 35, and
+    is not itself an extension event.</para>
+
+    <programlisting>GenericEvent
+    type:           BYTE       always GenericEvent (35)
+    extension:      CARD8      extension offset
+    sequenceNumber: CARD16     low 16 bits of request seq. number
+    length:         CARD32     length
+    evtype:         CARD16     event type</programlisting>
+
+    <para>The field 'extension' is to be set to the major opcode of the
+    extension. The 'evtype' field is the actual opcode of the event. The
+    length field specifies the number of 4-byte blocks after the initial 32
+    bytes. If length is 0, the event is 32 bytes long.</para>
+  </chapter>
+
+  <chapter>
+    <title>Notes</title>
+
+    <para>Although the wire event is of arbitrary length, the actual size of
+    an XEvent is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an
+    extension converts a wire event to an XEvent &gt; 96 bytes, it will
+    overwrite the space allocated for the event. See struct _XSQEvent in
+    Xlibint.h for details.</para>
+
+    <para>Extensions need to malloc additional data and fill the XEvent
+    structure with pointers to the malloc'd data. The client then needs to
+    free the data, only the XEvent structure will be released by Xlib.</para>
+
+    <para>The server must not send GenericEvents longer than 32 bytes until it
+    has verified that the client is able to interpret these events. If a long
+    event is sent to a client unable to process GenericEvents, future
+    interpretation of replies and events by this client will fail.</para>
+  </chapter>
+</book>