Add XGE header files and protocol description.

5 files changed, 306 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
index 782b7d4..2fa1920 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -3,6 +3,9 @@ xext_HEADERS = \
 	dpms.h \
 	dpmsstr.h \
 	extutil.h \
+        ge.h \
+        geproto.h \
+        Xge.h \
 	lbxbuf.h \
 	lbxbufstr.h \
 	lbxdeltastr.h \
diff --git a/Xge.h b/Xge.h
new file mode 100644
index 0000000..8b9fb3c
--- /dev/null
+++ b/Xge.h
@@ -0,0 +1,50 @@
+/*
+ * Copyright © 2007 Peter Hutterer
+ *
+ * Permission to use, copy, modify, distribute, and sell this software and its
+ * documentation for any purpose is hereby granted without fee, provided that
+ * the above copyright notice appear in all copies and that both that
+ * copyright notice and this permission notice appear in supporting
+ * documentation, and that the name of the author not be used in
+ * advertising or publicity pertaining to distribution of the software without
+ * specific, written prior permission.  The author makes no
+ * representations about the suitability of this software for any purpose.  It
+ * is provided "as is" without express or implied warranty.
+ *
+ * THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+ * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+ * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+ * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+ * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+ * PERFORMANCE OF THIS SOFTWARE.
+ */
+
+
+/* XGE Client interfaces */
+
+#ifndef _XGE_H_
+#define _XGE_H_
+
+#include <X11/Xlib.h>
+#include <X11/Xfuncproto.h>
+
+_XFUNCPROTOBEGIN
+
+/**
+ * Generic Event mask. 
+ * To be used whenever a list of masks per extension has to be provided.
+ */
+typedef struct {
+    CARD8       extension;
+    CARD8       pad0;
+    CARD16      pad1;
+    CARD32      evmask;
+} XGenericEventMask;
+
+Bool XGEQueryExtension(Display* dpy, int *event_basep, int *err_basep);
+Bool XGEQueryVersion(Display* dpy, int *major, int* minor);
+
+_XFUNCPROTOEND
+
+#endif /* _XGE_H_ */
diff --git a/ge.h b/ge.h
new file mode 100644
index 0000000..38652a0
--- /dev/null
+++ b/ge.h
@@ -0,0 +1,64 @@
+/* 
+
+Copyright 2007 Peter Hutterer <peter@cs.unisa.edu.au>
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of the author shall
+not be used in advertising or otherwise to promote the sale, use or
+other dealings in this Software without prior written authorization
+from the author.
+
+*/
+
+#ifndef _GE_H_
+#define _GE_H_
+
+#define GE_NAME         "Generic Event Extension"
+#define GE_MAJOR        1
+#define GE_MINOR        0
+
+/*********************************************************
+ *
+ * Requests
+ *
+ */
+
+#define X_GEQueryVersion        0
+
+#define GENumberRequests       (X_GEQueryVersion + 1)
+
+/*********************************************************
+ *
+ * Events
+ *
+ */
+
+#define X_GenericEvent        0
+
+#define GENumberEvents        (X_GenericEvent + 1)
+
+/*********************************************************
+ *
+ * Errors
+ *
+ */
+
+#define GENumberErrors        0
+
+#endif /* _GE_H_ */
diff --git a/geproto.h b/geproto.h
new file mode 100644
index 0000000..d9d79a1
--- /dev/null
+++ b/geproto.h
@@ -0,0 +1,87 @@
+/* 
+
+Copyright 2007 Peter Hutterer <peter@cs.unisa.edu.au>
+
+Permission to use, copy, modify, distribute, and sell this software and its
+documentation for any purpose is hereby granted without fee, provided that
+the above copyright notice appear in all copies and that both that
+copyright notice and this permission notice appear in supporting
+documentation.
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of the author shall
+not be used in advertising or otherwise to promote the sale, use or
+other dealings in this Software without prior written authorization
+from the author.
+
+*/
+
+#ifndef _GEPROTO_H_
+#define _GEPROTO_H_
+
+#include<X11/Xproto.h>
+#include<X11/X.h>
+#include<X11/extensions/ge.h>
+
+
+/*********************************************************
+ *
+ * Protocol request constants
+ *
+ */
+
+#define X_GEGetExtensionVersion 1
+
+/*********************************************************
+ *
+ * XGE protocol requests/replies 
+ *
+ */
+
+/* generic request */
+typedef struct {
+    CARD8   reqType;
+    CARD8   ReqType;
+    CARD16  length B16;
+} xGEReq;
+
+
+/* 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;
+
+#define sz_xGEQueryVersionReply    32
+
+#endif /* _GEPROTO_H_ */
+
diff --git a/geproto.txt b/geproto.txt
new file mode 100644
index 0000000..e30a68d
--- /dev/null
+++ b/geproto.txt
@@ -0,0 +1,102 @@
+                        X Generic Event Extension
+                              Peter Hutterer
+                          peter@cs.unisa.edu.au
+
+
+1. Introduction
+2. Requests
+3. Events
+4. Usage from other extensions - server side
+5. Usage from other extensions - client side
+6. Notes
+
+_____________________________________________________________________________
+1. Introduction
+
+X was designed to provide 64 event opcodes for all extensions. With the
+increasing number of extensions, event opcodes are running out and future
+extensions will not be able to send events to the client.
+
+The Generic Event Extension is a template for future extensions to re-use a
+single opcode. GE does not actually do much but provide headers and a few API
+calls. The majority of the work is still to be done in the extensions.
+
+Standard X events are limited to 32 bytes. GenericEvents have the same size
+restrictions as requests, with a minimum of 32 bytes, followed by an arbitrary
+amount of data specified in the length field (see Section 3.)
+
+_____________________________________________________________________________
+2. Requests
+
+GEQueryVersion:
+        CARD8   reqType
+        CARD8   ReqType         X_GEQueryVersion
+        CARD16  length
+        CARD32  majorVersion
+        CARD32  minorVersion
+
+GEQueryVersion reply:
+        CARD8   repType
+        CARD8   RepType         X_GEQueryVersion
+        CARD16  sequenceNumber
+        CARD32  length
+        CARD16  major_version
+        CARD16  minor_version
+_____________________________________________________________________________
+3. Events
+
+GE defines a single event, to be used by all extensions. The event's structure 
+is similar to a request.
+
+GenericEvent
+    BYTE    type
+    CARD8   extension
+    CARD16  sequenceNumber
+    CARD32  length;
+    CARD16  evtype;
+    CARD16  pad1;
+    CARD32  pad2;
+    CARD32  pad3;
+    CARD32  pad4;
+    CARD32  pad5;
+    CARD32  pad6;
+
+The field 'extension' is to be set to the major opcode of the extension.
+The 'evtype' field is the actual opcode of the event. 
+This event is to be type-cast by an extension to it's real format.
+The length field specifies the number of 4-byte blocks after the initial 32
+bytes.
+
+_____________________________________________________________________________
+4. Usage from other extensions - server side
+
+GERegisterExtension(major_opcode, swap)
+    An extension needs to register at the GE. This should be done after
+    calling AddExtension(). 
+    major_opcode is the major opcode for all extension requests.
+    The swap function will be called when an event has to be converted for a
+    client with different byte ordering.
+
+_____________________________________________________________________________
+5. Usage from other extensions - client side
+
+None. The event conversion rules of the extension however should be able to
+handle events of type GenericEvent as well.
+
+Internally, when an extension is initialized, it needs to call XExtAddDisplay
+and provide a set of hooks that are to be called for events conversion and
+other stuff. XGE hooks into XExtAddDisplay and stores the hooks provided by
+the extension. Should a GenericEvent come along, XGE receives it but relays
+the call to the real extension to handle it. 
+
+_____________________________________________________________________________
+6. 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
+acllocated 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.