appc

linux图形界面x liberary手册

.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

<P>

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

<P>

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

<P>

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

<P>

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.

<P>

A few protocol requests take no arguments at all. 
Instead, they use the
.PN xReq 
structure in
<B><TT>X11/Xproto.h ,</TT></B>
which contains only a reqType and a length (and a pad byte).

<P>
 
If the protocol request requires a reply, 
then
<B><TT>X11/Xproto.h</TT></B>
also contains a reply structure typedef:

<P>

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

<P>

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

<P>

Only 
.PN GetWindowAttributes , 
.PN QueryFont , 
.PN QueryKeymap , 
and
.PN GetKeyboardControl 
have reply structures longer than 32 bytes in the core protocol.

<P>

A few protocol requests return replies that contain no data.  
<B><TT>X11/Xproto.h</TT></B>
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

<P>

An Xlib stub procedure should start like this:

<P>

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

<P>

.Ds 
.R
xDoSomethingReply rep;
.De 
.SH
Locking Data Structures

<P>

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

<P>

<!.IN "UnlockDisplay" "" "@DEF@">
.FD 0
UnlockDisplay(\fIdisplay\fP)
.br
      Display *\fIdisplay\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.

<P>

.eM
.SH
Sending the Protocol Request and Arguments

<P>

After the variable declarations, 
a stub procedure should call one of four macros defined in 
<B><TT>X11/Xlibint.h : </TT></B>
.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 
<B><TT>X11/Xproto.h</TT></B>
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.

<P>

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

<P>

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

<P>

.Ds
.R
GetResReq (DoSomething, rid, req);
.De
The rid argument is the 
.PN Pixmap , 
.PN Window , 
or other resource ID.

<P>

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.

<P>

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

<P>

.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

<P>

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.

<P>

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:

<P>

.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

<P>

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

<P>

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

<P>

If the protocol request has a reply, 
then call 
.PN _XReply 
after you have finished dealing with 
all the fixed 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.

<P>

.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