From 35741d9dc745532dc4af37cc07e256392e3880da Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Tue, 3 Aug 2010 11:03:49 -0400 Subject: specs: convert protocol geproto.txt to DocBook XML Signed-off-by: Gaetan Nadon --- specs/Makefile.am | 3 +- specs/geproto.txt | 84 ----------------------------------------------- specs/geproto.xml | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 85 deletions(-) delete mode 100644 specs/geproto.txt create mode 100644 specs/geproto.xml diff --git a/specs/Makefile.am b/specs/Makefile.am index a1acb2e..3e631a1 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -27,6 +27,7 @@ doc_sources = \ dbe.xml \ dpms.xml \ evi.xml \ + geproto.xml \ multibuf.xml \ security.xml \ shape.xml \ @@ -35,7 +36,7 @@ doc_sources = \ tog-cup.xml \ xtest.xml -dist_doc_DATA = $(doc_sources) geproto.txt +dist_doc_DATA = $(doc_sources) if HAVE_XMLTO doc_DATA = $(doc_sources:.xml=.html) diff --git a/specs/geproto.txt b/specs/geproto.txt deleted file mode 100644 index 1054def..0000000 --- a/specs/geproto.txt +++ /dev/null @@ -1,84 +0,0 @@ - X Generic Event Extension - Peter Hutterer - peter.hutterer@who-t.net - - -1. Introduction -2. Extension Initialization -3. Events -4. Notes - -_____________________________________________________________________________ -1. Introduction - -X was designed to provide 64 event opcodes for all extensions. These events -are limited to 32 bytes. - -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. - -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. -_____________________________________________________________________________ -2. Extension Initialization - -The name of this extension is "Generic Event Extension" - -┌─── - GEQueryVersion - client-major-version: CARD16 - client-minor-version: CARD16 - ▶ - major-version: CARD16 - minor-version: CARD16 -└─── - - 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. - - - As of version 1.0, no other requests are provided by this extension. -_____________________________________________________________________________ -3. Events - -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. - -┌─── - 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 -└─── - - 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. -_____________________________________________________________________________ -4. Notes - -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 > 96 bytes, it will overwrite the space -allocated for the event. See struct _XSQEvent in Xlibint.h for details. - -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. - -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. 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 @@ + + + + + X Generic Event Extension + + + Peter + + Hutterer + + + peter.hutterer@who-t.net + + + + + + Introduction + + X was designed to provide 64 event opcodes for all extensions. These + events are limited to 32 bytes. + + 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. + + 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. + + + + Extension Initialization + + The name of this extension is "Generic Event Extension" + + GEQueryVersion + client-major-version: CARD16 + client-minor-version: CARD16 +==> + major-version: CARD16 + minor-version: CARD16 + + 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. + + As of version 1.0, no other requests are provided by this extension. + + + + + Events + + 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. + + 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 + + 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. + + + + Notes + + 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 > 96 bytes, it will + overwrite the space allocated for the event. See struct _XSQEvent in + Xlibint.h for details. + + 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. + + 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. + + -- cgit v1.2.3