442
442
To look up a resource, use one of the following.
443
443
<blockquote><programlisting>
445
pointer LookupIDByType(id, rtype)
445
int dixLookupResourceByType(
449
pointer LookupIDByClass(id, classes)
452
int dixLookupResourceByClass(
453
459
</programlisting></blockquote>
454
LookupIDByType finds a resource with the given id and exact type.
455
LookupIDByClass finds a resource with the given id whose type is
456
included in any one of the specified classes.</para>
460
dixLookupResourceByType finds a resource with the given id and exact type.
461
dixLookupResourceByClass finds a resource with the given id whose type is
462
included in any one of the specified classes.
463
The client and access_mode must be provided to allow security extensions to
464
check if the client has the right privileges for the requested access.
465
The bitmask values defined in the dixaccess.h header are or'ed together
466
to define the requested access_mode.
469
480
Before getting bogged down in the interface details, an typical usage
470
481
example should establish the framework. Let's look at the
471
482
ClientStateCallback in dix/dispatch.c. The purpose of this particular
472
callback is to notify intereseted parties when a client's state
483
callback is to notify interested parties when a client's state
473
484
(initial, running, gone) changes. The callback is "created" in this
474
485
case by simply declaring a variable:
475
486
<blockquote><programlisting>
499
510
Now for the details.
500
511
<blockquote><programlisting>
502
Bool CreateCallbackList(pcbl, cbfuncs)
503
CallbackListPtr *pcbl;
504
CallbackFuncsPtr cbfuncs;
506
</programlisting></blockquote>
507
CreateCallbackList creates a callback list. We envision that this
508
function will be rarely used because the callback list is created
509
automatically (if it doesn't already exist) when the first call to
510
AddCallback is made on the list. The only reason to explicitly create
511
the callback list with this function is if you want to override the
512
implementation of some of the other operations on the list by passing
513
your own cbfuncs. You also lose something by explicit creation: you
514
introduce an order dependency during server startup because the list
515
must be created before any modules subscribe to it. Returns TRUE if
518
<blockquote><programlisting>
520
513
Bool AddCallback(pcbl, callback, subscriber_data)
521
514
CallbackListPtr *pcbl;
522
515
CallbackProcPtr callback;
595
588
There are a number of macros in Xserver/include/dix.h which
596
589
are useful to the extension writer. Ones of particular interest
597
590
are: REQUEST, REQUEST_SIZE_MATCH, REQUEST_AT_LEAST_SIZE,
598
REQUEST_FIXED_SIZE, LEGAL_NEW_RESOURCE, LOOKUP_DRAWABLE, VERIFY_GC, and
591
REQUEST_FIXED_SIZE, LEGAL_NEW_RESOURCE, and
599
592
VALIDATE_DRAWABLE_AND_GC. Useful byte swapping macros can be found
593
in Xserver/include/dix.h: WriteReplyToClient and WriteSwappedDataToClient; and
600
594
in Xserver/include/misc.h: lswapl, lswaps, LengthRestB, LengthRestS,
601
595
LengthRestL, SwapRestS, SwapRestL, swapl, swaps, cpswapl, and cpswaps.</para>
881
875
Similarly, the X server or an extension may need to wait for some timeout.
882
876
Early X releases implemented this functionality using block and wakeup handlers,
883
877
but this has been rewritten to use a general timer facilty, and the
884
internal screen saver facilties reimplemented to use Timers.
878
internal screen saver facilities reimplemented to use Timers.
885
879
These functions are TimerInit, TimerForce, TimerSet, TimerCheck, TimerCancel,
886
880
and TimerFree, as defined in Xserver/include/os.h. A callback function will be called
887
881
when the timer fires, along with the current time, and a user provided argument.
920
914
void TimerCancel(OsTimerPtr /* pTimer */)
922
void TimerFree(OSTimerPtr /* pTimer */)
916
void TimerFree(OsTimerPtr /* pTimer */)
923
917
</programlisting></blockquote>
926
TimerInit frees any exisiting timer entries. TimerForce forces a call to the timer's
920
TimerInit frees any existing timer entries. TimerForce forces a call to the timer's
927
921
callback function and returns true if the timer entry existed, else it returns false and
928
922
does not call the callback function. TimerCancel will cancel the specified timer.
929
923
TimerFree calls TimerCancel and frees the specified timer.
1188
1182
<title>Font Support</title>
1190
1184
In the sample server, fonts are encoded in disk files or fetched from the
1185
font server. The two fonts required by the server, <quote>fixed</quote>
1186
and <quote>cursor</quote> are commonly compiled into the font library.
1192
1187
For disk fonts, there is one file per font, with a file name like
1193
1188
"fixed.pcf". Font server fonts are read over the network using the
1194
1189
X Font Server Protocol. The disk directories containing disk fonts and
1202
1197
that format both through the X server and the Font server.
1205
With the incorporation of font-server based fonts and the Speedo donation
1206
from Bitstream, the font interfaces have been moved into a separate
1207
library, now called the Font Library (../fonts/lib). These routines are
1200
The code for processing fonts in different formats, as well as handling the
1201
metadata files for them on disk (such as <filename>fonts.dir</filename>) is
1202
located in the libXfont library, which is provided as a separately compiled
1203
module. These routines are
1208
1204
shared between the X server and the Font server, so instead of this document
1209
1205
specifying what you must implement, simply refer to the font
1210
1206
library interface specification for the details. All of the interface code to the Font
1215
1211
<title>Memory Management</title>
1217
1213
Memory management is based on functions in the C runtime library.
1218
Xalloc(), Xrealloc(), and Xfree() work just like malloc(), realloc(),
1219
and free(), except that you can pass a null pointer to Xrealloc() to
1220
have it allocate anew or pass a null pointer to Xfree() and nothing
1221
will happen. The versions in the sample server also do some checking
1222
that is useful for debugging. Consult a C runtime library reference
1214
Xalloc(), Xrealloc(), and Xfree() are deprecated aliases for malloc(),
1215
realloc(), and free(), and you should simply call the C library functions
1216
directly. Consult a C runtime library reference
1223
1217
manual for more details.
1226
The macros ALLOCATE_LOCAL and DEALLOCATE_LOCAL are provided in
1227
Xserver/include/os.h. These are useful if your compiler supports
1228
alloca() (or some method of allocating memory from the stack); and are
1229
defined appropriately on systems which support it.
1232
1220
Treat memory allocation carefully in your implementation. Memory
1233
1221
leaks can be very hard to find and are frustrating to a user. An X
1234
1222
server could be running for days or weeks without being reset, just
1360
1348
The sample server implementation for these routines
1361
is in Xserver/os/util.c.
1365
<title>Idiom Support</title>
1367
The DBE specification introduces the notion of idioms, which are
1368
groups of X requests which can be executed more efficiently when taken
1369
as a whole compared to being performed individually and sequentially.
1370
This following server internal support to allows DBE
1371
implementations, as well as other parts of the server,
1372
to do idiom processing.
1375
<blockquote><programlisting>
1377
xReqPtr PeekNextRequest(xReqPtr req, ClientPtr client, Bool readmore)
1378
</programlisting></blockquote>
1379
If req is NULL, the return value will be a pointer to the start of the
1380
complete request that follows the one currently being executed for the
1381
client. If req is not NULL, the function assumes that req is a
1382
pointer to a request in the client's request buffer, and the return
1383
value will be a pointer to the the start of the complete request that
1384
follows req. If the complete request is not available, the function
1385
returns NULL; pointers to partial requests will never be returned. If
1386
(and only if) readmore is TRUE, PeekNextRequest should try to read an
1387
additional request from the client if one is not already available in
1388
the client's request buffer. If PeekNextRequest reads more data into
1389
the request buffer, it should not move or change the existing data.
1392
<blockquote><programlisting>
1394
void SkipRequests(xReqPtr req, ClientPtr client, int numskipped)
1395
</programlisting></blockquote>
1396
The requests for the client up to and including the one specified by
1397
req will be skipped. numskipped must be the number of requests being
1398
skipped. Normal request processing will resume with the request that
1399
follows req. The caller must not have modified the contents of the
1400
request buffer in any way (e.g., by doing byte swapping in place).
1403
Additionally, two macros in os.h operate on the xReq
1404
pointer returned by PeekNextRequest:
1405
<blockquote><programlisting>
1407
int ReqLen(xReqPtr req, ClientPtr client)
1408
</programlisting></blockquote>
1409
The value of ReqLen is the request length in bytes of the given xReq.
1410
<blockquote><programlisting>
1412
otherReqTypePtr CastxReq(xReq *req, otherReqTypePtr)
1413
</programlisting></blockquote>
1414
The value of CastxReq is the conversion of the given request pointer
1415
to an otherReqTypePtr (which should be a pointer to a protocol
1416
structure type). Only those fields which come after the length field
1417
of otherReqType may be accessed via the returned pointer.
1420
Thus the first two fields of a request, reqType and data, can be
1421
accessed directly using the xReq * returned by PeekNextRequest. The
1422
next field, the length, can be accessed with ReqLen. Fields beyond
1423
that can be accessed with CastxReq. This complexity was necessary
1424
because of the reencoding of core protocol that can happen due to the
1425
BigRequests extension.
1349
is in Xserver/os/log.c along with other routines for logging messages.
1755
1675
an extension is needed to provide for a client interface to a device.
1758
<blockquote><programlisting>
1760
void RegisterPointerDevice(device)
1762
</programlisting></blockquote>
1763
RegisterPointerDevice is a DIX routine that your DDX code calls that
1764
makes that device the main pointing device.
1765
This routine is called once upon initialization and cannot be called again.
1768
<blockquote><programlisting>
1770
void RegisterKeyboardDevice(device)
1772
</programlisting></blockquote>
1773
RegisterKeyboardDevice makes the given device the main keyboard.
1774
This routine is called once upon initialization and cannot be called again.
1777
1678
The following DIX
1778
1679
procedures return the specified DevicePtr. They may or may not be useful
1779
1680
to DDX implementors.
3053
2954
pScreen->SourceValidate(pDrawable, x, y, width, height)
3054
2955
DrawablePtr pDrawable;
3055
2956
int x, y, width, height;
2957
unsigned int subWindowMode;
3057
2959
</programlisting></blockquote>
3058
2960
SourceValidate should be called by CopyArea/CopyPlane primitives when
3059
the source drawable is not the same as the destination, and the
3060
SourceValidate function pointer in the screen is non-null. If you know that
2961
the SourceValidate function pointer in the screen is non-null. If you know that
3061
2962
you will never need SourceValidate, you can avoid this check. Currently,
3062
2963
SourceValidate is used by the mi software cursor code to remove the cursor
3063
2964
from the screen when the source rectangle overlaps the cursor position.
3064
2965
x,y,width,height describe the source rectangle (source relative, that is)
3065
for the copy operation.</para>
2966
for the copy operation. subWindowMode comes from the GC or source Picture.
3067
2969
<blockquote><programlisting>
4854
4756
the same value for <type>size</type> or the server will abort.</para>
4857
To request private space and have the server manage the key, use
4759
To request per-screen private space in an object, use
4858
4760
<blockquote><programlisting>
4859
DevPrivateKey dixCreatePrivateKey(DevPrivateType type, unsigned size);
4761
Bool dixRegisterScreenPrivateKey(DevScreenPrivateKey key, ScreenPtr pScreen, DevPrivateType type, unsigned size);
4860
4762
</programlisting></blockquote>
4861
4763
The <parameter>type</parameter> and <parameter>size</parameter> arguments are
4862
4764
the same as those to <function>dixRegisterPrivateKey</function> but this
4863
function allocates a <type>DevPrivateKeyRec</type> and returns a pointer to it
4864
instead of requiring the caller to pass a pointer to an existing structure.
4865
The server will free it automatically when the privates system is restarted
4866
at server reset time.</para>
4765
function ensures the given <parameter>key</parameter> exists on objects of
4766
the specified type with distinct storage for the given
4767
<parameter>pScreen</parameter>. The key is usable on ScreenPrivate variants
4768
that are otherwise equivalent to the following Private functions.</para>
4869
4771
To attach a piece of private data to an object, use:
5112
5014
<row><entry><function>ListInstalledColormaps</function></entry><entry><literal>ddx</literal></entry><entry><para>Screen</para></entry></row>
5113
5015
<row><entry><function>LookupKeyboardDevice</function></entry><entry><literal>dix</literal></entry><entry><para></para></entry></row>
5114
5016
<row><entry><function>LookupPointerDevice</function></entry><entry><literal>dix</literal></entry><entry><para></para></entry></row>
5115
<row><entry><function>ModifyPixmapheader</function></entry><entry><literal>mi</literal></entry><entry><para>Screen</para></entry></row>
5017
<row><entry><function>ModifyPixmapHeader</function></entry><entry><literal>mi</literal></entry><entry><para>Screen</para></entry></row>
5116
5018
<row><entry><function>NextAvailableClient</function></entry><entry><literal>dix</literal></entry><entry><para></para></entry></row>
5117
5019
<row><entry><function>OsInit</function></entry><entry><literal>os</literal></entry><entry><para></para></entry></row>
5118
5020
<row><entry><function>PaintWindowBackground</function></entry><entry><literal>mi</literal></entry><entry><para>Window</para></entry></row>
added
removed
doc/xml/Xserver-spec.xml
