84 lines
3.1 KiB
Plaintext
84 lines
3.1 KiB
Plaintext
|
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.
|