geproto.txt

   1                         X Generic Event Extension
   2                               Peter Hutterer
   3                           peter.hutterer@who-t.net
   4
   5
   6 1. Introduction
   7 2. Extension Initialization
   8 3. Extension Events
   9 4. Notes
  10
  11 _____________________________________________________________________________
  12 1. Introduction
  13
  14 X was designed to provide 64 event opcodes for all extensions. These events
  15 are limited to 32 bytes.
  16
  17 The Generic Event Extension provides a template event for extensions to re-use
  18 a single event opcode. GE only provide headers and the most basic
  19 functionality, leaving the extensions to interpret the events in their
  20 specific context.
  21
  22 GenericEvents may be longer than 32 bytes. If so, the number of 4 byte units
  23 following the initial 32 bytes must be specified in the length field of the
  24 event.
  25 _____________________________________________________________________________
  26 2. Extension Initialization
  27
  28 The name of this extension is "Generic Event Extension"
  29
  30 ┌───
  31     GEQueryVersion
  32         client-major-version:   CARD16
  33         client-minor-version:   CARD16
  34       ▶
  35         major-version:          CARD16
  36         minor-version:          CARD16
  37 └───
  38
  39         The client sends the highest supported version to the server
  40         and the server sends the highest version it supports, but no
  41         higher than the requested version. Major versions changes can
  42         introduce incompatibilities in existing functionality, minor
  43         version changes introduce only backward compatible changes.
  44         It is the clients responsibility to ensure that the server
  45         supports a version which is compatible with its expectations.
  46
  47
  48         As of version 1.0, no other requests are provided by this extension.
  49 _____________________________________________________________________________
  50 3. Extension Events
  51
  52 GE defines a single event, to be used by all extensions. The event's structure
  53 is similar to a reply.
  54
  55 ┌───
  56     GenericEvent
  57         type: BYTE;                     always GenericEvent
  58         extension: CARD8;               extension offset
  59         sequenceNumber: CARD16          low 16 bits of request seq. number
  60         length: CARD32                  length
  61         evtype: CARD16                  event type
  62 └───
  63
  64         The field 'extension' is to be set to the major opcode of the
  65         extension. The 'evtype' field is the actual opcode of the event.
  66         The length field specifies the number of 4-byte blocks after the
  67         initial 32 bytes. If length is 0, the event is 32 bytes long.
  68 _____________________________________________________________________________
  69 4. Notes
  70
  71 Although the wire event is of arbitrary length, the actual size of an XEvent
  72 is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an extension
  73 converts a wire event to an XEvent > 96 bytes, it will overwrite the space
  74 allocated for the event. See struct _XSQEvent in Xlibint.h for details.
  75
  76 Extensions need to malloc additional data and fill the XEvent structure with
  77 pointers to the malloc'd data. The client then needs to free the data, only
  78 the XEvent structure will be released by Xlib.
  79
  80 The server must not send GenericEvents longer than 32 bytes until it has
  81 verified that the client is able to interpret these events. If a long event is
  82 sent to a client unable to process GenericEvents, future interpretation of
  83 replies and events by this client will fail.