home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / AppC < prev    next >
Encoding:
Text File  |  1991-07-30  |  57.2 KB  |  2,008 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBAppendix C\fP\s-1
  5.  
  6. \s+1\fBExtensions\fP\s-1
  7. .sp 2
  8. .na
  9. .LP
  10. .XS
  11. Appendix C: Extensions
  12. .XE
  13. Because X can evolve by extensions to the core protocol, 
  14. it is important that extensions not be perceived as second class citizens.
  15. At some point, 
  16. your favorite extensions may be adopted as additional parts of the 
  17. X Standard.
  18. .LP
  19. Therefore, there should be little to distinguish the use of an extension from 
  20. that of the core protocol.
  21. To avoid having to initialize extensions explicitly in application programs, 
  22. it is also important that extensions perform ``lazy evaluations'' 
  23. and automatically initialize themselves when called for the first time.  
  24. .LP
  25. This appendix describes techniques for writing extensions to Xlib that will
  26. run at essentially the same performance as the core protocol requests.
  27. .NT
  28. It is expected that a given extension to X consists of multiple
  29. requests.
  30. Defining ten new features as ten separate extensions is a bad practice.
  31. Rather, they should be packaged into a single extension
  32. and should use minor opcodes to distinguish the requests.
  33. .NE
  34. .LP
  35. The symbols and macros used for writing stubs to Xlib are listed in
  36. .IN "Files" "<X11/Xlibint.h>"
  37. .Pn < X11/Xlibint.h >.
  38. .SH
  39. Basic Protocol Support Routines
  40. .LP
  41. The basic protocol requests for extensions are 
  42. .PN XQueryExtension
  43. and
  44. .PN XListExtensions .
  45. .IN "XQueryExtension" "" "@DEF@"
  46. .\" Start marker code here
  47. .FD 0
  48. Bool XQueryExtension(\^\fIdisplay\fP, \fIname\fP, \fImajor_opcode_return\fP, \
  49. \fIfirst_event_return\fP, \fIfirst_error_return\fP\^)
  50. .br
  51.       Display *\fIdisplay\fP\^;
  52. .br
  53.       char *\fIname;\fP\^
  54. .br
  55.       int *\fImajor_opcode_return\fP\^;
  56. .br
  57.       int *\fIfirst_event_return\fP\^;
  58. .br
  59.       int *\fIfirst_error_return\fP\^;
  60. .FN
  61. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  62. .IP \fIdisplay\fP 1i
  63. Specifies the connection to the X server.
  64. .IP \fIname\fP 1i
  65. Specifies the extension name.
  66. .IP \fImajor_opcode_return\fP 1i
  67. Returns the major opcode.
  68. .IP \fIfirst_event_return\fP 1i
  69. Returns the first event code, if any.
  70. .IP \fI\fP 1i
  71. Specifies the extension list.
  72. .\" End marker code here
  73. .LP
  74. .PN XQueryExtension
  75. determines if the named extension is present.  
  76. If the extension is not present,
  77. .PN False
  78. is returned;
  79. otherwise
  80. .PN True
  81. is returned.
  82. If the extension is present,
  83. the major opcode for the extension is returned to
  84. major_opcode_return;
  85. otherwise,
  86. zero is returned.
  87. Any minor opcode and the request formats are specific to the
  88. extension.  
  89. If the extension involves additional event types, 
  90. the base event type code is returned to first_event_return;
  91. otherwise, 
  92. zero is returned.  
  93. The format of the events is specific to the extension.  
  94. If the extension involves additional error codes, 
  95. the base error code is returned to first_error_return;
  96. otherwise, 
  97. zero is returned.  
  98. The format of additional data in the errors is specific to the extension.
  99. .LP
  100. If the extension name is not in the Host Portable Character Encoding
  101. the result is implementation dependent.
  102. Case matters; the strings \fIthing\fP, \fIThing\fP, and \fIthinG\fP 
  103. are all considered different names.
  104. .IN "XListExtensions" "" "@DEF@"
  105. .\" Start marker code here
  106. .FD 0
  107. char **XListExtensions(\^\fIdisplay\fP, \fInextensions_return\fP\^)
  108. .br
  109.       Display *\fIdisplay\fP\^;
  110. .br
  111.       int *\fInextensions_return\fP\^;
  112. .FN
  113. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  114. .IP \fIdisplay\fP 1i
  115. Specifies the connection to the X server.
  116. .IP \fInextensions_return\fP 1i
  117. Returns the number of extensions listed.
  118. .\" End marker code here
  119. .LP
  120. .PN XListExtensions   
  121. returns a list of all extensions supported by the server.
  122. If the data returned by the server is in the Latin Portable Character Encoding,
  123. then the returned strings are in the Host Portable Character Encoding.
  124. Otherwise, the result is implementation dependent.
  125. .IN "XFreeExtensionList" "" "@DEF@"
  126. .\" Start marker code here
  127. .FD 0
  128. XFreeExtensionList(\^\fIlist\fP\^)
  129. .br
  130.       char **\fIlist\fP\^;
  131. .FN
  132. .IP \fIlist\fP 1i
  133. Specifies the list of extension names.
  134. .\" End marker code here
  135. .LP
  136. .PN XFreeExtensionList
  137. frees the memory allocated by 
  138. .PN XListExtensions .
  139. .SH
  140. Hooking into Xlib 
  141. .LP
  142. These functions allow you to hook into the library.  
  143. They are not normally used by application programmers but are used 
  144. by people who need to extend the core X protocol and
  145. the X library interface.
  146. The functions, which generate protocol requests for X, are typically
  147. called stubs.
  148. .LP
  149. In extensions, stubs first should check to see if they have initialized 
  150. themselves on a connection.
  151. If they have not, they then should call 
  152. .PN XInitExtension 
  153. to attempt to initialize themselves on the connection.
  154. .LP
  155. If the extension needs to be informed of GC/font allocation or
  156. deallocation or if the extension defines new event types, 
  157. the functions described here allow the extension to be 
  158. called when these events occur.
  159. .LP
  160. The
  161. .PN XExtCodes
  162. structure returns the information from 
  163. .PN XInitExtension 
  164. and is defined in
  165. .IN "Files" "<X11/Xlib.h>"
  166. .Pn < X11/Xlib.h >: 
  167. .LP
  168. .IN "XExtCodes" "" "@DEF@"
  169. .\" Start marker code here
  170. .Ds 0
  171. .TA .5i 3i
  172. .ta .5i 3i
  173. typedef struct _XExtCodes {    /* public to extension, cannot be changed */
  174.     int extension;    /* extension number */
  175.     int major_opcode;    /* major op-code assigned by server */
  176.     int first_event;    /* first event number for the extension */
  177.     int first_error;    /* first error number for the extension */
  178. } XExtCodes;
  179. .De
  180. .\" End marker code here
  181. .LP
  182. .IN "XInitExtension" "" "@DEF@"
  183. .\" Start marker code here
  184. .FD 0
  185. XExtCodes *XInitExtension(\^\fIdisplay\fP, \fIname\fP\^)
  186. .br
  187.       Display *\fIdisplay\fP\^;
  188. .br
  189.       char *\fIname\fP\^;
  190. .FN
  191. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  192. .IP \fIdisplay\fP 1i
  193. Specifies the connection to the X server.
  194. .IP \fIname\fP 1i
  195. Specifies the extension name.
  196. .\" End marker code here
  197. .LP
  198. .PN XInitExtension
  199. determines if the named extension exists. 
  200. Then, it allocates storage for maintaining the 
  201. information about the extension on the connection, 
  202. chains this onto the extension list for the connection,
  203. and returns the information the stub implementor will need to access
  204. the extension.
  205. If the extension does not exist,
  206. .PN XInitExtension
  207. returns NULL.
  208. .LP
  209. If the extension name is not in the Host Portable Character Encoding
  210. the result is implementation dependent.
  211. Case matters; the strings \fIthing\fP, \fIThing\fP, and \fIthinG\fP 
  212. are all considered different names.
  213. .LP
  214. The extension number in the 
  215. .PN XExtCodes 
  216. structure is
  217. needed in the other calls that follow.  
  218. This extension number is unique only to a single connection.
  219. .LP
  220. .IN "XAddExtension" "" "@DEF@"
  221. .\" Start marker code here
  222. .FD 0
  223. XExtCodes *XAddExtension\^(\^\fIdisplay\fP\^)
  224. .br
  225.         Display *\fIdisplay\fP\^;
  226. .FN
  227. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  228. .IP \fIdisplay\fP 1i
  229. Specifies the connection to the X server.
  230. .\" End marker code here
  231. .LP
  232. For local Xlib extensions,
  233. .PN XAddExtension
  234. allocates the
  235. .PN XExtCodes
  236. structure, bumps the extension number count,
  237. and chains the extension onto the extension list.
  238. (This permits extensions to Xlib without requiring server extensions.)
  239. .SH
  240. Hooks into the Library
  241. .LP
  242. These functions allow you to define procedures that are to be
  243. called when various circumstances occur.
  244. The procedures include the creation of a new GC for a connection,
  245. the copying of a GC, the freeing of a GC, the creating and freeing of fonts,
  246. the conversion of events defined by extensions to and from wire
  247. format, and the handling of errors.
  248. .LP
  249. All of these functions return the previous routine defined for this
  250. extension.
  251. .IN "XESetCloseDisplay" "" "@DEF@"
  252. .\" Start marker code here
  253. .FD 0
  254. int (*XESetCloseDisplay(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  255. .br
  256.       Display *\fIdisplay\fP\^;
  257. .br
  258.       int \fIextension\fP\^;
  259. .br
  260.       int (\^*\fIproc\fP\^)(\^);
  261. .FN
  262. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  263. .IP \fIdisplay\fP 1i
  264. Specifies the connection to the X server.
  265. .IP \fIextension\fP 1i
  266. Specifies the extension number.
  267. .IP \fIproc\fP 1i
  268. Specifies the routine to call when the display is closed.
  269. .\" End marker code here
  270. .LP
  271. You use this procedure to define a procedure to be called whenever
  272. .PN XCloseDisplay 
  273. is called.  
  274. This procedure returns any previously defined procedure, usually NULL.
  275. .LP
  276. When 
  277. .PN XCloseDisplay 
  278. is called, 
  279. your routine is called 
  280. with these arguments:
  281. .LP
  282. .\" Start marker code here
  283. .Ds 0
  284. .TA .5i 3i
  285. .ta .5i 3i
  286. .R
  287. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP\^)
  288.     Display *\fIdisplay\fP\^;
  289.     XExtCodes *\fIcodes\fP\^;
  290. .De
  291. .\" End marker code here
  292. .LP
  293. .IN "XESetCreateGC" "" "@DEF@"
  294. .\" Start marker code here
  295. .FD 0
  296. int (*XESetCreateGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  297. .br
  298.       Display *\fIdisplay\fP\^;
  299. .br
  300.       int \fIextension\fP\^;
  301. .br
  302.       int (\^*\fIproc\fP\^)(\^);
  303. .FN
  304. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  305. .IP \fIdisplay\fP 1i
  306. Specifies the connection to the X server.
  307. .IP \fIextension\fP 1i
  308. Specifies the extension number.
  309. .IP \fIproc\fP 1i
  310. Specifies the routine to call when a GC is closed.
  311. .\" End marker code here
  312. .LP
  313. You use this procedure to define a procedure to be called whenever
  314. a new GC is created.  
  315. This procedure returns any previously defined procedure, usually NULL.
  316. .LP
  317. When a GC is created, 
  318. your routine is called with these arguments:
  319. .LP
  320. .\" Start marker code here
  321. .Ds 0
  322. .TA .5i 3i
  323. .ta .5i 3i
  324. .R
  325. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
  326.     Display *\fIdisplay\fP\^;
  327.     GC \fIgc\fP\^;
  328.     XExtCodes *\fIcodes\fP\^;
  329. .De
  330. .\" End marker code here
  331. .LP
  332. .IN "XESetCopyGC" "" "@DEF@"
  333. .\" Start marker code here
  334. .FD 0
  335. int (*XESetCopyGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  336. .br
  337.       Display *\fIdisplay\fP\^;
  338. .br
  339.       int \fIextension\fP\^;
  340. .br
  341.       int (\^*\fIproc\fP\^)(\^);
  342. .FN
  343. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  344. .IP \fIdisplay\fP 1i
  345. Specifies the connection to the X server.
  346. .IP \fIextension\fP 1i
  347. Specifies the extension number.
  348. .IP \fIproc\fP 1i
  349. Specifies the routine to call when GC components are copied.
  350. .\" End marker code here
  351. .LP
  352. You use this procedure to define a procedure to be called whenever
  353. a GC is copied.  
  354. This procedure returns any previously defined procedure, usually NULL.
  355. .LP
  356. When a GC is copied, 
  357. your routine is called with these arguments:
  358. .LP
  359. .\" Start marker code here
  360. .Ds 0
  361. .TA .5i 3i
  362. .ta .5i 3i
  363. .R
  364. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
  365.     Display *\fIdisplay\fP\^;
  366.     GC \fIgc\fP\^;
  367.     XExtCodes *\fIcodes\fP\^;
  368. .De
  369. .\" End marker code here
  370. .LP
  371. .IN "XESetFreeGC" "" "@DEF@"
  372. .\" Start marker code here
  373. .FD 0
  374. int (*XESetFreeGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc)\fP\^)(\^)
  375. .br
  376.       Display *\fIdisplay\fP\^;
  377. .br
  378.       int \fIextension\fP\^;
  379. .br
  380.       int (\^*\fIproc\fP\^)(\^);
  381. .FN
  382. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  383. .IP \fIdisplay\fP 1i
  384. Specifies the connection to the X server.
  385. .IP \fIextension\fP 1i
  386. Specifies the extension number.
  387. .IP \fIproc\fP 1i
  388. Specifies the routine to call when a GC is freed.
  389. .\" End marker code here
  390. .LP
  391. You use this procedure to define a procedure to be called whenever
  392. a GC is freed.  
  393. This procedure returns any previously defined procedure, usually NULL.
  394. .LP
  395. When a GC is freed, 
  396. your routine is called with these arguments:
  397. .LP
  398. .\" Start marker code here
  399. .Ds 0
  400. .TA .5i 3i
  401. .ta .5i 3i
  402. .R
  403. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
  404.     Display *\fIdisplay\fP\^;
  405.     GC \fIgc\fP\^;
  406.     XExtCodes *\fIcodes\fP\^;
  407. .De
  408. .\" End marker code here
  409. .LP
  410. .IN "XESetCreateFont" "" "@DEF@"
  411. .\" Start marker code here
  412. .FD 0
  413. int (*XESetCreateFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP))(\^)
  414. .br
  415.       Display *\fIdisplay\fP\^;
  416. .br
  417.       int \fIextension\fP\^;
  418. .br
  419.       int (\^*\fIproc\fP\^)(\^);
  420. .FN
  421. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  422. .IP \fIdisplay\fP 1i
  423. Specifies the connection to the X server.
  424. .IP \fIextension\fP 1i
  425. Specifies the extension number.
  426. .IP \fIproc\fP 1i
  427. Specifies the routine to call when a font is created.
  428. .\" End marker code here
  429. .LP
  430. You use this procedure to define a procedure to be called whenever
  431. .PN XLoadQueryFont 
  432. and
  433. .PN XQueryFont
  434. are called.  
  435. This procedure returns any previously defined procedure, usually NULL.
  436. .LP
  437. When 
  438. .PN XLoadQueryFont 
  439. or
  440. .PN XQueryFont
  441. is called, 
  442. your routine is called with these arguments:
  443. .LP
  444. .\" Start marker code here
  445. .Ds 0
  446. .TA .5i 3i
  447. .ta .5i 3i
  448. .R
  449. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^)
  450.     Display *\fIdisplay\fP\^;
  451.     XFontStruct *\fIfs\fP\^;
  452.     XExtCodes *\fIcodes\fP\^;
  453. .De
  454. .\" End marker code here
  455. .LP
  456. .IN "XESetFreeFont" "" "@DEF@"
  457. .\" Start marker code here
  458. .FD 0
  459. int (*XESetFreeFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  460. .br
  461.       Display *\fIdisplay\fP\^;
  462. .br
  463.       int \fIextension\fP\^;
  464. .br
  465.       int (\^*\fIproc\fP)(\^);
  466. .FN
  467. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  468. .IP \fIdisplay\fP 1i
  469. Specifies the connection to the X server.
  470. .IP \fIextension\fP 1i
  471. Specifies the extension number.
  472. .IP \fIproc\fP 1i
  473. Specifies the routine to call when a font is freed.
  474. .\" End marker code here
  475. .LP
  476. You use this procedure to define a procedure to be called whenever
  477. .PN XFreeFont 
  478. is called.  
  479. This procedure returns any previously defined procedure, usually NULL.
  480. .LP
  481. When 
  482. .PN XFreeFont 
  483. is called, your routine is called with these arguments:
  484. .LP
  485. .\" Start marker code here
  486. .Ds 0
  487. .TA .5i 3i
  488. .ta .5i 3i
  489. .R
  490. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^)
  491.     Display *\fIdisplay\fP\^;
  492.     XFontStruct *\fIfs\fP\^;
  493.     XExtCodes *\fIcodes\fP\^;
  494. .De
  495. .\" End marker code here
  496. .LP
  497. The next two functions allow you to define new events to the library.
  498. An 
  499. .PN XEvent
  500. structure always has a type code (type int) as the first component.  This
  501. uniquely identifies what kind of event it is.  The second component is
  502. always the serial number (type unsigned long) of the last request processed
  503. by the server.  The third component is always a boolean (type Bool) indicating
  504. whether the event came from a
  505. .PN SendEvent
  506. protocol request.  The fourth component is always a pointer to the display
  507. the event was read from.  The fifth component is always a resource ID of
  508. one kind or another, usually a window, carefully selected to be useful to
  509. toolkit dispatchers.  The fifth component should always exist, even if
  510. the event does not have a natural ``destination''; if there is no value
  511. from the protocol to put in this component, initialize it to zero.
  512. .NT
  513. There is an implementation limit such that your host event
  514. structure size cannot be bigger than the size of the
  515. .PN XEvent 
  516. union of structures.
  517. There also is no way to guarantee that more than 24 elements or 96 characters
  518. in the structure will be fully portable between machines.
  519. .NE
  520. .IN "XESetWireToEvent" "" "@DEF@"
  521. .\" Start marker code here
  522. .FD 0
  523. int (*XESetWireToEvent(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^)
  524. .br
  525.       Display *\fIdisplay\fP\^;
  526. .br
  527.       int \fIevent_number\fP\^;
  528. .br
  529.       Status (\^*\fIproc\fP\^)(\^);
  530. .FN
  531. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  532. .IP \fIdisplay\fP 1i
  533. Specifies the connection to the X server.
  534. .IP \fIevent_number\fP 1i
  535. Specifies the event code.
  536. .IP \fIproc\fP 1i
  537. Specifies the routine to call when converting an event.
  538. .\" End marker code here
  539. .LP
  540. You use this procedure to define a procedure to be called when an event
  541. needs to be converted from wire format 
  542. .Pn ( xEvent )
  543. to host format 
  544. .Pn ( XEvent ).
  545. The event number defines which protocol event number to install a
  546. conversion routine for.
  547. This procedure returns any previously defined procedure.
  548. .NT
  549. You can replace a core event conversion routine with one
  550. of your own, although this is not encouraged.
  551. It would, however, allow you to intercept a core event 
  552. and modify it before being placed in the queue or otherwise examined.
  553. .NE
  554. When Xlib needs to convert an event from wire format to host
  555. format, your routine is called with these arguments:
  556. .LP
  557. .\" Start marker code here
  558. .Ds 0
  559. .TA .5i 3i
  560. .ta .5i 3i
  561. .R
  562. Status (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^)
  563.     Display *\fIdisplay\fP\^;
  564.     XEvent *\fIre\fP\^;
  565.     xEvent *\fIevent\fP\^;
  566. .De
  567. .\" End marker code here
  568. .LP
  569. Your routine must return status to indicate if the conversion succeeded.
  570. The re argument is a pointer to where the host format event should be stored,
  571. and the event argument is the 32-byte wire event structure.
  572. In the 
  573. .PN XEvent 
  574. structure you are creating, 
  575. you must fill in the five required members of the event structure.
  576. You should fill in the type member with the type specified for the 
  577. .PN xEvent 
  578. structure.
  579. You should copy all other members from the 
  580. .PN xEvent 
  581. structure (wire format) to the
  582. .PN XEvent 
  583. structure (host format).
  584. Your conversion routine should return 
  585. .PN True
  586. if the event should be placed in the queue or
  587. .PN False
  588. if it should not be placed in the queue.
  589. .LP
  590. To initialize the serial number component of the event, call
  591. .PN _XSetLastRequestRead
  592. with the event and use the return value.
  593. .LP
  594. .IN "_XSetLastRequestRead" "" "@DEF@"
  595. .\" Start marker code here
  596. .FD 0
  597. unsigned long _XSetLastRequestRead(\^\fIdisplay\fP, \fIrep\fP\^)
  598. .br
  599.       Display *\fIdisplay\fP\^;
  600. .br
  601.       xGenericReply *\fIrep\fP\^;
  602. .FN
  603. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  604. .IP \fIdisplay\fP 1i
  605. Specifies the connection to the X server.
  606. .IP \fIrep\fP 1i
  607. Specifies the wire event structure.
  608. .\" End marker code here
  609. .LP
  610. This function computes and returns a complete serial number from the partial
  611. serial number in the event.
  612. .sp
  613. .LP
  614. .IN "XESetEventToWire" "" "@DEF@"
  615. .\" Start marker code here
  616. .FD 0
  617. Status (*XESetEventToWire(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^)
  618. .br
  619.       Display *\fIdisplay\fP\^;
  620. .br
  621.       int \fIevent_number\fP\^;
  622. .br
  623.       int (\^*\fIproc\fP\^)(\^);
  624. .FN
  625. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  626. .IP \fIdisplay\fP 1i
  627. Specifies the connection to the X server.
  628. .IP \fIevent_number\fP 1i
  629. Specifies the event code.
  630. .IP \fIproc\fP 1i
  631. Specifies the routine to call when converting an event.
  632. .\" End marker code here
  633. .LP
  634. You use this procedure to define a procedure to be called when an event
  635. needs to be converted from host format
  636. .Pn ( XEvent ) 
  637. to wire format
  638. .Pn ( xEvent )
  639. form.  
  640. The event number defines which protocol event number to install a
  641. conversion routine for.
  642. This procedure returns any previously defined procedure.
  643. It returns zero if the conversion fails or nonzero otherwise.
  644. .NT
  645. You can replace a core event conversion routine with one
  646. of your own, although this is not encouraged.  
  647. It would, however, allow you to intercept a core event 
  648. and modify it before being sent to another client.
  649. .NE
  650. When Xlib needs to convert an event from host format to wire format, 
  651. your routine is called with these arguments:
  652. .LP
  653. .\" Start marker code here
  654. .Ds 0
  655. .TA .5i 3i
  656. .ta .5i 3i
  657. .R
  658. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^)
  659.     Display *\fIdisplay\fP\^;
  660.     XEvent *\fIre\fP\^;
  661.     xEvent *\fIevent\fP\^;
  662. .De
  663. .\" End marker code here
  664. .LP
  665. The re argument is a pointer to the host format event,
  666. and the event argument is a pointer to where the 32-byte wire event 
  667. structure should be stored.
  668. You should fill in the type with the type from the 
  669. .PN XEvent 
  670. structure.
  671. All other members then should be copied from the host format to the 
  672. .PN xEvent 
  673. structure.
  674. .IN "XESetWireToError" "" "@DEF@"
  675. .\" Start marker code here
  676. .FD 0
  677. Bool (*XESetWireToError(\^\fIdisplay\fP, \fIerror_number\fP, \fIproc\fP\^)(\^)
  678. .br
  679.       Display *\fIdisplay\fP\^;
  680. .br
  681.       int \fIerror_number\fP\^;
  682. .br
  683.       Bool (\^*\fIproc\fP\^)(\^);
  684. .FN
  685. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  686. .IP \fIdisplay\fP 1i
  687. Specifies the connection to the X server.
  688. .IP \fIerror_number\fP 1i
  689. Specifies the error code.
  690. .IP \fIproc\fP 1i
  691. Specifies the routine to call when an error is received.
  692. .\" End marker code here
  693. .LP
  694. This function defines a procedure to be called when an extension
  695. error needs to be converted from wire format to host format.
  696. The error number defines which protocol error code to install
  697. the conversion routine for.
  698. This procedure returns any previously defined procedure.
  699. .LP
  700. Use this function for extension errors that contain additional error values
  701. beyond those in a core X error, when multiple wire errors must be combined
  702. into a single Xlib error, or when it is necessary to intercept an
  703. X error before it is otherwise examined.
  704. .LP
  705. When Xlib needs to convert an error from wire format to host format, the
  706. routine is called with these arguments:
  707. .LP
  708. .\" Start marker code here
  709. .Ds 0
  710. .TA .5i 3i
  711. .ta .5i 3i
  712. .R
  713. Bool (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIhe\fP, \fIwe\fP\^)
  714.     Display *\fIdisplay\fP\^;
  715.     XErrorEvent *\fIhe\fP\^;
  716.     xError *\fIwe\fP\^;
  717. .De
  718. .\" End marker code here
  719. .LP
  720. The he argument is a pointer to where the host format error should be stored.
  721. The structure pointed at by he is guaranteed to be as large as an
  722. .PN XEvent
  723. structure, and so can be cast to a type larger than an
  724. .PN XErrorEvent ,
  725. in order to store additional values.
  726. If the error is to be completely ignored by Xlib
  727. (for example, several protocol error structures will be combined into
  728. one Xlib error),
  729. then the function should return
  730. .PN False ;
  731. otherwise it should return
  732. .PN True .
  733. .IN "XESetError" "" "@DEF@"
  734. .\" Start marker code here
  735. .FD 0
  736. int (*XESetError(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  737. .br
  738.       Display *\fIdisplay\fP\^;
  739. .br
  740.       int \fIextension\fP\^;
  741. .br
  742.       int (\^*\fIproc\fP\^)(\^);
  743. .FN
  744. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  745. .IP \fIdisplay\fP 1i
  746. Specifies the connection to the X server.
  747. .IP \fIextension\fP 1i
  748. Specifies the extension number.
  749. .IP \fIproc\fP 1i
  750. Specifies the routine to call when an error is received.
  751. .\" End marker code here
  752. .LP
  753. Inside Xlib, there are times that you may want to suppress the
  754. calling of the external error handling when an error occurs.
  755. This allows status to be returned on a call at the cost of the call
  756. being synchronous (though most such routines are query operations, in any
  757. case, and are typically programmed to be synchronous).
  758. .LP
  759. When Xlib detects a protocol error in 
  760. .PN _XReply , 
  761. it calls your procedure with these arguments:
  762. .LP
  763. .\" Start marker code here
  764. .Ds 0
  765. .TA .5i 3i
  766. .ta .5i 3i
  767. .R
  768. int (*\fIproc\fP\^)(\fIdisplay\fP, \fIerr\fP, \fIcodes\fP, \fIret_code\fP\^)
  769.     Display *\fIdisplay\fP\^;
  770.     xError *\fIerr\fP\^;
  771.     XExtCodes *\fIcodes\fP\^;
  772.     int *\fIret_code\fP\^;
  773. .De
  774. .\" End marker code here
  775. .LP
  776. The err argument is a pointer to the 32-byte wire format error.
  777. The codes argument is a pointer to the extension codes structure.
  778. The ret_code argument is the return code you may want 
  779. .PN _XReply 
  780. returned to.
  781. .LP
  782. If your routine returns a zero value, 
  783. the error is not suppressed, and 
  784. the client's error handler is called.
  785. (For further information, see section 11.8.2.)
  786. If your routine returns nonzero, 
  787. the error is suppressed, and 
  788. .PN _XReply 
  789. returns the value of ret_code.
  790. .IN "XESetErrorString" "" "@DEF@"
  791. .\" Start marker code here
  792. .FD 0
  793. char  *(*XESetErrorString(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  794. .br
  795.       Display *\fIdisplay\fP\^;
  796. .br
  797.       int \fIextension\fP\^;
  798. .br
  799.       char *(\^*\fIproc\fP\^)(\^);
  800. .FN
  801. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  802. .IP \fIdisplay\fP 1i
  803. Specifies the connection to the X server.
  804. .IP \fIextension\fP 1i
  805. Specifies the extension number.
  806. .IP \fIproc\fP 1i
  807. Specifies the routine to call to obtain an error string.
  808. .\" End marker code here
  809. .LP
  810. The 
  811. .PN XGetErrorText 
  812. function returns a string to the user for an error.
  813. .PN XESetErrorString
  814. allows you to define a routine to be called that
  815. should return a pointer to the error message.
  816. The following is an example.
  817. .LP
  818. .\" Start marker code here
  819. .Ds 0
  820. .TA .5i 3i
  821. .ta .5i 3i
  822. .R
  823. (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcode\fP, \fIcodes\fP, \fIbuffer\fP, \fInbytes\fP\^)
  824.     Display *\fIdisplay\fP\^;
  825.     int \fIcode\fP\^;
  826.     XExtCodes *\fIcodes\fP\^;
  827.     char *\fIbuffer\fP\^;
  828.     int \fInbytes\fP\^;
  829. .De
  830. .\" End marker code here
  831. .LP
  832. Your procedure is called with the error code for every error detected.
  833. You should copy nbytes of a null-terminated string containing the
  834. error message into buffer.
  835. .IN "XESetPrintErrorValues" "" "@DEF@"
  836. .\" Start marker code here
  837. .FD 0
  838. void (*XESetPrintErrorValues(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  839. .br
  840.       Display *\fIdisplay\fP\^;
  841. .br
  842.       int \fIextension\fP\^;
  843. .br
  844.       void (\^*\fIproc\fP\^)(\^);
  845. .FN
  846. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  847. .IP \fIdisplay\fP 1i
  848. Specifies the connection to the X server.
  849. .IP \fIextension\fP 1i
  850. Specifies the extension number.
  851. .IP \fIproc\fP 1i
  852. Specifies the routine to call when an error is printed.
  853. .\" End marker code here
  854. .LP
  855. This function defines a procedure to be called when an extension
  856. error is printed, to print the error values.  Use this function for extension
  857. errors that contain additional error values beyond those in a core X error.
  858. This function returns any previously defined procedure.
  859. .LP
  860. When Xlib needs to print an error, the routine is called with these arguments:
  861. .LP
  862. .\" Start marker code here
  863. .Ds 0
  864. .TA .5i 3i
  865. .ta .5i 3i
  866. .R
  867. void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIev\fP, \fIfp\fP\^)
  868.     Display *\fIdisplay\fP\^;
  869.     XErrorEvent *\fIev\fP\^;
  870.     void *\fIfp\fP\^;
  871. .De
  872. .\" End marker code here
  873. .LP
  874. The structure pointed at by ev is guaranteed to be as large as an
  875. .PN XEvent
  876. structure, and so can be cast to a type larger than an
  877. .PN XErrorEvent ,
  878. in order to obtain additional values set by using
  879. .PN XESetWireToError .
  880. The underlying type of the fp argument is system dependent;
  881. on a POSIX-compliant fp should be cast to type FILE*.
  882. .IN "XESetFlushGC" "" "@DEF@"
  883. .\" Start marker code here
  884. .FD 0
  885. int (*XESetFlushGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
  886. .br
  887.       Display *\fIdisplay\fP\^;
  888. .br
  889.       int \fIextension\fP\^;
  890. .br
  891.       int *(\^*\fIproc\fP\^)(\^);
  892. .FN
  893. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  894. .IP \fIdisplay\fP 1i
  895. Specifies the connection to the X server.
  896. .IP \fIextension\fP 1i
  897. Specifies the extension number.
  898. .IP \fIproc\fP 1i
  899. Specifies the routine to call when a GC is flushed.
  900. .\" End marker code here
  901. .LP
  902. The
  903. .PN XESetFlushGC
  904. procedure is identical to
  905. .PN XESetCopyGC
  906. except that
  907. .PN XESetFlushGC
  908. is called when a GC cache needs to be updated in the server.
  909. .SH
  910. Hooks onto Xlib Data Structures
  911. .LP
  912. Various Xlib data structures have provisions for extension routines
  913. to chain extension supplied data onto a list.
  914. These structures are
  915. .PN GC , 
  916. .PN Visual , 
  917. .PN Screen , 
  918. .PN ScreenFormat , 
  919. .PN Display , 
  920. and 
  921. .PN XFontStruct .
  922. Because the list pointer is always the first member in the structure, 
  923. a single set of routines can be used to manipulate the data
  924. on these lists.
  925. .LP
  926. The following structure is used in the routines in this section
  927. and is defined in 
  928. .IN "Files" "<X11/Xlib.h>"
  929. .Pn < X11/Xlib.h >:
  930. .LP
  931. .IN "XExtData" "" "@DEF@"
  932. .\" Start marker code here
  933. .Ds 0
  934. .TA .5i 3i
  935. .ta .5i 3i
  936. typedef struct _XExtData {
  937.     int number;    /* number returned by XInitExtension */
  938.     struct _XExtData *next;    /* next item on list of data for structure */
  939.     int (*free_private)();    /* if defined,  called to free private */
  940.     XPointer private_data;    /* data private to this extension. */
  941. } XExtData;
  942. .De
  943. .\" End marker code here
  944. .LP
  945. When any of the data structures listed above are freed, 
  946. the list is walked, and the structure's free routine (if any) is called. 
  947. If free is NULL, 
  948. then the library frees both the data pointed to by the private_data member
  949. and the structure itself. 
  950. .LP
  951. .\" Start marker code here
  952. .Ds 0
  953. .TA .5i
  954. .ta .5i
  955. union {    Display *display;
  956.     GC gc;
  957.     Visual *visual;
  958.     Screen *screen;
  959.     ScreenFormat *pixmap_format;
  960.     XFontStruct *font } XEDataObject;
  961. .De
  962. .\" End marker code here
  963. .LP
  964. .IN "XEHeadOfExtensionList" "" "@DEF@"
  965. .\" Start marker code here
  966. .FD 0
  967. XExtData **XEHeadOfExtensionList(object)
  968.     XEDataObject object;
  969. .FN
  970. .IP \fIobject\fP 1i
  971. Specifies the object.
  972. .\" End marker code here
  973. .LP
  974. .PN XEHeadOfExtensionList
  975. returns a pointer to the list of extension structures attached to the
  976. specified object.
  977. In concert with 
  978. .PN XAddToExtensionList ,
  979. .PN XEHeadOfExtensionList
  980. allows an extension to attach arbitrary data to any of the structures
  981. of types contained in
  982. .PN XEDataObject .
  983. .LP
  984. .IN "XAddToExtensionList" "" "@DEF@"
  985. .\" Start marker code here
  986. .FD 0
  987. XAddToExtensionList(\^\fIstructure\fP, \fIext_data\fP\^)
  988. .br
  989.       XExtData **\fIstructure\fP\^;
  990. .br
  991.       XExtData *\fIext_data\fP\^;
  992. .FN
  993. .IP \fIstructure\fP 1i
  994. Specifies the extension list.
  995. .IP \fIext_data\fP 1i
  996. Specifies the extension data structure to add.
  997. .\" End marker code here
  998. .LP
  999. The structure argument is a pointer to one of the data structures enumerated above.
  1000. You must initialize ext_data->number with the extension number
  1001. before calling this routine.
  1002. .IN "XFindOnExtensionList" "" "@DEF@"
  1003. .\" Start marker code here
  1004. .FD 0
  1005. XExtData *XFindOnExtensionList(\^\fIstructure\fP, \fInumber\fP\^)
  1006. .br
  1007.       struct _XExtData **\fIstructure\fP\^;
  1008. .br
  1009.       int \fInumber\fP\^;
  1010. .FN
  1011. .IP \fIstructure\fP 1i
  1012. Specifies the extension list.
  1013. .IP \fInumber\fP 1i
  1014. Specifies the extension number from XInitExtension.
  1015. .\" End marker code here
  1016. .LP
  1017. .PN XFindOnExtensionList
  1018. returns the first extension data structure for the extension numbered
  1019. number.
  1020. It is expected that an extension will add at most one extension
  1021. data structure to any single data structure's extension data list.
  1022. There is no way to find additional structures.
  1023. .LP
  1024. The 
  1025. .PN XAllocID 
  1026. macro, which allocates and returns a resource ID, is defined in 
  1027. .IN "Files" "<X11/Xlib.h>"
  1028. .Pn < X11/Xlib.h >.
  1029. .IN "XAllocID" "" "@DEF@"
  1030. .\" Start marker code here
  1031. .FD 0
  1032. XAllocID\^(\fIdisplay\fP\^)
  1033. .br
  1034.      Display *\fIdisplay\fP\^;
  1035. .FN
  1036. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1037. .IP \fIdisplay\fP 1i
  1038. Specifies the connection to the X server.
  1039. .\" End marker code here
  1040. .LP
  1041. This macro is a call through the 
  1042. .PN Display
  1043. structure to the internal resource ID allocator.
  1044. It returns a resource ID that you can use when creating new resources.
  1045. .SH
  1046. GC Caching
  1047. .LP
  1048. GCs are cached by the library to allow merging of independent change
  1049. requests to the same GC into single protocol requests.
  1050. This is typically called a write-back cache.
  1051. Any extension routine whose behavior depends on the contents of a GC must flush
  1052. the GC cache to make sure the server has up-to-date contents in its GC.
  1053. .LP
  1054. The 
  1055. .PN FlushGC
  1056. macro checks the dirty bits in the library's GC structure and calls
  1057. .PN _XFlushGCCache 
  1058. if any elements have changed.
  1059. The
  1060. .PN FlushGC
  1061. macro is defined as follows:
  1062. .IN "FlushGC" "" "@DEF@"
  1063. .\" Start marker code here
  1064. .FD 0
  1065. FlushGC\^(\^\fIdisplay\fP\^, \fIgc\fP\^)
  1066. .br
  1067.       Display *\^\fIdisplay\fP\^;
  1068. .br
  1069.       GC \fIgc\fP\^;
  1070. .FN
  1071. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1072. .IP \fIdisplay\fP 1i
  1073. Specifies the connection to the X server.
  1074. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1075. .IP \fIgc\fP 1i
  1076. Specifies the GC.
  1077. .\" End marker code here
  1078. .LP
  1079. Note that if you extend the GC to add additional resource ID components,
  1080. you should ensure that the library stub sends the change request immediately.
  1081. This is because a client can free a resource immediately after
  1082. using it, so if you only stored the value in the cache without
  1083. forcing a protocol request, the resource might be destroyed before being
  1084. set into the GC.
  1085. You can use the
  1086. .PN _XFlushGCCache 
  1087. procedure 
  1088. to force the cache to be flushed.
  1089. The
  1090. .PN _XFlushGCCache 
  1091. procedure
  1092. is defined as follows:
  1093. .IN "_XFlushGCCache" "" "@DEF@"
  1094. .\" Start marker code here
  1095. .FD 0
  1096. _XFlushGCCache\^(\^\fIdisplay\fP\^, \fIgc\fP\^)
  1097. .br
  1098.       Display *\^\fIdisplay\fP\^;
  1099. .br
  1100.       GC \fIgc\fP\^;
  1101. .FN
  1102. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1103. .IP \fIdisplay\fP 1i
  1104. Specifies the connection to the X server.
  1105. .\" $Header: gc.a,v 1.2 88/05/09 11:20:34 mento Exp $
  1106. .IP \fIgc\fP 1i
  1107. Specifies the GC.
  1108. .\" End marker code here
  1109. .SH
  1110. Graphics Batching
  1111. .LP
  1112. If you extend X to add more poly graphics primitives, you may be able to
  1113. take advantage of facilities in the library to allow back-to-back 
  1114. single calls to be transformed into poly requests.
  1115. This may dramatically improve performance of programs that are not
  1116. written using poly requests. 
  1117. A pointer to an 
  1118. .PN xReq ,
  1119. called last_req in the display structure, is the last request being processed.  
  1120. By checking that the last request
  1121. type, drawable, gc, and other options are the same as the new one
  1122. and that there is enough space left in the buffer, you may be able
  1123. to just extend the previous graphics request by extending the length
  1124. field of the request and appending the data to the buffer.  
  1125. This can improve performance by five times or more in naive programs.  
  1126. For example, here is the source for the 
  1127. .PN XDrawPoint 
  1128. stub.
  1129. (Writing extension stubs is discussed in the next section.)
  1130. .IP
  1131. .\" Start marker code here
  1132. .nf
  1133. #include "copyright.h"
  1134.  
  1135. #include "Xlibint.h"
  1136.  
  1137. /* precompute the maximum size of batching request allowed */
  1138.  
  1139. static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
  1140.  
  1141. XDrawPoint(dpy, d, gc, x, y)
  1142.     register Display *dpy;
  1143.     Drawable d;
  1144.     GC gc;
  1145.     int x, y; /* INT16 */
  1146. {
  1147.     xPoint *point;
  1148.     LockDisplay(dpy);
  1149.     FlushGC(dpy, gc);
  1150.     {
  1151.     register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
  1152.     /* if same as previous request, with same drawable, batch requests */
  1153.     if (
  1154.           (req->reqType == X_PolyPoint)
  1155.        && (req->drawable == d)
  1156.        && (req->gc == gc->gid)
  1157.        && (req->coordMode == CoordModeOrigin)
  1158.        && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
  1159.        && (((char *)dpy->bufptr - (char *)req) < size) ) {
  1160.          point = (xPoint *) dpy->bufptr;
  1161.          req->length += sizeof (xPoint) >> 2;
  1162.          dpy->bufptr += sizeof (xPoint);
  1163.          }
  1164.  
  1165.     else {
  1166.         GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
  1167.         req->drawable = d;
  1168.         req->gc = gc->gid;
  1169.         req->coordMode = CoordModeOrigin;
  1170.         point = (xPoint *) (req + 1);
  1171.         }
  1172.     point->x = x;
  1173.     point->y = y;
  1174.     }
  1175.     UnlockDisplay(dpy);
  1176.     SyncHandle();
  1177. }
  1178. .fi
  1179. .\" End marker code here
  1180. .LP
  1181. To keep clients from generating very long requests that may monopolize the 
  1182. server,
  1183. there is a symbol defined in
  1184. .IN "Files" "<X11/Xlibint.h>"
  1185. .Pn < X11/Xlibint.h >
  1186. of EPERBATCH on the number of requests batched.
  1187. Most of the performance benefit occurs in the first few merged requests.
  1188. Note that 
  1189. .PN FlushGC 
  1190. is called \fIbefore\fP picking up the value of last_req,
  1191. because it may modify this field.
  1192. .SH
  1193. Writing Extension Stubs
  1194. .LP
  1195. All X requests always contain the length of the request,
  1196. expressed as a 16-bit quantity of 32 bits.
  1197. This means that a single request can be no more than 256K bytes in
  1198. length.
  1199. Some servers may not support single requests of such a length.
  1200. The value of dpy->max_request_size contains the maximum length as
  1201. defined by the server implementation.
  1202. For further information,
  1203. see ``X Window System Protocol.''
  1204. .SH
  1205. Requests, Replies, and Xproto.h
  1206. .LP
  1207. The 
  1208. .IN "Files" "<X11/Xproto.h>"
  1209. .Pn < X11/Xproto.h >
  1210. file contains three sets of definitions that
  1211. are of interest to the stub implementor:  
  1212. request names, request structures, and reply structures.
  1213. .LP
  1214. You need to generate a file equivalent to 
  1215. .IN "Files" "<X11/Xproto.h>"
  1216. .Pn < X11/Xproto.h >
  1217. for your extension and need to include it in your stub routine.
  1218. Each stub routine also must include 
  1219. .IN "Files" "<X11/Xlibint.h>"
  1220. .Pn < X11/Xlibint.h >.
  1221. .LP
  1222. The identifiers are deliberately chosen in such a way that, if the
  1223. request is called X_DoSomething, then its request structure is
  1224. xDoSomethingReq, and its reply is xDoSomethingReply.  
  1225. The GetReq family of macros, defined in 
  1226. .IN "Files" "<X11/Xlibint.h>"
  1227. .Pn < X11/Xlibint.h >, 
  1228. takes advantage of this naming scheme.
  1229. .LP
  1230. For each X request, 
  1231. there is a definition in 
  1232. .IN "Files" "<X11/Xproto.h>"
  1233. .Pn < X11/Xproto.h >
  1234. that looks similar to this:
  1235. .LP
  1236. .Ds 
  1237. .R
  1238. #define X_DoSomething   42
  1239. .De
  1240. In your extension header file, 
  1241. this will be a minor opcode, 
  1242. instead of a major opcode.
  1243. .SH
  1244. Request Format
  1245. .LP
  1246. Every request contains an 8-bit major opcode and a 16-bit length field
  1247. expressed in units of four bytes.  
  1248. Every request consists of four bytes of header
  1249. (containing the major opcode, the length field, and a data byte) followed by
  1250. zero or more additional bytes of data. 
  1251. The length field defines the total length of the request, including the header.
  1252. The length field in a request must equal the minimum length required to contain 
  1253. the request. 
  1254. If the specified length is smaller or larger than the required length, 
  1255. the server should generate a 
  1256. .PN BadLength 
  1257. error.
  1258. Unused bytes in a request are not required to be zero.  
  1259. Extensions should be designed in such a way that long protocol requests
  1260. can be split up into smaller requests,
  1261. if it is possible to exceed the maximum request size of the server.
  1262. The protocol guarantees the maximum request size to be no smaller than
  1263. 4096 units (16384 bytes).
  1264. .LP
  1265. Major opcodes 128 through 255 are reserved for extensions.
  1266. Extensions are intended to contain multiple requests, 
  1267. so extension requests typically have an additional minor opcode encoded 
  1268. in the ``spare'' data byte in the request header, 
  1269. but the placement and interpretation of this minor opcode as well as all
  1270. other fields in extension requests are not defined by the core protocol.
  1271. Every request is implicitly assigned a sequence number (starting with one)
  1272. used in replies, errors, and events.
  1273. .LP
  1274. To help but not cure portability problems to certain machines, the
  1275. .PN B16
  1276. and
  1277. .PN B32
  1278. macros have been defined so that they can become bitfield specifications 
  1279. on some machines.
  1280. For example, on a Cray,
  1281. these should be used for all 16-bit and 32-bit quantities, as discussed below.
  1282. .LP
  1283. Most protocol requests have a corresponding structure typedef in
  1284. .IN "Files" "<X11/Xproto.h>"
  1285. .Pn < X11/Xproto.h >,
  1286. which looks like:
  1287. .LP
  1288. .IN "xDoSomethingReq" "" "@DEF@"
  1289. .\" Start marker code here
  1290. .Ds 0
  1291. .TA .5i 3i
  1292. .ta .5i 3i
  1293. typedef struct _DoSomethingReq {
  1294.     CARD8 reqType;    /* X_DoSomething */
  1295.     CARD8 someDatum;    /* used differently in different requests */
  1296.     CARD16 length B16;    /* total # of bytes in request, divided by 4 */
  1297.     ...
  1298.     /* request-specific data */
  1299.     ...
  1300. } xDoSomethingReq;
  1301. .De
  1302. .\" End marker code here
  1303. .LP
  1304. If a core protocol request has a single 32-bit argument, 
  1305. you need not declare a request structure in your extension header file.
  1306. Instead, such requests use 
  1307. .Pn < X11/Xproto.h >'s
  1308. .PN xResourceReq
  1309. structure.  
  1310. This structure is used for any request whose single argument is a 
  1311. .PN Window , 
  1312. .PN Pixmap ,
  1313. .PN Drawable , 
  1314. .PN GContext , 
  1315. .PN Font , 
  1316. .PN Cursor , 
  1317. .PN Colormap , 
  1318. .PN Atom , 
  1319. or
  1320. .PN VisualID .
  1321. .LP
  1322. .IN "xResourceReq" "" "@DEF@"
  1323. .\" Start marker code here
  1324. .Ds 0
  1325. .TA .5i 3i
  1326. .ta .5i 3i
  1327. typedef struct _ResourceReq {
  1328.     CARD8 reqType;    /* the request type, e.g. X_DoSomething */
  1329.     BYTE pad;    /* not used */
  1330.     CARD16 length B16;    /* 2 (= total # of bytes in request, divided by 4) */
  1331.     CARD32 id B32;    /* the Window, Drawable, Font, GContext, etc. */
  1332. } xResourceReq;
  1333. .De
  1334. .\" End marker code here
  1335. .LP
  1336. If convenient,
  1337. you can do something similar in your extension header file. 
  1338. .LP
  1339. In both of these structures, 
  1340. the reqType field identifies the type of the request (for example, 
  1341. X_MapWindow or X_CreatePixmap).  
  1342. The length field tells how long the request is
  1343. in units of 4-byte longwords. 
  1344. This length includes both the request structure itself and any
  1345. variable length data, such as strings or lists, that follow the
  1346. request structure.  
  1347. Request structures come in different sizes, 
  1348. but all requests are padded to be multiples of four bytes long.
  1349. .LP
  1350. A few protocol requests take no arguments at all. 
  1351. Instead, they use 
  1352. .Pn < X11/Xproto.h >'s
  1353. .PN xReq 
  1354. structure, which contains only a reqType and a length (and a pad byte).
  1355. .LP 
  1356. If the protocol request requires a reply, 
  1357. then
  1358. .IN "Files" "<Xproto.h>"
  1359. .Pn < X11/Xproto.h >
  1360. also contains a reply structure typedef:
  1361. .LP
  1362. .IN "xDoSomethingReply" "" "@DEF@"
  1363. .\" Start marker code here
  1364. .Ds 0
  1365. .TA .5i 3i
  1366. .ta .5i 3i
  1367. typedef struct _DoSomethingReply {
  1368.     BYTE type;    /* always X_Reply */
  1369.     BYTE someDatum;    /* used differently in different requests */
  1370.     CARD16 sequenceNumber B16;    /* # of requests sent so far */
  1371.     CARD32 length B32;    /* # of additional bytes, divided by 4 */
  1372.     ...
  1373.     /* request-specific data */
  1374.     ...
  1375. } xDoSomethingReply;
  1376. .De
  1377. .\" End marker code here
  1378. .LP
  1379. Most of these reply structures are 32 bytes long. 
  1380. If there are not that many reply values, 
  1381. then they contain a sufficient number of pad fields
  1382. to bring them up to 32 bytes.  
  1383. The length field is the total number of bytes in the request minus 32, 
  1384. divided by 4.  
  1385. This length will be nonzero only if:
  1386. .IP \(bu 5
  1387. The reply structure is followed by variable length
  1388. data such as a list or string.
  1389. .IP \(bu 5
  1390. The reply structure is longer than 32 bytes.
  1391. .LP
  1392. Only 
  1393. .PN GetWindowAttributes , 
  1394. .PN QueryFont , 
  1395. .PN QueryKeymap , 
  1396. and
  1397. .PN GetKeyboardControl 
  1398. have reply structures longer than 32 bytes in the core protocol.
  1399. .LP
  1400. A few protocol requests return replies that contain no data.  
  1401. .IN "Files" "<X11/Xproto.h>"
  1402. .Pn < X11/Xproto.h >
  1403. does not define reply structures for these.
  1404. Instead, they use the 
  1405. .PN xGenericReply
  1406. structure, which contains only a type, length,
  1407. and sequence number (and sufficient padding to make it 32 bytes long).
  1408. .SH
  1409. Starting to Write a Stub Routine
  1410. .LP
  1411. An Xlib stub routine should always start like this:
  1412. .LP
  1413. .Ds 
  1414. .R
  1415. #include "Xlibint.h"
  1416.  
  1417. XDoSomething (arguments, ... )
  1418. /* argument declarations */
  1419. {
  1420.  
  1421. register XDoSomethingReq *req;
  1422. ...
  1423. .De
  1424. If the protocol request has a reply, 
  1425. then the variable declarations should include the reply structure for the request.
  1426. The following is an example:
  1427. .LP
  1428. .Ds 
  1429. .R
  1430. xDoSomethingReply rep;
  1431. .De 
  1432. .SH
  1433. Locking Data Structures
  1434. .LP
  1435. To lock the display structure for systems that
  1436. want to support multithreaded access to a single display connection,
  1437. each stub will need to lock its critical section.
  1438. Generally, this section is the point from just before the appropriate GetReq
  1439. call until all arguments to the call have been stored into the buffer.
  1440. The precise instructions needed for this locking depend upon the machine
  1441. architecture. 
  1442. Two calls, which are generally implemented as macros, have been provided.
  1443. .IN "LockDisplay" "" "@DEF@"
  1444. .\" Start marker code here
  1445. .FD 0
  1446. LockDisplay(\^\fIdisplay\fP\^)
  1447. .br
  1448.       Display *\fIdisplay\fP\^;
  1449. .FN
  1450. .LP
  1451. .IN "UnlockDisplay" "" "@DEF@"
  1452. .FD 0
  1453. UnlockDisplay(\^\fIdisplay\fP\^)
  1454. .br
  1455.       Display *\fIdisplay\fP\^;
  1456. .FN
  1457. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1458. .IP \fIdisplay\fP 1i
  1459. Specifies the connection to the X server.
  1460. .\" End marker code here
  1461. .SH
  1462. Sending the Protocol Request and Arguments
  1463. .LP
  1464. After the variable declarations, 
  1465. a stub routine should call one of four macros defined in 
  1466. .IN "Files" "<X11/Xlibint.h>"
  1467. .Pn < X11/Xlibint.h >: 
  1468. .PN GetReq , 
  1469. .PN GetReqExtra , 
  1470. .PN GetResReq , 
  1471. or 
  1472. .PN GetEmptyReq .  
  1473. All of these macros take, as their first argument,
  1474. the name of the protocol request as declared in 
  1475. .IN "Files" "<X11/Xproto.h>"
  1476. .Pn < X11/Xproto.h >
  1477. except with X_ removed.   
  1478. Each one declares a 
  1479. .PN Display 
  1480. structure pointer,
  1481. called dpy, and a pointer to a request structure, called req,
  1482. which is of the appropriate type.
  1483. The macro then appends the request structure to the output buffer, 
  1484. fills in its type and length field, and sets req to point to it.
  1485. .LP
  1486. If the protocol request has no arguments (for instance, X_GrabServer),
  1487. then use 
  1488. .PN GetEmptyReq .
  1489. .LP
  1490. .Ds
  1491. .R 
  1492. GetEmptyReq (DoSomething, req);
  1493. .De
  1494. If the protocol request has a single 32-bit argument (such as a
  1495. .PN Pixmap , 
  1496. .PN Window , 
  1497. .PN Drawable , 
  1498. .PN Atom , 
  1499. and so on),
  1500. then use 
  1501. .PN GetResReq .  
  1502. The second argument to the macro is the 32-bit object.  
  1503. .PN X_MapWindow 
  1504. is a good example.
  1505. .LP
  1506. .Ds
  1507. .R
  1508. GetResReq (DoSomething, rid, req);
  1509. .De
  1510. The rid argument is the 
  1511. .PN Pixmap , 
  1512. .PN Window , 
  1513. or other resource ID.
  1514. .LP
  1515. If the protocol request takes any other argument list, 
  1516. then call 
  1517. .PN GetReq .  
  1518. After the 
  1519. .PN GetReq , 
  1520. you need to set all the other fields in the request structure,
  1521. usually from arguments to the stub routine.
  1522. .LP
  1523. .Ds 
  1524. .R
  1525. GetReq (DoSomething, req);
  1526. /* fill in arguments here */
  1527. req->arg1 = arg1;
  1528. req->arg2 = arg2;
  1529. ...
  1530. .De
  1531. A few stub routines (such as 
  1532. .PN XCreateGC 
  1533. and 
  1534. .PN XCreatePixmap ) 
  1535. return a resource ID to the caller but pass a resource ID as an argument
  1536. to the protocol request.   
  1537. Such routines use the macro 
  1538. .PN XAllocID 
  1539. to allocate a resource ID from the range of IDs 
  1540. that were assigned to this client when it opened the connection.
  1541. .LP
  1542. .Ds 
  1543. .R
  1544. rid = req->rid = XAllocID();
  1545. ...
  1546. return (rid);
  1547. .De
  1548. Finally, some stub routines transmit a fixed amount of variable length
  1549. data after the request.  
  1550. Typically, these routines (such as
  1551. .PN XMoveWindow 
  1552. and 
  1553. .PN XSetBackground ) 
  1554. are special cases of more general functions like 
  1555. .PN XMoveResizeWindow 
  1556. and 
  1557. .PN XChangeGC .   
  1558. These special case routines use 
  1559. .PN GetReqExtra , 
  1560. which is the same as 
  1561. .PN GetReq
  1562. except that it takes an additional argument (the number of
  1563. extra bytes to allocate in the output buffer after the request structure).  
  1564. This number should always be a multiple of four.
  1565. .SH
  1566. Variable Length Arguments
  1567. .LP
  1568. Some protocol requests take additional variable length data that
  1569. follow the 
  1570. .PN xDoSomethingReq 
  1571. structure.    
  1572. The format of this data varies from request to request. 
  1573. Some requests require a sequence of 8-bit bytes, 
  1574. others a sequence of 16-bit or 32-bit entities, 
  1575. and still others a sequence of structures.
  1576. .LP
  1577. It is necessary to add the length of any variable length data to the
  1578. length field of the request structure.  
  1579. That length field is in units of 32-bit longwords.  
  1580. If the data is a string or other sequence of 8-bit bytes, 
  1581. then you must round the length up and shift it before adding:
  1582. .LP
  1583. .Ds
  1584. .R
  1585. req->length += (nbytes+3)>>2;
  1586. .De
  1587. To transmit variable length data, use the 
  1588. .PN Data 
  1589. macros.
  1590. If the data fits into the output buffer, 
  1591. then this macro copies it to the buffer.  
  1592. If it does not fit, however,
  1593. the 
  1594. .PN Data 
  1595. macro calls 
  1596. .PN _XSend , 
  1597. which transmits first the contents of the buffer and then your data.
  1598. The 
  1599. .PN Data 
  1600. macros take three arguments:  
  1601. the Display, a pointer to the beginning of the data, 
  1602. and the number of bytes to be sent.
  1603. .\" Start marker code here
  1604. .FD 0
  1605. Data(\^\fIdisplay\fP, (char *) \fIdata\fP, \fInbytes\fP\^);
  1606. .sp
  1607. Data16(\^\fIdisplay\fP, (short *) \fIdata\fP, \fInbytes\fP\^);
  1608. .sp
  1609. Data32(\^\fIdisplay\fP, (long *) \fIdata\fP, \fInbytes\fP\^);
  1610. .FN
  1611. .\" End marker code here
  1612. .LP
  1613. .PN Data ,
  1614. .PN Data16 ,
  1615. and
  1616. .PN Data32
  1617. are macros that may use their last argument
  1618. more than once, so that argument should be a variable rather than
  1619. an expression such as ``nitems*sizeof(item)''.  
  1620. You should do that kind of computation in a separate statement before calling 
  1621. them.
  1622. Use the appropriate macro when sending byte, short, or long data.
  1623. .LP
  1624. If the protocol request requires a reply, 
  1625. then call the procedure 
  1626. .PN _XSend 
  1627. instead of the 
  1628. .PN Data 
  1629. macro.  
  1630. .PN _XSend 
  1631. takes the same arguments, but because it sends your data immediately instead of 
  1632. copying it into the output buffer (which would later be flushed
  1633. anyway by the following call on 
  1634. .PN _XReply ), 
  1635. it is faster.
  1636. .SH
  1637. Replies
  1638. .LP
  1639. If the protocol request has a reply, 
  1640. then call 
  1641. .PN _XReply 
  1642. after you have finished dealing with 
  1643. all the fixed and variable length arguments.  
  1644. .PN _XReply 
  1645. flushes the output buffer and waits for an 
  1646. .PN xReply 
  1647. packet to arrive.  
  1648. If any events arrive in the meantime,
  1649. .PN _XReply 
  1650. places them in the queue for later use.
  1651. .IN "_XReply" "" "@DEF@"
  1652. .\" Start marker code here
  1653. .FD 0
  1654. Status _XReply(\^\fIdisplay\fP, \fIrep\fP, \fIextra\fP, \fIdiscard\fP\^)
  1655. .br
  1656.       Display *\fIdisplay\fP\^;
  1657. .br
  1658.       xReply *\fIrep\fP\^;
  1659. .br
  1660.       int \fIextra\fP\^;
  1661. .br
  1662.       Bool \fIdiscard\fP\^;
  1663. .FN
  1664. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1665. .IP \fIdisplay\fP 1i
  1666. Specifies the connection to the X server.
  1667. .IP \fIrep\fP 1i
  1668. Specifies the reply structure.
  1669. .IP \fIextra\fP 1i
  1670. Specifies the number of 32-bit words expected after the replay.
  1671. .IP \fIdiscard\fP 1i
  1672. Specifies if beyond the ``extra'' data should be discarded.
  1673. .\" End marker code here
  1674. .LP
  1675. .PN _XReply 
  1676. waits for a reply packet and copies its contents into the
  1677. specified rep.  
  1678. .PN _XReply 
  1679. handles error and event packets that occur before the reply is received.
  1680. .PN _XReply 
  1681. takes four arguments:
  1682. .IP \(bu 5
  1683. A 
  1684. .PN Display 
  1685. * structure
  1686. .IP \(bu 5
  1687. A pointer to a reply structure (which must be cast to an 
  1688. .PN xReply 
  1689. *)
  1690. .IP \(bu 5
  1691. The number of additional 32-bit words (beyond 
  1692. .Pn sizeof( xReply ) 
  1693. = 32 bytes)
  1694. in the reply structure
  1695. .IP \(bu 5
  1696. A Boolean that indicates whether
  1697. .PN _XReply 
  1698. is to discard any additional bytes
  1699. beyond those it was told to read
  1700. .LP
  1701. Because most reply structures are 32 bytes long, 
  1702. the third argument is usually 0.  
  1703. The only core protocol exceptions are the replies to 
  1704. .PN GetWindowAttributes , 
  1705. .PN QueryFont , 
  1706. .PN QueryKeymap , 
  1707. and 
  1708. .PN GetKeyboardControl ,
  1709. which have longer replies.
  1710. .LP
  1711. The last argument should be 
  1712. .PN False 
  1713. if the reply structure is followed
  1714. by additional variable length data (such as a list or string).  
  1715. It should be 
  1716. .PN True 
  1717. if there is not any variable length data.
  1718. .NT
  1719. This last argument is provided for upward-compatibility reasons
  1720. to allow a client to communicate properly with a hypothetical later
  1721. version of the server that sends more data than the client expected.
  1722. For example, some later version of 
  1723. .PN GetWindowAttributes 
  1724. might use a
  1725. larger, but compatible, 
  1726. .PN xGetWindowAttributesReply 
  1727. that contains additional attribute data at the end.
  1728. .NE
  1729. .PN _XReply 
  1730. returns 
  1731. .PN True
  1732. if it received a reply successfully or 
  1733. .PN False 
  1734. if it received any sort of error. 
  1735. .LP
  1736. For a request with a reply that is not followed by variable length
  1737. data, you write something like:
  1738. .LP
  1739. .Ds 
  1740. .R
  1741. _XReply(display, (xReply *)&rep, 0, True);
  1742. *ret1 = rep.ret1;
  1743. *ret2 = rep.ret2;
  1744. *ret3 = rep.ret3;
  1745. ...
  1746. UnlockDisplay(dpy);
  1747. SyncHandle();
  1748. return (rep.ret4);
  1749. }
  1750. .De
  1751. If there is variable length data after the reply, 
  1752. change the 
  1753. .PN True 
  1754. to 
  1755. .PN False , 
  1756. and use the appropriate
  1757. .PN _XRead 
  1758. function to read the variable length data.
  1759. .LP
  1760. .\" Start marker code here
  1761. .FD 0
  1762. _XRead(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
  1763.        Display *\fIdisplay\fP\^;
  1764.        char *\fIdata_return\fP\^;
  1765.        long \fInbytes\fP\^;    
  1766. .FN
  1767. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1768. .IP \fIdisplay\fP 1i
  1769. Specifies the connection to the X server.
  1770. .IP \fIdata_return\fP 1i
  1771. Specifies the buffer.
  1772. .IP \fInbytes\fP 1i
  1773. Specifies the number of bytes required.
  1774. .\" End marker code here
  1775. .LP
  1776. .PN _XRead
  1777. reads the specified number of bytes into data_return.
  1778. .LP
  1779. .\" Start marker code here
  1780. .FD 0
  1781. _XRead16(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
  1782.        Display *\fIdisplay\fP\^;
  1783.        short *\fIdata_return\fP\^;
  1784.        long \fInbytes\fP\^;
  1785. .FN
  1786. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1787. .IP \fIdisplay\fP 1i
  1788. Specifies the connection to the X server.
  1789. .IP \fIdata_return\fP 1i
  1790. Specifies the buffer.
  1791. .IP \fInbytes\fP 1i
  1792. Specifies the number of bytes required.
  1793. .\" End marker code here
  1794. .LP
  1795. .PN _XRead16
  1796. reads the specified number of bytes, unpacking them as 16-bit quantities,
  1797. into the specified array as shorts.
  1798. .LP
  1799. .\" Start marker code here
  1800. .FD 0
  1801. _XRead32(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
  1802.        Display *\fIdisplay\fP\^;
  1803.        long *\fIdata_return\fP\^;
  1804.        long \fInbytes\fP\^;
  1805. .FN
  1806. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1807. .IP \fIdisplay\fP 1i
  1808. Specifies the connection to the X server.
  1809. .IP \fIdata_return\fP 1i
  1810. Specifies the buffer.
  1811. .IP \fInbytes\fP 1i
  1812. Specifies the number of bytes required.
  1813. .\" End marker code here
  1814. .LP
  1815. .PN _XRead32
  1816. reads the specified number of bytes, unpacking them as 32-bit quantities,
  1817. into the specified array as longs.
  1818. .LP
  1819. .\" Start marker code here
  1820. .FD 0
  1821. _XRead16Pad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
  1822.        Display *\fIdisplay\fP\^;
  1823.        short *\fIdata_return\fP\^;
  1824.        long \fInbytes\fP\^; 
  1825. .FN
  1826. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1827. .IP \fIdisplay\fP 1i
  1828. Specifies the connection to the X server.
  1829. .IP \fIdata_return\fP 1i
  1830. Specifies the buffer.
  1831. .IP \fInbytes\fP 1i
  1832. Specifies the number of bytes required.
  1833. .\" End marker code here
  1834. .LP
  1835. .PN _XRead16Pad
  1836. reads the specified number of bytes, unpacking them as 16-bit quantities,
  1837. into the specified array as shorts.
  1838. If the number of bytes is not a multiple of four,
  1839. .PN _XRead16Pad
  1840. reads and discards up to three additional pad bytes.
  1841. .LP
  1842. .\" Start marker code here
  1843. .FD 0
  1844. _XReadPad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
  1845.        Display *\fIdisplay\fP\^;
  1846.        char *\fIdata_return\fP\^;
  1847.        long \fInbytes\fP\^; 
  1848. .FN
  1849. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1850. .IP \fIdisplay\fP 1i
  1851. Specifies the connection to the X server.
  1852. .IP \fIdata_return\fP 1i
  1853. Specifies the buffer.
  1854. .IP \fInbytes\fP 1i
  1855. Specifies the number of bytes required.
  1856. .\" End marker code here
  1857. .LP
  1858. .PN _XReadPad
  1859. reads the specified number of bytes into data_return.
  1860. If the number of bytes is not a multiple of four,
  1861. .PN _XReadPad
  1862. reads and discards up to three additional pad bytes.
  1863. .LP
  1864. Each protocol request is a little different. 
  1865. For further information,
  1866. see the Xlib sources for examples.
  1867. .SH
  1868. Synchronous Calling
  1869. .LP
  1870. To ease debugging, 
  1871. each routine should have a call, just before returning to the user, 
  1872. to a routine called
  1873. .PN SyncHandle .
  1874. This routine generally is implemented as a macro.
  1875. If synchronous mode is enabled (see 
  1876. .PN XSynchronize ), 
  1877. the request is sent immediately.
  1878. The library, however, waits until any error the routine could generate
  1879. at the server has been handled.
  1880. .SH
  1881. Allocating and Deallocating Memory
  1882. .LP
  1883. To support the possible reentry of these routines, 
  1884. you must observe several conventions when allocating and deallocating memory,
  1885. most often done when returning data to the user from the window
  1886. system of a size the caller could not know in advance
  1887. (for example, a list of fonts or a list of extensions).
  1888. The standard C library routines on many systems
  1889. are not protected against signals or other multithreaded uses.
  1890. The following analogies to standard I/O library routines
  1891. have been defined:
  1892. .IP Xmalloc() 1i
  1893. Replaces malloc()
  1894. .IP XFree() 1i
  1895. Replaces free()
  1896. .IP Xcalloc() 1i
  1897. Replaces calloc()
  1898. .LP
  1899. These should be used in place of any calls you would make to the normal
  1900. C library routines.
  1901. .LP
  1902. If you need a single scratch buffer inside a critical section 
  1903. (for example, to pack and unpack data to and from the wire protocol),
  1904.  the general memory allocators
  1905. may be too expensive to use (particularly in output routines, which
  1906. are performance critical).  
  1907. The routine below returns a scratch buffer for your use:
  1908. .IN "_XAllocScratch" "" "@DEF@"
  1909. .\" Start marker code here
  1910. .FD 0
  1911. char *_XAllocScratch(\^\fIdisplay\fP, \fInbytes\fP\^)
  1912. .br
  1913.       Display *\fIdisplay\fP\^;
  1914. .br
  1915.       unsigned long \fInbytes\fP\^;
  1916. .FN
  1917. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1918. .IP \fIdisplay\fP 1i
  1919. Specifies the connection to the X server.
  1920. .IP \fInbytes\fP 1i
  1921. Specifies the number of bytes required.
  1922. .\" End marker code here
  1923. .LP
  1924. This storage must only be used inside of the critical section of your
  1925. stub.
  1926. .SH
  1927. Portability Considerations
  1928. .LP
  1929. Many machine architectures, 
  1930. including many of the more recent RISC architectures, 
  1931. do not correctly access data at unaligned locations; 
  1932. their compilers pad out structures to preserve this characteristic.
  1933. Many other machines capable of unaligned references pad inside of structures
  1934. as well to preserve alignment, because accessing aligned data is
  1935. usually much faster.
  1936. Because the library and the server use structures to access data at
  1937. arbitrary points in a byte stream,
  1938. all data in request and reply packets \fImust\fP be naturally aligned;
  1939. that is, 16-bit data starts on 16-bit boundaries in the request
  1940. and 32-bit data on 32-bit boundaries.
  1941. All requests \fImust\fP be a multiple of 32 bits in length to preserve
  1942. the natural alignment in the data stream.
  1943. You must pad structures out to 32-bit boundaries.
  1944. Pad information does not have to be zeroed unless you want to
  1945. preserve such fields for future use in your protocol requests.
  1946. Floating point varies radically between machines and should be
  1947. avoided completely if at all possible.
  1948. .LP
  1949. This code may run on machines with 16-bit ints.  
  1950. So, if any integer argument, variable, or return value either can take 
  1951. only nonnegative values or is declared as a CARD16 in the protocol, 
  1952. be sure to declare it as unsigned int and not as int.
  1953. (This, of course, does not apply to Booleans or enumerations.)
  1954. .LP
  1955. Similarly, 
  1956. if any integer argument or return value is declared CARD32 in the protocol, 
  1957. declare it as an unsigned long and not as int or long.
  1958. This also goes for any internal variables that may
  1959. take on values larger than the maximum 16-bit unsigned int.
  1960. .LP
  1961. The library currently assumes that a char is 8 bits, 
  1962. a short is 16 bits, an int is 16 or 32 bits, and a long is 32 bits.  
  1963. The 
  1964. .PN PackData 
  1965. macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 
  1966. However, much more work is needed to make this work properly.
  1967. .SH
  1968. Deriving the Correct Extension Opcode
  1969. .LP
  1970. The remaining problem a writer of an extension stub routine faces that
  1971. the core protocol does not face is to map from the call to the proper
  1972. major and minor opcodes.  
  1973. While there are a number of strategies, 
  1974. the simplest and fastest is outlined below.
  1975. .IP 1. 5
  1976. Declare an array of pointers, _NFILE long (this is normally found
  1977. in 
  1978. .Pn < stdio.h > 
  1979. and is the number of file descriptors supported on the system)
  1980. of type 
  1981. .PN XExtCodes .
  1982. Make sure these are all initialized to NULL.
  1983. .IP 2. 5
  1984. When your stub is entered, your initialization test is just to use
  1985. the display pointer passed in to access the file descriptor and an index
  1986. into the array.  
  1987. If the entry is NULL, then this is the first time you
  1988. are entering the routine for this display.  
  1989. Call your initialization routine and pass it to the display pointer.
  1990. .IP 3. 5
  1991. Once in your initialization routine, call 
  1992. .PN XInitExtension ;
  1993. if it succeeds, store the pointer returned into this array.  
  1994. Make sure to establish a close display handler to allow you to zero the entry.
  1995. Do whatever other initialization your extension requires.
  1996. (For example, install event handlers and so on.)
  1997. Your initialization routine would normally return a pointer to the
  1998. .PN XExtCodes 
  1999. structure for this extension, which is what would normally
  2000. be found in your array of pointers.
  2001. .IP 4. 5
  2002. After returning from your initialization routine, 
  2003. the stub can now continue normally, because it has its major opcode safely 
  2004. in its hand in the 
  2005. .PN XExtCodes 
  2006. structure.
  2007. .bp
  2008.