appc

linux图形界面x liberary手册

.IP \(bu 5
A Boolean that indicates whether
.PN _XReply 
is to discard any additional bytes
beyond those it was told to read

<P>

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.

<P>

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. 

<P>

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

<P>

.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.

<P>

.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.

<P>

.eM
The
.PN _XRead
function reads the specified number of bytes into data_return.

<P>

.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.

<P>

.eM
The
.PN _XRead16
function reads the specified number of bytes,
unpacking them as 16-bit quantities,
into the specified array as shorts.

<P>

.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.

<P>

.eM
The
.PN _XRead32
function reads the specified number of bytes,
unpacking them as 32-bit quantities,
into the specified array as longs.

<P>

.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.

<P>

.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.

<P>

.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.

<P>

.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.

<P>

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

<P>

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

<P>

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

<P>

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

<P>

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.

<P>

.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.

<P>

.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.

<P>

.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.

<P>

.eM
You must pass back the same pointer and size that were returned by
.PN _XAllocTemp .
.SH
Portability Considerations

<P>

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.

<P>

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.)

<P>

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 .

<P>

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

<P>

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 
<B><TT>stdio.h</TT></B>
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