specs: move geproto.txt in the specs directory

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

2 files changed, 85 insertions, 1 deletions

diff --git a/specs/Makefile.am b/specs/Makefile.am
index 9d94e85..c717d04 100644
--- a/specs/Makefile.am
+++ b/specs/Makefile.am
@@ -23,7 +23,7 @@
 
 if ENABLE_SPECS
 doc_sources = dbe.xml security.xml sync.xml
-dist_doc_DATA = $(doc_sources)
+dist_doc_DATA = $(doc_sources) geproto.txt
 
 if HAVE_XMLTO
 doc_DATA = $(doc_sources:.xml=.html)
diff --git a/specs/geproto.txt b/specs/geproto.txt
new file mode 100644
index 0000000..1054def
--- /dev/null
+++ b/specs/geproto.txt
@@ -0,0 +1,84 @@
+                        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.