aboutsummaryrefslogtreecommitdiff
path: root/X11/extensions/geproto.txt
diff options
context:
space:
mode:
Diffstat (limited to 'X11/extensions/geproto.txt')
-rw-r--r--X11/extensions/geproto.txt83
1 files changed, 83 insertions, 0 deletions
diff --git a/X11/extensions/geproto.txt b/X11/extensions/geproto.txt
new file mode 100644
index 000000000..654cd0f70
--- /dev/null
+++ b/X11/extensions/geproto.txt
@@ -0,0 +1,83 @@
+ X Generic Event Extension
+ Peter Hutterer
+ peter.hutterer@who-t.net
+
+
+1. Introduction
+2. Extension Initialization
+3. Extension 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. Extension Events
+
+GE defines a single event, to be used by all extensions. The event's structure
+is similar to a reply.
+
+┌───
+ GenericEvent
+ type: BYTE; always GenericEvent
+ 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.