diff options
Diffstat (limited to 'libX11/specs/libX11/AppC')
| -rw-r--r-- | libX11/specs/libX11/AppC | 2230 |
1 files changed, 2230 insertions, 0 deletions
diff --git a/libX11/specs/libX11/AppC b/libX11/specs/libX11/AppC new file mode 100644 index 000000000..43261ba83 --- /dev/null +++ b/libX11/specs/libX11/AppC @@ -0,0 +1,2230 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" 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 X CONSORTIUM 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 X Consortium 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 X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBAppendix C\fP\s-1 + +\s+1\fBExtensions\fP\s-1 +.sp 2 +.na +.LP +.XS +Appendix C: Extensions +.XE +Because X can evolve by extensions to the core protocol, +it is important that extensions not be perceived as second-class citizens. +At some point, +your favorite extensions may be adopted as additional parts of the +X Standard. +.LP +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, +it is also important that extensions perform lazy evaluations, +automatically initializing themselves when called for the first time. +.LP +This appendix describes techniques for writing extensions to Xlib that will +run at essentially the same performance as the core protocol requests. +.NT +It is expected that a given extension to X consists of multiple +requests. +Defining 10 new features as 10 separate extensions is a bad practice. +Rather, they should be packaged into a single extension +and should use minor opcodes to distinguish the requests. +.NE +.LP +The symbols and macros used for writing stubs to Xlib are listed in +.hN X11/Xlibint.h . +.SH +Basic Protocol Support Routines +.LP +The basic protocol requests for extensions are +.PN XQueryExtension +and +.PN XListExtensions . +.IN "XQueryExtension" "" "@DEF@" +.sM +.FD 0 +Bool XQueryExtension(\^\fIdisplay\fP, \fIname\fP, \fImajor_opcode_return\fP, \ +\fIfirst_event_return\fP, \fIfirst_error_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname;\fP\^ +.br + int *\fImajor_opcode_return\fP\^; +.br + int *\fIfirst_event_return\fP\^; +.br + int *\fIfirst_error_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the extension name. +.IP \fImajor_opcode_return\fP 1i +Returns the major opcode. +.IP \fIfirst_event_return\fP 1i +Returns the first event code, if any. +.IP \fIfirst_error_return\fP 1i +Returns the first error code, if any. +.LP +.eM +The +.PN XQueryExtension +function determines if the named extension is present. +If the extension is not present, +.PN XQueryExtension +returns +.PN False ; +otherwise, it returns +.PN True . +If the extension is present, +.PN XQueryExtension +returns the major opcode for the extension to major_opcode_return; +otherwise, +it returns zero. +Any minor opcode and the request formats are specific to the +extension. +If the extension involves additional event types, +.PN XQueryExtension +returns the base event type code to first_event_return; +otherwise, +it returns zero. +The format of the events is specific to the extension. +If the extension involves additional error codes, +.PN XQueryExtension +returns the base error code to first_error_return; +otherwise, +it returns zero. +The format of additional data in the errors is specific to the extension. +.LP +If the extension name is not in the Host Portable Character Encoding +the result is implementation-dependent. +Uppercase and lowercase matter; +the strings ``thing'', ``Thing'', and ``thinG'' +are all considered different names. +.IN "XListExtensions" "" "@DEF@" +.sM +.FD 0 +char **XListExtensions(\^\fIdisplay\fP, \fInextensions_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fInextensions_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInextensions_return\fP 1i +Returns the number of extensions listed. +.LP +.eM +The +.PN XListExtensions +function 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. +.IN "XFreeExtensionList" "" "@DEF@" +.sM +.FD 0 +XFreeExtensionList(\^\fIlist\fP\^) +.br + char **\fIlist\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the list of extension names. +.LP +.eM +The +.PN XFreeExtensionList +function frees the memory allocated by +.PN XListExtensions . +.SH +Hooking into Xlib +.LP +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. +.LP +In extensions, stubs first should check to see if they have initialized +themselves on a connection. +If they have not, they then should call +.PN XInitExtension +to attempt to initialize themselves on the connection. +.LP +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. +.LP +The +.PN XExtCodes +structure returns the information from +.PN XInitExtension +and is defined in +.hN X11/Xlib.h : +.LP +.IN "XExtCodes" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +.IN "XInitExtension" "" "@DEF@" +.sM +.FD 0 +XExtCodes *XInitExtension(\^\fIdisplay\fP, \fIname\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIname\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIname\fP 1i +Specifies the extension name. +.LP +.eM +The +.PN XInitExtension +function 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, +.PN XInitExtension +returns NULL. +.LP +If the extension name is not in the Host Portable Character Encoding, +the result is implementation-dependent. +Uppercase and lowercase matter; +the strings ``thing'', ``Thing'', and ``thinG'' +are all considered different names. +.LP +The extension number in the +.PN XExtCodes +structure is +needed in the other calls that follow. +This extension number is unique only to a single connection. +.LP +.IN "XAddExtension" "" "@DEF@" +.sM +.FD 0 +XExtCodes *XAddExtension\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +For local Xlib extensions, the +.PN XAddExtension +function allocates the +.PN XExtCodes +structure, bumps the extension number count, +and chains the extension onto the extension list. +(This permits extensions to Xlib without requiring server extensions.) +.SH +Hooks into the Library +.LP +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. +.LP +All of these functions return the previous procedure defined for this +extension. +.IN "XESetCloseDisplay" "" "@DEF@" +.sM +.FD 0 +int (*XESetCloseDisplay(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when the display is closed. +.LP +.eM +The +.PN XESetCloseDisplay +function defines a procedure to be called whenever +.PN XCloseDisplay +is called. +It returns any previously defined procedure, usually NULL. +.LP +When +.PN XCloseDisplay +is called, +your procedure is called +with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetCreateGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetCreateGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a GC is closed. +.LP +.eM +The +.PN XESetCreateGC +function defines a procedure to be called whenever +a new GC is created. +It returns any previously defined procedure, usually NULL. +.LP +When a GC is created, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + GC \fIgc\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetCopyGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetCopyGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when GC components are copied. +.LP +.eM +The +.PN XESetCopyGC +function defines a procedure to be called whenever +a GC is copied. +It returns any previously defined procedure, usually NULL. +.LP +When a GC is copied, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + GC \fIgc\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetFreeGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetFreeGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc)\fP\^)(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a GC is freed. +.LP +.eM +The +.PN XESetFreeGC +function defines a procedure to be called whenever +a GC is freed. +It returns any previously defined procedure, usually NULL. +.LP +When a GC is freed, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + GC \fIgc\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetCreateFont" "" "@DEF@" +.sM +.FD 0 +int (*XESetCreateFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a font is created. +.LP +.eM +The +.PN XESetCreateFont +function defines a procedure to be called whenever +.PN XLoadQueryFont +and +.PN XQueryFont +are called. +It returns any previously defined procedure, usually NULL. +.LP +When +.PN XLoadQueryFont +or +.PN XQueryFont +is called, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + XFontStruct *\fIfs\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +.IN "XESetFreeFont" "" "@DEF@" +.sM +.FD 0 +int (*XESetFreeFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a font is freed. +.LP +.eM +The +.PN XESetFreeFont +function defines a procedure to be called whenever +.PN XFreeFont +is called. +It returns any previously defined procedure, usually NULL. +.LP +When +.PN XFreeFont +is called, your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^) + Display *\fIdisplay\fP\^; + XFontStruct *\fIfs\fP\^; + XExtCodes *\fIcodes\fP\^; +.De +.LP +.eM +The +.PN XESetWireToEvent +and +.PN XESetEventToWire +functions allow you to define new events to the library. +An +.PN XEvent +structure always has a type code (type +.PN int ) +as the first component. +This uniquely identifies what kind of event it is. +The second component is always the serial number (type +.PN unsigned +.PN long ) +of the last request processed by the server. +The third component is always a Boolean (type +.PN Bool ) +indicating whether the event came from a +.PN 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. +.NT +There is an implementation limit such that your host event +structure size cannot be bigger than the size of the +.PN 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. +.NE +.IN "XESetWireToEvent" "" "@DEF@" +.sM +.FD 0 +int (*XESetWireToEvent(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_number\fP\^; +.br + Status (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_number\fP 1i +Specifies the event code. +.IP \fIproc\fP 1i +Specifies the procedure to call when converting an event. +.LP +.eM +The +.PN XESetWireToEvent +function defines a procedure to be called when an event +needs to be converted from wire format +.Pn ( xEvent ) +to host format +.Pn ( XEvent ). +The event number defines which protocol event number to install a +conversion procedure for. +.PN XESetWireToEvent +returns any previously defined procedure. +.NT +You can replace a core event conversion function 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. +.NE +When Xlib needs to convert an event from wire format to host +format, your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +Status (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^) + Display *\fIdisplay\fP\^; + XEvent *\fIre\fP\^; + xEvent *\fIevent\fP\^; +.De +.LP +.eM +Your procedure 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 +.PN 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 +.PN xEvent +structure. +You should copy all other members from the +.PN xEvent +structure (wire format) to the +.PN XEvent +structure (host format). +Your conversion procedure should return +.PN True +if the event should be placed in the queue or +.PN False +if it should not be placed in the queue. +.LP +To initialize the serial number component of the event, call +.PN _XSetLastRequestRead +with the event and use the return value. +.LP +.IN "_XSetLastRequestRead" "" "@DEF@" +.sM +.FD 0 +unsigned long _XSetLastRequestRead(\^\fIdisplay\fP, \fIrep\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + xGenericReply *\fIrep\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrep\fP 1i +Specifies the wire event structure. +.LP +.eM +The +.PN _XSetLastRequestRead +function computes and returns a complete serial number from the partial +serial number in the event. +.sp +.LP +.IN "XESetEventToWire" "" "@DEF@" +.sM +.FD 0 +Status (*XESetEventToWire(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIevent_number\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIevent_number\fP 1i +Specifies the event code. +.IP \fIproc\fP 1i +Specifies the procedure to call when converting an event. +.LP +.eM +The +.PN XESetEventToWire +function defines a procedure to be called when an event +needs to be converted from host format +.Pn ( XEvent ) +to wire format +.Pn ( xEvent ) +form. +The event number defines which protocol event number to install a +conversion procedure for. +.PN XESetEventToWire +returns any previously defined procedure. +It returns zero if the conversion fails or nonzero otherwise. +.NT +You can replace a core event conversion function 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 sent to another client. +.NE +When Xlib needs to convert an event from host format to wire format, +your procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^) + Display *\fIdisplay\fP\^; + XEvent *\fIre\fP\^; + xEvent *\fIevent\fP\^; +.De +.LP +.eM +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 +.PN XEvent +structure. +All other members then should be copied from the host format to the +.PN xEvent +structure. +.IN "XESetWireToError" "" "@DEF@" +.sM +.FD 0 +Bool (*XESetWireToError(\^\fIdisplay\fP, \fIerror_number\fP, \fIproc\fP\^)(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIerror_number\fP\^; +.br + Bool (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIerror_number\fP 1i +Specifies the error code. +.IP \fIproc\fP 1i +Specifies the procedure to call when an error is received. +.LP +.eM +The +.PN XESetWireToError +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 procedure for. +.PN XESetWireToError +returns any previously defined procedure. +.LP +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. +.LP +When Xlib needs to convert an error from wire format to host format, +the procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +Bool (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIhe\fP, \fIwe\fP\^) + Display *\fIdisplay\fP\^; + XErrorEvent *\fIhe\fP\^; + xError *\fIwe\fP\^; +.De +.LP +.eM +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 +.PN XEvent +structure and so can be cast to a type larger than an +.PN XErrorEvent +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 +.PN False ; +otherwise, it should return +.PN True . +.IN "XESetError" "" "@DEF@" +.sM +.FD 0 +int (*XESetError(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when an error is received. +.LP +.eM +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 functions are query operations, in any +case, and are typically programmed to be synchronous). +.LP +When Xlib detects a protocol error in +.PN _XReply , +it calls your procedure with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +int (*\fIproc\fP\^)(\fIdisplay\fP, \fIerr\fP, \fIcodes\fP, \fIret_code\fP\^) + Display *\fIdisplay\fP\^; + xError *\fIerr\fP\^; + XExtCodes *\fIcodes\fP\^; + int *\fIret_code\fP\^; +.De +.LP +.eM +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 +.PN _XReply +returned to. +.LP +If your procedure 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 procedure returns nonzero, +the error is suppressed, and +.PN _XReply +returns the value of ret_code. +.IN "XESetErrorString" "" "@DEF@" +.sM +.FD 0 +char *(*XESetErrorString(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + char *(\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call to obtain an error string. +.LP +.eM +The +.PN XGetErrorText +function returns a string to the user for an error. +.PN XESetErrorString +allows you to define a procedure to be called that +should return a pointer to the error message. +The following is an example. +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcode\fP, \fIcodes\fP, \fIbuffer\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + int \fIcode\fP\^; + XExtCodes *\fIcodes\fP\^; + char *\fIbuffer\fP\^; + int \fInbytes\fP\^; +.De +.LP +.eM +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. +.IN "XESetPrintErrorValues" "" "@DEF@" +.sM +.FD 0 +void (*XESetPrintErrorValues(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + void (\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when an error is printed. +.LP +.eM +The +.PN XESetPrintErrorValues +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. +It returns any previously defined procedure. +.LP +When Xlib needs to print an error, +the procedure is called with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIev\fP, \fIfp\fP\^) + Display *\fIdisplay\fP\^; + XErrorEvent *\fIev\fP\^; + void *\fIfp\fP\^; +.De +.LP +.eM +The structure pointed at by ev is guaranteed to be as large as an +.PN XEvent +structure and so can be cast to a type larger than an +.PN XErrorEvent +to obtain additional values set by using +.PN XESetWireToError . +The underlying type of the fp argument is system dependent; +on a POSIX-compliant system, fp should be cast to type FILE*. +.IN "XESetFlushGC" "" "@DEF@" +.sM +.FD 0 +int (*XESetFlushGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int *(\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a GC is flushed. +.LP +.eM +The procedure set by the +.PN XESetFlushGC +function has the same interface as the procedure set by the +.PN XESetCopyGC +function, but is called when a GC cache needs to be updated in the server. +.IN "XESetBeforeFlush" "" "@DEF@" +.sM +.FD 0 +int (*XESetBeforeFlush(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIextension\fP\^; +.br + int *(\^*\fIproc\fP\^)(\^); +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIextension\fP 1i +Specifies the extension number. +.IP \fIproc\fP 1i +Specifies the procedure to call when a buffer is flushed. +.LP +.eM +The +.PN XESetBeforeFlush +function defines a procedure to be called when data is about to be +sent to the server. When data is about to be sent, your procedure is +called one or more times with these arguments: +.LP +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +.R +void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP, \fIdata\fP, \fIlen\fP\^) + Display *\fIdisplay\fP\^; + XExtCodes *\fIcodes\fP\^; + char *\fIdata\fP\^; + long \fIlen\fP\^; +.De +.LP +.eM +The data argument specifies a portion of the outgoing data buffer, +and its length in bytes is specified by the len argument. +Your procedure must not alter the contents of the data and must not +do additional protocol requests to the same display. +.SH +Hooks onto Xlib Data Structures +.LP +Various Xlib data structures have provisions for extension procedures +to chain extension supplied data onto a list. +These structures are +.PN GC , +.PN Visual , +.PN Screen , +.PN ScreenFormat , +.PN Display , +and +.PN XFontStruct . +Because the list pointer is always the first member in the structure, +a single set of procedures can be used to manipulate the data +on these lists. +.LP +The following structure is used in the functions in this section +and is defined in +.hN X11/Xlib.h : +.LP +.IN "XExtData" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +When any of the data structures listed above are freed, +the list is walked, and the structure's free procedure (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. +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +union { Display *display; + GC gc; + Visual *visual; + Screen *screen; + ScreenFormat *pixmap_format; + XFontStruct *font } XEDataObject; +.De +.LP +.eM +.IN "XEHeadOfExtensionList" "" "@DEF@" +.sM +.FD 0 +XExtData **XEHeadOfExtensionList(\^\fIobject\fP\^) + XEDataObject \fIobject\fP\^; +.FN +.IP \fIobject\fP 1i +Specifies the object. +.LP +.eM +The +.PN XEHeadOfExtensionList +function returns a pointer to the list of extension structures attached +to the specified object. +In concert with +.PN XAddToExtensionList , +.PN XEHeadOfExtensionList +allows an extension to attach arbitrary data to any of the structures +of types contained in +.PN XEDataObject . +.LP +.IN "XAddToExtensionList" "" "@DEF@" +.sM +.FD 0 +XAddToExtensionList(\^\fIstructure\fP, \fIext_data\fP\^) +.br + XExtData **\fIstructure\fP\^; +.br + XExtData *\fIext_data\fP\^; +.FN +.IP \fIstructure\fP 1i +Specifies the extension list. +.IP \fIext_data\fP 1i +Specifies the extension data structure to add. +.LP +.eM +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 function. +.IN "XFindOnExtensionList" "" "@DEF@" +.sM +.FD 0 +XExtData *XFindOnExtensionList(\^\fIstructure\fP, \fInumber\fP\^) +.br + struct _XExtData **\fIstructure\fP\^; +.br + int \fInumber\fP\^; +.FN +.IP \fIstructure\fP 1i +Specifies the extension list. +.IP \fInumber\fP 1i +Specifies the extension number from +.PN XInitExtension . +.LP +.eM +The +.PN XFindOnExtensionList +function 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. +.LP +The +.PN XAllocID +macro, which allocates and returns a resource ID, is defined in +.hN X11/Xlib.h . +.IN "XAllocID" "" "@DEF@" +.sM +.FD 0 +XAllocID\^(\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +This macro is a call through the +.PN Display +structure to an internal resource ID allocator. +It returns a resource ID that you can use when creating new resources. +.LP +The +.PN XAllocIDs +macro allocates and returns an array of resource ID. +.IN "XAllocIDs" "" "@DEF@" +.sM +.FD 0 +XAllocIDs\^(\fIdisplay\fP, \fIids_return\fP, \fIcount\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XID *\fIids_return\fP\^; +.br + int \fIcount\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIids_return\fP 1i +Returns the resource IDs. +.IP \fIrep\fP 1i +Specifies the number of resource IDs requested. +.LP +.eM +This macro is a call through the +.PN Display +structure to an internal resource ID allocator. +It returns resource IDs to the array supplied by the caller. +To correctly handle automatic reuse of resource IDs, you must call +.PN XAllocIDs +when requesting multiple resource IDs. This call might generate +protocol requests. +.SH +GC Caching +.LP +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 procedure 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. +.LP +The +.PN FlushGC +macro checks the dirty bits in the library's GC structure and calls +.PN _XFlushGCCache +if any elements have changed. +The +.PN FlushGC +macro is defined as follows: +.IN "FlushGC" "" "@DEF@" +.sM +.FD 0 +FlushGC\^(\^\fIdisplay\fP\^, \fIgc\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +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 +.PN _XFlushGCCache +procedure +to force the cache to be flushed. +The +.PN _XFlushGCCache +procedure +is defined as follows: +.IN "_XFlushGCCache" "" "@DEF@" +.sM +.FD 0 +_XFlushGCCache\^(\^\fIdisplay\fP\^, \fIgc\fP\^) +.br + Display *\^\fIdisplay\fP\^; +.br + GC \fIgc\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIgc\fP 1i +Specifies the GC. +.LP +.eM +.SH +Graphics Batching +.LP +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 +.PN 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 +.PN XDrawPoint +stub. +(Writing extension stubs is discussed in the next section.) +.IP +.sM +.nf + +#include <X11/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(); +} +.fi +.LP +.eM +To keep clients from generating very long requests that may monopolize the +server, +there is a symbol defined in +.hN X11/Xlibint.h +of EPERBATCH on the number of requests batched. +Most of the performance benefit occurs in the first few merged requests. +Note that +.PN FlushGC +is called \fIbefore\fP picking up the value of last_req, +because it may modify this field. +.SH +Writing Extension Stubs +.LP +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.'' +.SH +Requests, Replies, and Xproto.h +.LP +The +.hN X11/Xproto.h +file contains three sets of definitions that +are of interest to the stub implementor: +request names, request structures, and reply structures. +.LP +You need to generate a file equivalent to +.hN X11/Xproto.h +for your extension and need to include it in your stub procedure. +Each stub procedure also must include +.hN X11/Xlibint.h . +.LP +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 +.hN X11/Xlibint.h , +takes advantage of this naming scheme. +.LP +For each X request, +there is a definition in +.hN X11/Xproto.h +that looks similar to this: +.LP +.Ds +.R +#define X_DoSomething 42 +.De +In your extension header file, +this will be a minor opcode, +instead of a major opcode. +.SH +Request Format +.LP +Every request contains an 8-bit major opcode and a 16-bit length field +expressed in units of 4 bytes. +Every request consists of 4 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 +.PN 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). +.LP +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 second 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. +.LP +To help but not cure portability problems to certain machines, the +.PN B16 +and +.PN 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. +.LP +Most protocol requests have a corresponding structure typedef in +.hN X11/Xproto.h , +which looks like: +.LP +.IN "xDoSomethingReq" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +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 the +.PN xResourceReq +structure in +.hN X11/Xproto.h . +This structure is used for any request whose single argument is a +.PN Window , +.PN Pixmap , +.PN Drawable , +.PN GContext , +.PN Font , +.PN Cursor , +.PN Colormap , +.PN Atom , +or +.PN VisualID . +.LP +.IN "xResourceReq" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +If convenient, +you can do something similar in your extension header file. +.LP +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. +.LP +A few protocol requests take no arguments at all. +Instead, they use the +.PN xReq +structure in +.hN X11/Xproto.h , +which contains only a reqType and a length (and a pad byte). +.LP +If the protocol request requires a reply, +then +.hN X11/Xproto.h +also contains a reply structure typedef: +.LP +.IN "xDoSomethingReply" "" "@DEF@" +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +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; +.De +.LP +.eM +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: +.IP \(bu 5 +The reply structure is followed by variable-length data, +such as a list or string. +.IP \(bu 5 +The reply structure is longer than 32 bytes. +.LP +Only +.PN GetWindowAttributes , +.PN QueryFont , +.PN QueryKeymap , +and +.PN GetKeyboardControl +have reply structures longer than 32 bytes in the core protocol. +.LP +A few protocol requests return replies that contain no data. +.hN X11/Xproto.h +does not define reply structures for these. +Instead, they use the +.PN xGenericReply +structure, which contains only a type, length, +and sequence number (and sufficient padding to make it 32 bytes long). +.SH +Starting to Write a Stub Procedure +.LP +An Xlib stub procedure should start like this: +.LP +.Ds +.R +#include "<X11/Xlibint.h> + +XDoSomething (arguments, ... ) +/* argument declarations */ +{ + +register XDoSomethingReq *req; +\^... +.De +If the protocol request has a reply, +then the variable declarations should include the reply structure for the request. +The following is an example: +.LP +.Ds +.R +xDoSomethingReply rep; +.De +.SH +Locking Data Structures +.LP +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. +.IN "LockDisplay" "" "@DEF@" +.sM +.FD 0 +LockDisplay(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.LP +.IN "UnlockDisplay" "" "@DEF@" +.FD 0 +UnlockDisplay(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.SH +Sending the Protocol Request and Arguments +.LP +After the variable declarations, +a stub procedure should call one of four macros defined in +.hN X11/Xlibint.h : +.PN GetReq , +.PN GetReqExtra , +.PN GetResReq , +or +.PN GetEmptyReq . +All of these macros take, as their first argument, +the name of the protocol request as declared in +.hN X11/Xproto.h +except with X_ removed. +Each one declares a +.PN 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. +.LP +If the protocol request has no arguments (for instance, X_GrabServer), +then use +.PN GetEmptyReq . +.LP +.Ds +.R +GetEmptyReq (DoSomething, req); +.De +If the protocol request has a single 32-bit argument (such as a +.PN Pixmap , +.PN Window , +.PN Drawable , +.PN Atom , +and so on), +then use +.PN GetResReq . +The second argument to the macro is the 32-bit object. +.PN X_MapWindow +is a good example. +.LP +.Ds +.R +GetResReq (DoSomething, rid, req); +.De +The rid argument is the +.PN Pixmap , +.PN Window , +or other resource ID. +.LP +If the protocol request takes any other argument list, +then call +.PN GetReq . +After the +.PN GetReq , +you need to set all the other fields in the request structure, +usually from arguments to the stub procedure. +.LP +.Ds +.R +GetReq (DoSomething, req); +/* fill in arguments here */ +req->arg1 = arg1; +req->arg2 = arg2; +\^... +.De +A few stub procedures (such as +.PN XCreateGC +and +.PN XCreatePixmap ) +return a resource ID to the caller but pass a resource ID as an argument +to the protocol request. +Such procedures use the macro +.PN XAllocID +to allocate a resource ID from the range of IDs +that were assigned to this client when it opened the connection. +.LP +.Ds +.R +rid = req->rid = XAllocID(); +\^... +return (rid); +.De +Finally, some stub procedures transmit a fixed amount of variable-length +data after the request. +Typically, these procedures (such as +.PN XMoveWindow +and +.PN XSetBackground ) +are special cases of more general functions like +.PN XMoveResizeWindow +and +.PN XChangeGC . +These procedures use +.PN GetReqExtra , +which is the same as +.PN 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. +.SH +Variable Length Arguments +.LP +Some protocol requests take additional variable-length data that +follow the +.PN 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. +.LP +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: +.LP +.Ds +.R +req->length += (nbytes+3)>>2; +.De +To transmit variable-length data, use the +.PN 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 +.PN Data +macro calls +.PN _XSend , +which transmits first the contents of the buffer and then your data. +The +.PN Data +macros take three arguments: +the display, a pointer to the beginning of the data, +and the number of bytes to be sent. +.sM +.FD 0 +Data(\^\fIdisplay\fP, (char *) \fIdata\fP, \fInbytes\fP\^); +.sp +Data16(\^\fIdisplay\fP, (short *) \fIdata\fP, \fInbytes\fP\^); +.sp +Data32(\^\fIdisplay\fP, (long *) \fIdata\fP, \fInbytes\fP\^); +.FN +.LP +.eM +.PN Data , +.PN Data16 , +and +.PN 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. +.LP +If the protocol request requires a reply, +then call the procedure +.PN _XSend +instead of the +.PN Data +macro. +.PN _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 +.PN _XReply ), +it is faster. +.SH +Replies +.LP +If the protocol request has a reply, +then call +.PN _XReply +after you have finished dealing with +all the fixed-length and variable-length arguments. +.PN _XReply +flushes the output buffer and waits for an +.PN xReply +packet to arrive. +If any events arrive in the meantime, +.PN _XReply +places them in the queue for later use. +.IN "_XReply" "" "@DEF@" +.sM +.FD 0 +Status _XReply(\^\fIdisplay\fP, \fIrep\fP, \fIextra\fP, \fIdiscard\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + xReply *\fIrep\fP\^; +.br + int \fIextra\fP\^; +.br + Bool \fIdiscard\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIrep\fP 1i +Specifies the reply structure. +.IP \fIextra\fP 1i +Specifies the number of 32-bit words expected after the replay. +.IP \fIdiscard\fP 1i +Specifies if any data beyond that specified in the extra argument +should be discarded. +.LP +.eM +The +.PN _XReply +function waits for a reply packet and copies its contents into the +specified rep. +.PN _XReply +handles error and event packets that occur before the reply is received. +.PN _XReply +takes four arguments: +.IP \(bu 5 +A +.PN Display +* structure +.IP \(bu 5 +A pointer to a reply structure (which must be cast to an +.PN xReply +*) +.IP \(bu 5 +The number of additional 32-bit words (beyond +.Pn sizeof( xReply ) += 32 bytes) +in the reply structure +.IP \(bu 5 +A Boolean that indicates whether +.PN _XReply +is to discard any additional bytes +beyond those it was told to read +.LP +Because most reply structures are 32 bytes long, +the third argument is usually 0. +The only core protocol exceptions are the replies to +.PN GetWindowAttributes , +.PN QueryFont , +.PN QueryKeymap , +and +.PN GetKeyboardControl , +which have longer replies. +.LP +The last argument should be +.PN False +if the reply structure is followed +by additional variable-length data (such as a list or string). +It should be +.PN True +if there is not any variable-length data. +.NT +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 +.PN GetWindowAttributes +might use a +larger, but compatible, +.PN xGetWindowAttributesReply +that contains additional attribute data at the end. +.NE +.PN _XReply +returns +.PN True +if it received a reply successfully or +.PN False +if it received any sort of error. +.LP +For a request with a reply that is not followed by variable-length +data, you write something like: +.LP +.Ds +.R +_XReply(display, (xReply *)&rep, 0, True); +*ret1 = rep.ret1; +*ret2 = rep.ret2; +*ret3 = rep.ret3; +\^... +UnlockDisplay(dpy); +SyncHandle(); +return (rep.ret4); +} +.De +If there is variable-length data after the reply, +change the +.PN True +to +.PN False , +and use the appropriate +.PN _XRead +function to read the variable-length data. +.LP +.sM +.FD 0 +_XRead(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + char *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead +function reads the specified number of bytes into data_return. +.LP +.sM +.FD 0 +_XRead16(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + short *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead16 +function reads the specified number of bytes, +unpacking them as 16-bit quantities, +into the specified array as shorts. +.LP +.sM +.FD 0 +_XRead32(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + long *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead32 +function reads the specified number of bytes, +unpacking them as 32-bit quantities, +into the specified array as longs. +.LP +.sM +.FD 0 +_XRead16Pad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + short *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XRead16Pad +function reads 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, +.PN _XRead16Pad +reads and discards up to two additional pad bytes. +.LP +.sM +.FD 0 +_XReadPad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^) + Display *\fIdisplay\fP\^; + char *\fIdata_return\fP\^; + long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIdata_return\fP 1i +Specifies the buffer. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +The +.PN _XReadPad +function reads the specified number of bytes into data_return. +If the number of bytes is not a multiple of four, +.PN _XReadPad +reads and discards up to three additional pad bytes. +.LP +Each protocol request is a little different. +For further information, +see the Xlib sources for examples. +.SH +Synchronous Calling +.LP +Each procedure should have a call, just before returning to the user, +to a macro called +.PN SyncHandle . +If synchronous mode is enabled (see +.PN XSynchronize ), +the request is sent immediately. +The library, however, waits until any error the procedure could generate +at the server has been handled. +.SH +Allocating and Deallocating Memory +.LP +To support the possible reentry of these procedures, +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 functions on many systems +are not protected against signals or other multithreaded uses. +The following analogies to standard I/O library functions +have been defined: +.TS +l l. +T{ +.PN Xmalloc () +T} T{ +Replaces +.PN malloc () +T} +T{ +.PN XFree () +T} T{ +Replaces +.PN free () +T} +T{ +.PN Xcalloc () +T} T{ +Replaces +.PN calloc () +T} +.TE +.LP +These should be used in place of any calls you would make to the normal +C library functions. +.LP +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 functions, which are performance critical). +The following function returns a scratch buffer for use within a +critical section: +.IN "_XAllocScratch" "" "@DEF@" +.sM +.FD 0 +char *_XAllocScratch(\^\fIdisplay\fP, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +This storage must only be used inside of a critical section of your +stub. The returned pointer cannot be assumed valid after any call +that might permit another thread to execute inside Xlib. For example, +the pointer cannot be assumed valid after any use of the +.PN GetReq +or +.PN Data +families of macros, +after any use of +.PN _XReply , +or after any use of the +.PN _XSend +or +.PN _XRead +families of functions. +.LP +.sp +The following function returns a scratch buffer for use across +critical sections: +.IN "_XAllocTemp" "" "@DEF@" +.sM +.FD 0 +char *_XAllocTemp(\^\fIdisplay\fP, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + unsigned long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fInbytes\fP 1i +Specifies the number of bytes required. +.LP +.eM +This storage can be used across calls that might permit another thread to +execute inside Xlib. The storage must be explicitly returned to Xlib. +The following function returns the storage: +.IN "_XFreeTemp" "" "@DEF@" +.sM +.FD 0 +void _XFreeTemp(\^\fIdisplay\fP, \fIbuf\fP, \fInbytes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char *\fIbuf\fP\^; +.br + unsigned long \fInbytes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIbuf\fP 1i +Specifies the buffer to return. +.IP \fInbytes\fP 1i +Specifies the size of the buffer. +.LP +.eM +You must pass back the same pointer and size that were returned by +.PN _XAllocTemp . +.SH +Portability Considerations +.LP +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 \fImust\fP 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 \fImust\fP 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. +.LP +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 +.PN CARD16 +in the protocol, be sure to declare it as +.PN unsigned +.PN int +and not as +.PN int . +(This, of course, does not apply to Booleans or enumerations.) +.LP +Similarly, +if any integer argument or return value is declared +.PN CARD32 +in the protocol, +declare it as an +.PN unsigned +.PN long +and not as +.PN int +or +.PN long . +This also goes for any internal variables that may +take on values larger than the maximum 16-bit +.PN unsigned +.PN int . +.LP +The library currently assumes that a +.PN char +is 8 bits, a +.PN short +is 16 bits, an +.PN int +is 16 or 32 bits, and a +.PN long +is 32 bits. +The +.PN 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. +.SH +Deriving the Correct Extension Opcode +.LP +The remaining problem a writer of an extension stub procedure 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. +.IP 1. 5 +Declare an array of pointers, _NFILE long (this is normally found +in +.hN stdio.h +and is the number of file descriptors supported on the system) +of type +.PN XExtCodes . +Make sure these are all initialized to NULL. +.IP 2. 5 +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 procedure for this display. +Call your initialization procedure and pass to it the display pointer. +.IP 3. 5 +Once in your initialization procedure, call +.PN 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 procedure would normally return a pointer to the +.PN XExtCodes +structure for this extension, which is what would normally +be found in your array of pointers. +.IP 4. 5 +After returning from your initialization procedure, +the stub can now continue normally, because it has its major opcode safely +in its hand in the +.PN XExtCodes +structure. +.bp |