Xlib Programming Manual (O'Reilly & Associates, Inc.)

www.sbin.org

Xlib Programming Manual (O'Reilly & Associates, Inc.)

Writing Extensions to X

Extensibility is an important part of X. Hooks are provided into Xlib and the protocol so that extensions will have the same performance as the core routines. This appendix provides reference information on how to write extensions and integrate them into Xlib. This appendix is not a tutorial, and you will need to look at existing extensions to figure out how to write one yourself.

Extensions can be added to Xlib only with no protocol addition or to both Xlib and the server with a protocol addition. Several extensions are already available that support nonrectangular windows, 3-D graphics, and alternate input devices and multibuffering. See the code for these for examples of writing extensions.

Because X can only evolve by extension to the core protocol, it is important that extensions not be perceivable as second-class citizens. At some point, some extensions may be adopted as parts of the "X Standard."

Therefore, there should be little to distinguish the use of an extension from that of the core protocol. To avoid having to initialize extensions explicitly in application programs, extensions should perform "lazy evaluations" and automatically initialize themselves when called for the first time.

Extensions written according to these instructions will run at essentially the same performance as the core protocol requests.

It is expected that a given extension to X will consist of multiple requests. Defining ten new features as ten separate extensions is a bad practice. Rather, they should be packaged into a single extension and should use minor opcodes to distinguish the requests.

The symbols and macros used for writing stubs to Xlib are listed in <Xlibint.h>.

Basic Protocol Support Routines

The basic protocol requests for extensions are XQueryExtension() and XListExtensions().

Bool XQueryExtension(display, name, major_opcode_return, \
first_event_return, first_error_return)
      Display *display;
      char *name;
      int *major_opcode_return;
      int *first_event_return;
      int *first_error_return;

display: Specifies the connection to the X server.
name: Specifies the extension name.
major_opcode_return: Returns the major opcode.
first_event_return: Returns the first event code, if any.; Specifies the extension list.

XQueryExtension()determines if the named extension is present. If the extension is not present, False is returned; otherwise True is returned. If the extension is present, the major opcode for the extension is returned to major_opcode_return; otherwise, zero is returned. Any minor opcode and the request formats are specific to the extension. If the extension involves additional event types, the base event type code is returned to first_event_return; otherwise, zero is returned. The format of the events is specific to the extension. If the extension involves additional error codes, the base error code is returned to first_error_return; otherwise, zero is returned. The format of additional data in the errors is specific to the extension.

If the extension name is not in the Host Portable Character Encoding the result is implementation dependent. Case matters; the strings thing, Thing, and thinG are all considered different names.

XListExtensions

char **XListExtensions(display, nextensions_return)
      Display *display;
      int *nextensions_return;

display: Specifies the connection to the X server.
nextensions_return: Returns the number of extensions listed.

XListExtensions()returns a list of all extensions supported by the server. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent.

XFreeExtensionList

XFreeExtensionList(list)
      char **list;

list: Specifies the list of extension names.

XFreeExtensionList()frees the memory allocated by XListExtensions().

Hooking into Xlib

These functions allow you to hook into the library. They are not normally used by application programmers but are used by people who need to extend the core X protocol and the X library interface. The functions, which generate protocol requests for X, are typically called stubs.

In extensions, stubs first should check to see if they have initialized themselves on a connection. If they have not, they then should call XInitExtension() to attempt to initialize themselves on the connection.

If the extension needs to be informed of GC/font allocation or deallocation or if the extension defines new event types, the functions described here allow the extension to be called when these events occur.

XInitExtension

The XExtCodes structure returns the information from XInitExtension() and is defined in <Xlib.h>:

typedef struct _XExtCodes {  /* public to extension, cannot be changed */
    int extension;           /* extension number */
    int major_opcode;        /* major op-code assigned by server */
    int first_event;         /* first event number for the extension */
    int first_error;         /* first error number for the extension */
} XExtCodes;

XExtCodes *XInitExtension(display, name)
      Display *display;
      char *name;

display: Specifies the connection to the X server.
name: Specifies the extension name.

XInitExtension()determines if the named extension exists. Then it allocates storage for maintaining the information about the extension on the connection, chains this onto the extension list for the connection, and returns the information the stub implementor will need to access the extension. If the extension does not exist, XInitExtension() returns NULL.

The extension number in the XExtCodes structure is needed in the other calls that follow. This extension number is unique only to a single connection.

XAddExtension

XExtCodes *XAddExtension(display)
        Display *display;

display: Specifies the connection to the X server.

For local Xlib extensions, XAddExtension() allocates the XExtCodes structure, bumps the extension number count, and chains the extension onto the extension list. (This permits extensions to Xlib without requiring server extensions.)

Hooks into the Library

These functions allow you to define procedures that are to be called when various circumstances occur. The procedures include the creation of a new GC for a connection, the copying of a GC, the freeing of a GC, the creating and freeing of fonts, the conversion of events defined by extensions to and from wire format, and the handling of errors.

All of these functions return the previous routine defined for this extension.

XESetCloseDisplay

int (*XESetCloseDisplay(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when the display is closed.

You use this procedure to define a procedure to be called whenever XCloseDisplay() is called. This procedure returns any previously defined procedure, usually NULL.

When XCloseDisplay() is called, your routine is called with these arguments:

(*proc)(display, codes)
    Display *display;
    XExtCodes *codes;

XESetCreateGC

int (*XESetCreateGC(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when a GC is closed.

You use this procedure to define a procedure to be called whenever a new GC is created. This procedure returns any previously defined procedure, usually NULL.

When a GC is created, your routine is called with these arguments:

(*proc)(display, gc, codes)
    Display *display;
    GC gc;
    XExtCodes *codes;

XESetCopyGC

int (*XESetCopyGC(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when GC components are copied.

You use this procedure to define a procedure to be called whenever a GC is copied. This procedure returns any previously defined procedure, usually NULL.

When a GC is copied, your routine is called with these arguments:

(*proc)(display, gc, codes)
    Display *display;
    GC gc;
    XExtCodes *codes;

XESetFreeGC

int (*XESetFreeGC(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when a GC is freed.

You use this procedure to define a procedure to be called whenever a GC is freed. This procedure returns any previously defined procedure, usually NULL.

When a GC is freed, your routine is called with these arguments:

(*proc)(display, gc, codes)
    Display *display;
    GC gc;
    XExtCodes *codes;

XESetCreateFont

int (*XESetCreateFont(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when a font is created.

You use this procedure to define a procedure to be called whenever XLoadQueryFont() and XQueryFont() are called. This procedure returns any previously defined procedure, usually NULL.

When XLoadQueryFont() or XQueryFont() is called, your routine is called with these arguments:

(*proc)(display, fs, codes)
    Display *display;
    XFontStruct *fs;
    XExtCodes *codes;

XESetFreeFont

int (*XESetFreeFont(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when a font is freed.

You use this procedure to define a procedure to be called whenever XFreeFont() is called. This procedure returns any previously defined procedure, usually NULL.

When XFreeFont() is called, your routine is called with these arguments:

(*proc)(display, fs, codes)
    Display *display;
    XFontStruct *fs;
    XExtCodes *codes;

Defining New Events and Errors

The next three functions allow you to define new events to the library. An XEvent structure always has a type code (type int) as the first component. This uniquely identifies what kind of event it is. The second component is always the serial number (type unsignedlong) of the last request processed by the server. The third component is always a boolean (type BoolP) indicating whether the event came from a SendEvent protocol request. The fourth component is always a pointer to the display the event was read from. The fifth component is always a resource ID of one kind or another, usually a window, carefully selected to be useful to toolkit dispatchers. The fifth component should always exist, even if the event does not have a natural "destination"; if there is no value from the protocol to put in this component, initialize it to zero.

There is an implementation limit such that your host event structure size cannot be bigger than the size of the XEvent union of structures. There also is no way to guarantee that more than 24 elements or 96 characters in the structure will be fully portable between machines.

XESetWireToEvent

int (*XESetWireToEvent()(display, event_number, proc))()
      Display *display;
      int event_number;
      Status (*proc)();

display: Specifies the connection to the X server.
event_number: Specifies the event code.
proc: Specifies the routine to call when converting an event.

You use this procedure to define a procedure to be called when an event needs to be converted from wire format (xEvent) to host format (XEvent). The event number defines which protocol event number to install a conversion routine for. This procedure returns any previously defined procedure.

You can replace a core event conversion routine with one of your own, although this is not encouraged. It would, however, allow you to intercept a core event and modify it before being placed in the queue or otherwise examined.

When Xlib needs to convert an event from wire format to host format, your routine is called with these arguments:

Status (*proc)(display, re, event)
    Display *display;
    XEvent *re;
    xEvent *event;

Your routine must return status to indicate if the conversion succeeded. The re argument is a pointer to where the host format event should be stored, and the event argument is the 32-byte wire event structure. In the XEvent structure you are creating, you must fill in the five required members of the event structure. You should fill in the type member with the type specified for the xEvent structure. You should copy all other members from the xEvent structure (wire format) to the XEvent structure (host format). Your conversion routine should return True if the event should be placed in the queue or False if it should not be placed in the queue.

_XSetLastRequestRead

To initialize the serial number component of the event, call _XSetLastRequestRead() with the event and use the return value.

unsigned long _XSetLastRequestRead(display, rep)
      Display *display;
      xGenericReply *rep;

display: Specifies the connection to the X server.
rep: Specifies the wire event structure.

This function computes and returns a complete serial number from the partial serial number in the event.

XESetEventToWire

Status (*XESetEventToWire()(display, event_number, proc))()
      Display *display;
      int event_number;
      int (*proc)();

display: Specifies the connection to the X server.
event_number: Specifies the event code.
proc: Specifies the routine to call when converting an event.

You use this procedure to define a procedure to be called when an event needs to be converted from host format (XEvent) to wire format (xEvent) form. The event number defines which protocol event number to install a conversion routine for. This procedure returns any previously defined procedure. It returns zero if the conversion fails or nonzero otherwise.

When Xlib needs to convert an event from host format to wire format, your routine is called with these arguments:

(*proc)(display, re, event)
    Display *display;
    XEvent *re;
    xEvent *event;

The re argument is a pointer to the host format event, and the event argument is a pointer to where the 32-byte wire event structure should be stored. You should fill in the type with the type from the XEvent structure. All other members then should be copied from the host format to the xEvent structure.

XESetWireToError

Bool (*XESetWireToError()(display, error_number, proc)()
      Display *display;
      int error_number;
      Bool (*proc)();

display: Specifies the connection to the X server.
error_number: Specifies the error code.
proc: Specifies the routine to call when an error is received.

This function defines a procedure to be called when an extension error needs to be converted from wire format to host format. The error number defines which protocol error code to install the conversion routine for. This procedure returns any previously defined procedure.

Use this function for extension errors that contain additional error values beyond those in a core X error, when multiple wire errors must be combined into a single Xlib error, or when it is necessary to intercept an X error before it is otherwise examined.

When Xlib needs to convert an error from wire format to host format, the routine is called with these arguments:

Bool (*proc)(display, he, we)
    Display *display;
    XErrorEvent *he;
    xError *we;

The he argument is a pointer to where the host format error should be stored. The structure pointed at by he is guaranteed to be as large as an XEvent structure, and so can be cast to a type larger than an XErrorEvent(), in order to store additional values. If the error is to be completely ignored by Xlib (for example, several protocol error structures will be combined into one Xlib error), then the function should return False; otherwise it should return True.

XESetError

int (*XESetError()(display, extension, proc))()
      Display *display;
      int extension;
      int (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when an error is received.

Inside Xlib, there are times that you may want to suppress the calling of the external error handling when an error occurs. This allows status to be returned on a call at the cost of the call being synchronous (though most such routines are query operations, in any case, and are typically programmed to be synchronous).

When Xlib detects a protocol error in _XReply(), it calls your procedure with these arguments:

int (*proc)(display, err, codes, ret_code)
    Display *display;
    xError *err;
    XExtCodes *codes;
    int *ret_code;

The err argument is a pointer to the 32-byte wire format error. The codes argument is a pointer to the extension codes structure. The ret_code argument is the return code you may want _XReply returned to.

If your routine returns a zero value, the error is not suppressed, and the client's error handler is called. (For further information, see Section 11.8.2.) If your routine returns nonzero, the error is suppressed, and _XReply returns the value of ret_code.

XESetErrorString

char  *(*XESetErrorString()(display, extension, proc))()
      Display *display;
      int extension;
      char *(*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call to obtain an error string.

The XGetErrorText() function returns a string to the user for an error. XESetErrorString() allows you to define a routine to be called that should return a pointer to the error message. The following is an example.

(*proc)(display, code, codes, buffer, nbytes)
    Display *display;
    int code;
    XExtCodes *codes;
    char *buffer;
    int nbytes;

Your procedure is called with the error code for every error detected. You should copy nbytes of a null-terminated string containing the error message into buffer.

XESetPrintErrorValues

void (*XESetPrintErrorValues()(display, extension, proc))()
      Display *display;
      int extension;
      void (*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when an error is printed.

This function defines a procedure to be called when an extension error is printed, to print the error values. Use this function for extension errors that contain additional error values beyond those in a core X error. This function returns any previously defined procedure.

When Xlib needs to print an error, the routine is called with these arguments:

void (*proc)(display, ev, fp)
    Display *display;
    XErrorEvent *ev;
    void *fp;

The structure pointed at by ev is guaranteed to be as large as an XEvent structure, and so can be cast to a type larger than an XErrorEvent(), in order to obtain additional values set by using XESetWireToError(). The underlying type of the fp argument is system dependent; on a POSIX-compliant fp should be cast to type FILE*.

XESetFlushGC

int (*XESetFlushGC()(display, extension, proc))()
      Display *display;
      int extension;
      int *(*proc)();

display: Specifies the connection to the X server.
extension: Specifies the extension number.
proc: Specifies the routine to call when a GC is flushed.

The XESetFlushGC() procedure is identical to XESetCopyGC() except that XESetFlushGC is called when a GC cache needs to be updated in the server.

Hooks onto Xlib Data Structures

Various Xlib data structures have provisions for extension routines to chain extension supplied data onto a list. These structures are GC, Visual, Screen, ScreenFormat, Display, and XFontStruct. Because the list pointer is always the first member in the structure, a single set of routines can be used to manipulate the data on these lists.

The following structure is used in the routines in this section and is defined in <Xlib.h>:

typedef struct _XExtData {
    int number;              /* number returned by XInitExtension() */
    struct _XExtData *next;  /* next item on list of data for structure */
    int (*free_private)();   /* if defined,  called to free private */
    XPointer private_data;   /* data private to this extension. */
} XExtData;

When any of the data structures listed above are freed, the list is walked, and the structure's free routine (if any) is called. If free is NULL, then the library frees both the data pointed to by the private_data member and the structure itself.

union {    Display *display;
    GC gc;
    Visual *visual;
    Screen *screen;
    ScreenFormat *pixmap_format;
    XFontStruct *font } XEDataObject;

XEHeadOfExtensionList

XExtData **XEHeadOfExtensionList(object)
   XEDataObject object;

object: Specifies the object.

XEHeadOfExtensionList()returns a pointer to the list of extension structures attached to the specified object. In concert with

XAddToExtensionList

XAddToExtensionList(), XEHeadOfExtensionList() allows an extension to attach arbitrary data to any of the structures of types contained in XEDataObject().

XAddToExtensionList(structure, ext_data)
      XExtData **structure;
      XExtData *ext_data;

structure: Specifies the extension list.
ext_data: Specifies the extension data structure to add.

The structure argument is a pointer to one of the data structures enumerated above. You must initialize ext_data->number with the extension number before calling this routine.

XFindOnExtensionList

XExtData *XFindOnExtensionList()(structure, number)
      struct _XExtData **structure;
      int number;

structure: Specifies the extension list.
number: Specifies the extension number from XInitExtension().

XFindOnExtensionList()returns the first extension data structure for the extension numbered number. It is expected that an extension will add at most one extension data structure to any single data structure's extension data list. There is no way to find additional structures.

XAllocID

The XAllocID() macro, which allocates and returns a resource ID, is defined in <Xlib.h>.

XAllocID(display)
     Display *display;

display: Specifies the connection to the X server.

This macro is a call through the Display structure to the internal resource ID allocator. It returns a resource ID that you can use when creating new resources.

GC Caching

GCs are cached by the library to allow merging of independent change requests to the same GC into single protocol requests. This is typically called a write-back cache. Any extension routine whose behavior depends on the contents of a GC must flush the GC cache to make sure the server has up-to-date contents in its GC.

The FlushGC() macro checks the dirty bits in the library's GC structure and calls _XFlushGCCache if any elements have changed. The FlushGC() macro is defined as follows:

FlushGC(display, gc)
      Display *display;
      GC gc;

display: Specifies the connection to the X server.
gc: Specifies the GC.

Note that if you extend the GC to add additional resource ID components, you should ensure that the library stub sends the change request immediately. This is because a client can free a resource immediately after using it, so if you only stored the value in the cache without forcing a protocol request, the resource might be destroyed before being set into the GC. You can use the _XFlushGCCache procedure to force the cache to be flushed. The _XFlushGCCache procedure is defined as follows:

_XFlushGC()Cache(display, gc)
      Display *display;
      GC gc;

display: Specifies the connection to the X server.
gc: Specifies the GC.

Graphics Batching

If you extend X to add more poly graphics primitives, you may be able to take advantage of facilities in the library to allow back-to-back single calls to be transformed into poly requests. This may dramatically improve performance of programs that are not written using poly requests. A pointer to an xReq(), called last_req in the display structure, is the last request being processed. By checking that the last request type, drawable, gc, and other options are the same as the new one and that there is enough space left in the buffer, you may be able to just extend the previous graphics request by extending the length field of the request and appending the data to the buffer. This can improve performance by five times or more in naive programs. For example, here is the source for the XDrawPoint() stub. (Writing extension stubs is discussed in the next section.)

#include "copyright.h"
#include "Xlibint.h"
/* precompute the maximum size of batching request allowed */
static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
XDrawPoint()(dpy, d, gc, x, y)
    register Display *dpy;
    Drawable d;
    GC gc;
    int x, y; /* INT16 */
{
    xPoint *point;
    LockDisplay()(dpy);
    FlushGC()(dpy, gc);
    {
    register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
    /* if same as previous request, with same drawable, batch requests */
    if (
          (req->reqType == X_PolyPoint)
       && (req->drawable == d)
       && (req->gc == gc->gid)
       && (req->coordMode == CoordModeOrigin)
       && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
       && (((char *)dpy->bufptr - (char *)req) < size) ) {
         point = (xPoint *) dpy->bufptr;
         req->length += sizeof (xPoint) >> 2;
         dpy->bufptr += sizeof (xPoint);
         }
    else {
        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
        req->drawable = d;
        req->gc = gc->gid;
        req->coordMode = CoordModeOrigin;
        point = (xPoint *) (req + 1);
        }
    point->x = x;
    point->y = y;
    }
    UnlockDisplay()(dpy);
    SyncHandle();
}

To keep clients from generating very long requests that may monopolize the server, there is a symbol defined in <Xlibint.h> of EPERBATCH on the number of requests batched. Most of the performance benefit occurs in the first few merged requests. Note that FlushGC() is called before picking up the value of last_req, because it may modify this field.

Writing Extension Stubs

All X requests always contain the length of the request, expressed as a 16-bit quantity of 32 bits. This means that a single request can be no more than 256K bytes in length. Some servers may not support single requests of such a length. The value of dpy->max_request_size contains the maximum length as defined by the server implementation. For further information, see "X Window System Protocol."

Requests, Replies, and Xproto.h

The <Xproto.h> file contains three sets of definitions that are of interest to the stub implementor: request names, request structures, and reply structures.

You need to generate a file equivalent to <Xproto.h> for your extension and need to include it in your stub routine. Each stub routine also must include <Xlibint.h>.

The identifiers are deliberately chosen in such a way that, if the request is called X_DoSomething, then its request structure is xDoSomethingReq, and its reply is xDoSomethingReply. The GetReq family of macros, defined in <Xlibint.h>, takes advantage of this naming scheme.

For each X request, there is a definition in <Xproto.h> that looks similar to this:

#define X_DoSomething   42

In your extension header file this will be a minor opcode, rather than a major opcode.

Request Format

Every request contains an 8-bit major opcode and a 16-bit length field expressed in units of four bytes. Every request consists of four bytes of header (containing the major opcode, the length field, and a data byte) followed by zero or more additional bytes of data. The length field defines the total length of the request, including the header. The length field in a request must equal the minimum length required to contain the request. If the specified length is smaller or larger than the required length, the server should generate a BadLength error. Unused bytes in a request are not required to be zero. Extensions should be designed in such a way that long protocol requests can be split up into smaller requests, if it is possible to exceed the maximum request size of the server. The protocol guarantees the maximum request size to be no smaller than 4096 units (16384 bytes).

Major opcodes 128 through 255 are reserved for extensions. Extensions are intended to contain multiple requests, so extension requests typically have an additional minor opcode encoded in the "spare" data byte in the request header, but the placement and interpretation of this minor opcode as well as all other fields in extension requests are not defined by the core protocol. Every request is implicitly assigned a sequence number (starting with one) used in replies, errors, and events.

To help but not cure portability problems to certain machines, the B16 and B32 macros have been defined so that they can become bitfield specifications on some machines. For example, on a Cray, these should be used for all 16-bit and 32-bit quantities, as discussed below.

Most protocol requests have a corresponding structure typedef in <Xproto.h>, which looks like:

typedef struct _DoSomethingReq {
    CARD8 reqType;        /* X_DoSomething */
    CARD8 someDatum;      /* used differently in different requests */
    CARD16 length B16;    /* total # of bytes in request, divided by 4 */
    ...
    /* request-specific data */
    ...
} xDoSomethingReq;

If a core protocol request has a single 32-bit argument, you need not declare a request structure in your extension header file. Instead, such requests use <Xproto.h>'s xResourceReq structure. This structure is used for any request whose single argument is a Window, Pixmap, Drawable, GContext, Font, Cursor, Colormap, Atom, or VisualID.

typedef struct _ResourceReq {
    CARD8 reqType;     /* the request type, e.g., X_DoSomething */
    BYTE pad;          /* not used */
    CARD16 length B16; /* 2 (= total # of bytes in request, divided by 4) */
    CARD32 id B32;     /* the Window, Drawable, Font, GContext, etc. */
} xResourceReq;

If convenient, you can do something similar in your extension header file.

In both of these structures, the reqType field identifies the type of the request (for example, X_MapWindow or X_CreatePixmap). The length field tells how long the request is in units of 4-byte longwords. This length includes both the request structure itself and any variable length data, such as strings or lists, that follow the request structure. Request structures come in different sizes, but all requests are padded to be multiples of four bytes long.

A few protocol requests take no arguments at all. Instead, they use <Xproto.h>'s xReq structure, which contains only a reqType and a length (and a pad byte).

If the protocol request requires a reply, then <Xproto.h> also contains a reply structure typedef:

typedef struct _DoSomethingReply {
    BYTE type;                 /* always X_Reply */
    BYTE someDatum;            /* used differently in different requests */
    CARD16 sequenceNumber B16; /* # of requests sent so far */
    CARD32 length B32;         /* # of additional bytes, divided by 4 */
    ...
    /* request-specific data */
    ...
} xDoSomethingReply;

Most of these reply structures are 32 bytes long. If there are not that many reply values, then they contain a sufficient number of pad fields to bring them up to 32 bytes. The length field is the total number of bytes in the request minus 32, divided by 4. This length will be nonzero only if:

The reply structure is followed by variable length data such as a list or string.
The reply structure is longer than 32 bytes.

Only XGetWindowAttributes(), XQueryFont(), XQueryKeymap(), and XGetKeyboardControl have reply structures longer than 32 bytes in the core protocol.

A few protocol requests return replies that contain no data. <Xproto.h> does not define reply structures for these. Instead, they use the xGenericReply structure, which contains only a type, length, and sequence number (and sufficient padding to make it 32 bytes long).

Starting to Write a Stub Routine

An Xlib stub routine should always start like this:

#include "Xlibint.h"
XDoSomething (arguments, ... )
/* argument declarations */
{
register XDoSomethingReq *req;

If the protocol request has a reply, then the variable declarations should include the reply structure for the request. The following is an example:

xDoSomethingReply rep;

Locking Data Structures

To lock the display structure for systems that want to support multithreaded access to a single display connection, each stub will need to lock its critical section. Generally, this section is the point from just before the appropriate GetReq call until all arguments to the call have been stored into the buffer. The precise instructions needed for this locking depend upon the machine architecture. Two calls, which are generally implemented as macros, have been provided.

LockDisplay(display)
      Display *display;

UnlockDisplay(display)
      Display *display;

display: Specifies the connection to the X server.

Sending the Protocol Request and Arguments

After the variable declarations, a stub routine should call one of four macros defined in <Xlibint.h>: GetReq(), GetReqExtra(), GetResReq(), or GetEmptyReq(). All of these macros take, as their first argument, the name of the protocol request as declared in <Xproto.h> except with X_ removed. Each one declares a Display structure pointer, called dpy, and a pointer to a request structure, called req, which is of the appropriate type. The macro then appends the request structure to the output buffer, fills in its type and length field, and sets req to point to it.

If the protocol request has no arguments (for instance, X_GrabServer), then use GetEmptyReq().

GetEmptyReq (DoSomething, req);

If the protocol request has a single 32-bit argument (such as a Pixmap, Window, Drawable, Atom, and so on), then use GetResReq(). The second argument to the macro is the 32-bit object. X_MapWindow is a good example.

GetResReq (DoSomething, rid, req);

The rid argument is the Pixmap, Window, or other resource ID.

If the protocol request takes any other argument list, then call GetReq(). After the GetReq(), you need to set all the other fields in the request structure, usually from arguments to the stub routine.

GetReq (DoSomething, req);
/* fill in arguments here */
req->arg1 = arg1;
req->arg2 = arg2;

A few stub routines (such as XCreateGC() and XCreatePixmap()) return a resource ID to the caller but pass a resource ID as an argument to the protocol request. Such routines use the macro XAllocID to allocate a resource ID from the range of IDs that were assigned to this client when it opened the connection.

rid = req->rid = XAllocID();
return (rid);

Finally, some stub routines transmit a fixed amount of variable length data after the request. Typically, these routines (such as XMoveWindow() and XSetBackground()) are special cases of more general functions like XMoveResizeWindow() and XChangeGC(). These special case routines use GetReqExtra(), which is the same as GetReq except that it takes an additional argument (the number of extra bytes to allocate in the output buffer after the request structure). This number should always be a multiple of four.

Variable Length Arguments

Some protocol requests take additional variable length data that follow the xDoSomethingReq structure. The format of this data varies from request to request. Some requests require a sequence of 8-bit bytes, others a sequence of 16-bit or 32-bit entities, and still others a sequence of structures.

It is necessary to add the length of any variable length data to the length field of the request structure. That length field is in units of 32-bit longwords. If the data is a string or other sequence of 8-bit bytes, then you must round the length up and shift it before adding:

req->length += (nbytes+3)>>2;

To transmit variable length data, use the Data macros. If the data fits into the output buffer, then this macro copies it to the buffer. If it does not fit, however, the Data macro calls _XSend(), which transmits first the contents of the buffer and then your data. The Data macros take three arguments: the Display, a pointer to the beginning of the data, and the number of bytes to be sent.

Data(display, (char *) data, nbytes);
Data16(display, (short *) data, nbytes);
Data32(display, (long *) data, nbytes);

Data(), Data16(), and Data32() are macros that may use their last argument more than once, so that argument should be a variable rather than an expression such as "nitems*sizeof(item)". You should do that kind of computation in a separate statement before calling them. Use the appropriate macro when sending byte, short, or long data.

If the protocol request requires a reply, then call the procedure _XSend instead of the Data macro. _XSend takes the same arguments, but because it sends your data immediately instead of copying it into the output buffer (which would later be flushed anyway by the following call on _XReply()), it is faster.

Replies

If the protocol request has a reply, then call _XReply after you have finished dealing with all the fixed and variable length arguments. _XReply flushes the output buffer and waits for an xReply packet to arrive. If any events arrive in the meantime, _XReply places them in the queue for later use.

Status _XReply(display, rep, extra, discard)
      Display *display;
      xReply *rep;
      int extra;
      Bool discard;

display: Specifies the connection to the X server.
rep: Specifies the reply structure.
extra: Specifies the number of 32-bit words expected after the replay.
discard: Specifies if beyond the "extra" data should be discarded.

_XReplywaits for a reply packet and copies its contents into the specified rep. _XReply handles error and event packets that occur before the reply is received. _XReply takes four arguments:

A Display * structure
A pointer to a reply structure (which must be cast to an xReply *)
The number of additional 32-bit words (beyond sizeof(xReply) = 32 bytes) in the reply structure
A Boolean that indicates whether _XReply is to discard any additional bytes beyond those it was told to read

Because most reply structures are 32 bytes long, the third argument is usually 0. The only core protocol exceptions are the replies to XGetWindowAttributes(), XQueryFont(), XQueryKeymap(), and XGetKeyboardControl(), which have longer replies.

The last argument should be False if the reply structure is followed by additional variable length data (such as a list or string). It should be True if there is not any variable length data.

This last argument is provided for upward-compatibility reasons to allow a client to communicate properly with a hypothetical later version of the server that sends more data than the client expected. For example, some later version of XGetWindowAttributes might use a larger, but compatible, xGetWindowAttributesReply that contains additional attribute data at the end.

_XReplyreturns True if it received a reply successfully or False if it received any sort of error.

For a request with a reply that is not followed by variable length data, you write something like:

_XReply(display, (xReply *)&rep, 0, True);
*ret1 = rep.ret1;
*ret2 = rep.ret2;
*ret3 = rep.ret3;
UnlockDisplay()(dpy);
SyncHandle();
return (rep.ret4);
}

If there is variable length data after the reply, change the True to False, and use the appropriate _XRead function to read the variable length data.

_XRead(display, data_return, nbytes)
       Display *display;
       char *data_return;
       long nbytes;

display: Specifies the connection to the X server.
data_return: Specifies the buffer.
nbytes: Specifies the number of bytes required.

_XReadreads the specified number of bytes into data_return.

_XRead16

_XRead16(display, data_return, nbytes)
       Display *display;
       short *data_return;
       long nbytes;

display: Specifies the connection to the X server.
data_return: Specifies the buffer.
nbytes: Specifies the number of bytes required.

_XRead16reads the specified number of bytes, unpacking them as 16-bit quantities, into the specified array as shorts.

_XRead32

_XRead32(display, data_return, nbytes)
       Display *display;
       long *data_return;
       long nbytes;

display: Specifies the connection to the X server.
data_return: Specifies the buffer.
nbytes: Specifies the number of bytes required.

_XRead32reads the specified number of bytes, unpacking them as 32-bit quantities, into the specified array as longs.

_XRead16Pad

_XRead16Pad(display, data_return, nbytes)
       Display *display;
       short *data_return;
       long nbytes;

display: Specifies the connection to the X server.
data_return: Specifies the buffer.
nbytes: Specifies the number of bytes required.

_XRead16Padreads the specified number of bytes, unpacking them as 16-bit quantities, into the specified array as shorts. If the number of bytes is not a multiple of four, _XRead16Pad reads and discards up to three additional pad bytes.

_XReadPad

_XReadPad(display, data_return, nbytes)
       Display *display;
       char *data_return;
       long nbytes;

display: Specifies the connection to the X server.
data_return: Specifies the buffer.
nbytes: Specifies the number of bytes required.

_XReadPadreads the specified number of bytes into data_return. If the number of bytes is not a multiple of four, _XReadPad reads and discards up to three additional pad bytes.

Each protocol request is a little different. For further information, see the Xlib sources for examples.

Synchronous Calling

To ease debugging, each routine should have a call, just before returning to the user, to a routine called SyncHandle(). This routine generally is implemented as a macro. If synchronous mode is enabled (see XSynchronize()), the request is sent immediately. The library, however, waits until any error the routine could generate at the server has been handled.

Allocating and Deallocating Memory

To support the possible reentry of these routines, you must observe several conventions when allocating and deallocating memory, most often done when returning data to the user from the window system of a size the caller could not know in advance (for example, a list of fonts or a list of extensions). The standard C library routines on many systems are not protected against signals or other multithreaded uses. The following analogies to standard I/O library routines have been defined:

Xmalloc(): Replaces malloc().
XFree(): Replaces free().
Xcalloc(): Replaces calloc().

These should be used in place of any calls you would make to the normal C library routines.

If you need a single scratch buffer inside a critical section (for example, to pack and unpack data to and from the wire protocol), the general memory allocators may be too expensive to use (particularly in output routines, which are performance critical). The routine below returns a scratch buffer for your use:

char *_XAllocScratch(display, nbytes)
      Display *display;
      unsigned long nbytes;

display: Specifies the connection to the X server.
nbytes: Specifies the number of bytes required.

This storage must only be used inside of the critical section of your stub.

Portability Considerations

Many machine architectures, including many of the more recent RISC architectures, do not correctly access data at unaligned locations; their compilers pad out structures to preserve this characteristic. Many other machines capable of unaligned references pad inside of structures as well to preserve alignment, because accessing aligned data is usually much faster. Because the library and the server use structures to access data at arbitrary points in a byte stream, all data in request and reply packets must be naturally aligned; that is, 16-bit data starts on 16-bit boundaries in the request and 32-bit data on 32-bit boundaries. All requests must be a multiple of 32 bits in length to preserve the natural alignment in the data stream. You must pad structures out to 32-bit boundaries. Pad information does not have to be zeroed unless you want to preserve such fields for future use in your protocol requests. Floating point varies radically between machines and should be avoided completely if at all possible.

This code may run on machines with 16-bit ints. So, if any integer argument, variable, or return value either can take only nonnegative values or is declared as a CARD16 in the protocol, be sure to declare it as unsigned int and not as int. (This, of course, does not apply to Booleans or enumerations.)

Similarly, if any integer argument or return value is declared CARD32 in the protocol, declare it as an unsigned long and not as int or long. This also goes for any internal variables that may take on values larger than the maximum 16-bit unsigned int.

The library currently assumes that a char is 8 bits, a short is 16 bits, an int is 16 or 32 bits, and a long is 32 bits. The PackData macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. However, much more work is needed to make this work properly.

Deriving the Correct Extension Opcode

The remaining problem a writer of an extension stub routine faces that the core protocol does not face is to map from the call to the proper major and minor opcodes. While there are a number of strategies, the simplest and fastest is outlined below.

Declare an array of pointers, _NFILE long (this is normally found in <stdio.h> and is the number of file descriptors supported on the system) of type XExtCodes(). Make sure these are all initialized to NULL.
When your stub is entered, your initialization test is just to use the display pointer passed in to access the file descriptor and an index into the array. If the entry is NULL, then this is the first time you are entering the routine for this display. Call your initialization routine and pass it to the display pointer.
Once in your initialization routine, call XInitExtension(); if it succeeds, store the pointer returned into this array. Make sure to establish a close display handler to allow you to zero the entry. Do whatever other initialization your extension requires. (For example, install event handlers and so on.) Your initialization routine would normally return a pointer to the XExtCodes structure for this extension, which is what would normally be found in your array of pointers.
After returning from your initialization routine, the stub can now continue normally, because it has its major opcode safely in its hand in the XExtCodes structure.