summaryrefslogtreecommitdiff
path: root/Development/Documentation/XGE.mdwn
blob: 3927ce992a54080742430c48b5410965e8bcbfbd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# X Generic Event Extension

The X Generic Event extension (XGE) grew out of the problem that X only allows 64 event opcodes for all extensions together. Right now, there are only around 15 or so left, depending on how many extensions are enabled in your server. XGE simply defines one new event opcode (35, _GenericEvent_) in the core protocol, and then re-uses this opcode for multiple events.  


## Event Structure


[[!format txt """
typedef struct 
{
    BYTE    type; /* Always GenericEvent */
    CARD8   extension; 
    CARD16  sequenceNumber B16;
    CARD32  length B32;
    CARD16  evtype B16;
    CARD16  pad2 B16;
    CARD32  pad3 B32;
    CARD32  pad4 B32;
    CARD32  pad5 B32;
    CARD32  pad6 B32;
    CARD32  pad7 B32;
} xGenericEvent;

"""]]
The actual type of an event is specified as the combination of _extension_ and _evtype_. _extension_ specifies the matching extension's major opcode. _evtype_ is a static type as defined for this extension. _evtype_ must be unique within the extension. 


## Long events

XGE allows events that are longer than the standard X protocol's 32 byte events. The _length_ field of a _GenericEvent_ defines the number of bytes after the initial 32 bytes in 4 byte units. 

**Sending long events requires an XGE-aware libX11/libxcb!** The server must not send a long event unless it is sure that the client supports XGE, otherwise the protocol will be unaligned. libX11 without xcb support does **not** support _GenericEvents_. 


## Requests

XGE provides a single request: _GEQueryVersion_. 


[[!format txt """
/* QueryVersion */
typedef struct {
    CARD8       reqType;       /* input extension major code   */
    CARD8       ReqType;       /* always X_GEQueryVersion */
    CARD16      length B16;
    CARD16      majorVersion B16;
    CARD16      minorVersion B16;
} xGEQueryVersionReq;

#define sz_xGEQueryVersionReq    8

typedef struct {
    CARD8       repType;        /* X_Reply                      */
    CARD8       RepType;        /* always X_GEQueryVersion */
    CARD16      sequenceNumber B16;
    CARD32      length B32;
    CARD16      majorVersion B16;
    CARD16      minorVersion B16;
    CARD32      pad00 B32;
    CARD32      pad01 B32;
    CARD32      pad02 B32;
    CARD32      pad03 B32;
    CARD32      pad04 B32;
} xGEQueryVersionReply;

"""]]

## Usage

As the event selection is specific to the extension, it is (currently) required that each extension provides its own event selection request. For example, in XI this is _XiSelectEvent_. 

XGE is being used by XI ([[MPX]]) to send long events. Much of its current implementation supports device-specific events, but it is intended to be usable by other extensions as well.