home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / FSProtocol / protocol.ms < prev    next >
Encoding:
Text File  |  1993-07-21  |  91.6 KB  |  3,593 lines
  1. .\" $XConsortium: protocol.ms,v 1.9 92/07/09 18:16:13 gildea Exp $
  2. .\" Use tbl, -ms, and macros.t
  3. .EH ''''
  4. .OH ''''
  5. .EF ''''
  6. .OF ''''
  7. .ps 11
  8. .nr PS 11
  9. \&
  10. .sp 8
  11. .ce 50
  12. \s+3\fBThe X Font Service Protocol\fP\s-3
  13. .sp
  14. \fBVersion 2.0\fP
  15. \fBMIT X Consortium Standard\fR
  16. .sp
  17. \fBX Version 11, Release 5\fR
  18. .sp 6
  19. Jim Fulton
  20. Network Computing Devices, Inc.
  21. .ce 0
  22. .bp
  23. .br
  24. \&
  25. .sp 15
  26. .ps 9
  27. .nr PS 9
  28. .LP
  29. Copyright \(co 1991 Network Computing Devices, Inc.
  30. .LP
  31. Permission to use, copy, modify, distribute, and sell this
  32. documentation for any purpose is hereby granted without fee,
  33. provided that the above copyright notice and this permission
  34. notice appear in all copies.  Network Computing Devices, Inc.
  35. makes no representations about the suitability for any purpose
  36. of the information in this document.  This documentation is
  37. provided ``as is'' without express or implied warranty.
  38. .ps 11
  39. .nr PS 11
  40. .bp 1
  41. .EH '\fBX Font Service Protocol\fP''\fBX11, Release 5\fP'
  42. .OH '\fBX Font Service Protocol\fP''\fBX11, Release 5\fP'
  43. .EF ''\fB % \fP''
  44. .OF ''\fB % \fP''
  45. .NH 1
  46. Introduction
  47. .XS
  48. \*(SN Introduction
  49. .XE
  50. .LP
  51. The management of fonts in large, heterogeneous environments is one of the
  52. hardest aspects of using the X Window System.*
  53. .FS
  54. *X Window System is a trademark of the Massachusetts Institute of 
  55. Technology.
  56. .FE
  57. Multiple formats and the lack of
  58. a consistent mechanism for exporting font data to all displays on a network
  59. prevent the transparent use of applications across different display platforms.
  60. The X Font Service protocol is designed to address this and other issues, with
  61. specific emphasis on the needs of the core X protocol.  Upward-compatible
  62. changes (typically in the form of new requests) are expected as consensus is
  63. reached on new features (particularly outline font support).
  64. .LP
  65. Currently, most X displays use network file protocols such as NFS and TFTP to
  66. obtain raw font data which they parse directly.  Since a common binary format
  67. for this data doesn't exist, displays must be able to interpret a variety of
  68. formats if they are to be used with different application hosts.  This leads to
  69. wasted code and data space and a loss of interoperability as displays are used
  70. in unforeseen environments.
  71. .LP
  72. By moving the interpretation of font data out of the X server into a separate
  73. service on the network, these problems can be greatly reduced.  In addition,
  74. new technologies, such as dynamically generating bitmaps from scaled or outline
  75. fonts, can be provided to all displays transparently.  For horizontal text,
  76. caching techniques and increased processor power can potentially make
  77. rasterization more efficient on large, centralized hosts than on individual
  78. displays.
  79. .LP
  80. Each font server provides sets of fonts that may be listed and queried for
  81. header, property, glyph extents, and bitmap information.  This data is
  82. transmitted over the network using a binary format (with variations to support
  83. different bit- and byte-orders) designed to minimize the amount of processing
  84. required by the display.  Since the font server, rather than the display, is
  85. responsible for parsing the raw font data, new formats can be used by all
  86. displays by modifying a single font server.
  87. .LP
  88. From the user's point of view, font servers are simply a new type of name in
  89. the X font path.  Network name services allow descriptive names (such as
  90. DEPARTMENT-FONTS or APPLICATION-FONTS) to be translated into proper network
  91. addresses.  X displays send requests to and read replies from the font server
  92. rather than reading directly from files.  Since the X Font Service protocol is
  93. designed to allow subsets of the font data to be requested, displays may easily
  94. implement a variety of strategies for fine-grained demand-loading of glyphs.
  95. .NH 1
  96. Architectural Model
  97. .XS
  98. \*(SN Architectural Model
  99. .XE
  100. .LP
  101. In this document, the words ``client'' and ``server'' refer to the consumer and
  102. provider of a font, respectively, unless otherwise indicated.  It is important
  103. to note that in this context, the X server is also a font client.
  104. .LP
  105. The X Font Service protocol does not require any changes to the core X protocol
  106. or to any applications.  To the user, font servers are simply additional types
  107. of font path elements.  As such, X servers may connect to multiple font
  108. servers, as shown in Figure 2.1.  Although the font protocol is geared towards
  109. the X Window System, it may be also used by other consumers of font data (such
  110. as printer drivers).
  111. .DS
  112. .ft C
  113.  +--------+              +---------------+
  114.  |   X1   |--------------|               |
  115.  | Server |              |  Font Server  |
  116.  +--------+      +-------|      1        |
  117.                  |       +---------------+
  118.  +--------+      |
  119.  |   X2   |------+       +---------------+
  120.  | Server |--------------|               |
  121.  +--------+              |  Font Server  |
  122.                  +-------|      2        |
  123. +---------+      |       +---------------+
  124. |  other  |      |
  125. | clients |------+
  126. +---------+
  127. .ft
  128. .DE 
  129. .ce
  130. Figure \*(SN1:  Connecting to a Font Server
  131. .LP 
  132. Clients communicate with the font server using the request/reply/event model
  133. over any mutually-understood virtual stream connection (such as TCP/IP, DECnet,*
  134. .FS
  135. *DECnet is a trademark of Digital Equipment Corporation.
  136. .FE
  137. etc.).  Font servers are responsible for providing data in the bit and byte
  138. orders requested by the client.  The set of requests and events provided in the
  139. first version of the X Font Service protocol is limited to supporting the needs
  140. of the bitmap-oriented core X Window System protocol.  Extensions are expected
  141. as new needs evolve.
  142. .LP
  143. A font server reads raw font data from a variety of sources (possibly
  144. including other font servers) and converts it into a common format that is
  145. transmitted to the client using the protocol described in Section 4.  New font
  146. formats are handled by adding new converters to a font server, as shown in
  147. Figure 2.2.
  148. .DS
  149. .ft C
  150.                 +------------+
  151.                 |   client   |
  152.                 | (X server) |
  153.                 +------------+
  154.                       |
  155.                    network  
  156.                       |
  157. +--------------------------------------------+
  158. |                                            |
  159. |                font server 1               |
  160. |                                            |
  161. +-----+-----+-----+-----+----+-----+---+-----+
  162. | bdf | snf | pcf | atm | f3 | dwf | | | ... |
  163. +-----+-----+-----+-----+----+-----+-|-+-----+
  164.                                      |
  165.                                   network
  166.                                      |
  167.                                +----------+
  168.                                |   font   |
  169.                                | server 2 |
  170.                                +----------+
  171. .ft
  172. .DE
  173. .ce
  174. Figure \*(SN2:  Where Font Data Comes From
  175. .LP
  176. The server may choose to provide named sets of fonts called ``catalogues.''
  177. Clients may specify which of the sets should be used in listing or opening a
  178. font.
  179. .LP
  180. An event mechanism similar to that used in the X protocol is provided for
  181. asynchronous notification of clients by the server.
  182. .LP
  183. Clients may provide authorization data for the server to used in determining
  184. (according to the server's licensing policy) whether or not access should be
  185. granted to particular fonts.  This is particularly useful for clients whose
  186. authorization changes over side (such as an X server that can verify the
  187. identity of the user).
  188. .LP
  189. Implementations that wish to provide additional requests or events may use the
  190. extension mechanism.  Adding to the core font service protocol (with the
  191. accompanying change in the major or minor version numbers) is reserved to the X
  192. Consortium.
  193. .NH 1
  194. Font Server Naming
  195. .XS
  196. \*(SN Font Server Naming
  197. .XE
  198. .LP
  199. Font clients that expose font server names to the user are encouraged to
  200. provide ways of naming font servers symbolically (e.g. DEPARTMENT-FONTS).
  201. However, for environments that lack appropriate name services
  202. transport-specific names are necessary.  Since these names do occur in the
  203. protocol, clients and servers should support at least the applicable formats
  204. described below.  Formats for additional transports may be registered with the
  205. MIT X Consortium.
  206. .NH 2
  207. TCP/IP Names
  208. .XS
  209. \*(SN TCP/IP Names
  210. .XE
  211. .LP
  212. The following syntax should be used for TCP/IP names:
  213. .DS
  214.     <TCP name>  ::=  "tcp/" <hostname>":" <ipportnumber> ["/" <cataloguelist>]
  215. .DE
  216. where <hostname> is either symbolic (such as expo.lcs.mit.edu) or numeric
  217. decimal (such as 18.30.0.212).  The <ipportnumber> is the port on which the
  218. font server is listening for connections.  The <cataloguelist> string at
  219. the end is optional and specifies a plus-separated list of catalogues
  220. that may be requested.  For example:
  221. .DS
  222.     tcp/expo.lcs.mit.edu:8012/available+special
  223.     tcp/18.30.0.212:7890
  224. .DE
  225. .NH 2
  226. DECnet Names
  227. .XS
  228. \*(SN DECnet Names
  229. .XE
  230. .LP
  231. The following syntax should be used for DECnet names:
  232. .DS
  233.     <DECnet name>  ::=  "decnet/" <nodename> "::font$" <objname>
  234.             ["/" <cataloguelist>]
  235. .DE
  236. where <nodename> is either symbolic (such as SRVNOD) or the numeric decimal
  237. form of the DECnet address (such as 44.70).  The <objname> is normal,
  238. case-insensitive DECnet object name.  The <cataloguelist> string at the end is
  239. optional and specifies a plus-separated list of catalogues that may be
  240. requested.  For example:
  241. .DS
  242.     DECNET/SRVNOD::FONT$DEFAULT/AVAILABLE
  243.     decnet/44.70::font$other
  244. .DE
  245. .NH 1
  246. Protocol
  247. .XS
  248. \*(SN Protocol
  249. .XE
  250. .LP
  251. The protocol described below uses the request/reply/error model and is
  252. specified using the same conventions outlined in Section 2 of the core X Window
  253. System protocol [1]:
  254. .IP \(bu 5
  255. Data type names are spelled in upper case with no word separators, 
  256. as in:  FONTID
  257. .IP \(bu 5
  258. Alternate values are capitalized with no word separators, 
  259. as in:  MaxWidth
  260. .IP \(bu 5
  261. Structure element declarations are in lower case with hyphens
  262. as word separators, as in:  byte-order-msb
  263. .NT
  264. Structure element names are referred to in
  265. upper case (e.g. BYTE-ORDER-MSB) when used in
  266. descriptions to set them off from the surrounding
  267. text.  When this document is typeset they will be
  268. printed in lower case in a distinct font.
  269. .NE
  270. .IP \(bu 5
  271. Type declarations have the form ``name: type'', 
  272. as in:  CARD8: 8-bit byte
  273. .IP \(bu 5
  274. Comma-separated lists of alternate values are enclosed in
  275. braces, as in:  { Min, MaxWidth, Max }
  276. .IP \(bu 5
  277. Comma-separated lists of structure elements are enclosed in
  278. brackets, as in:  [ byte1: CARD8, byte2: CARD8 ]
  279. .LP
  280. A type with a prefix ``LISTof'' represents a counted list of
  281. elements of that type, as in:  LISTofCARD8
  282. .NH 2
  283. Data Types
  284. .XS
  285. \*(SN Data Types
  286. .XE
  287. .LP
  288. The following data types are used in the core X Font Server protocol:
  289. .LP
  290. ACCESSCONTEXT:    ID
  291. .IP
  292. This value is specified in the CreateAC request as the identifier
  293. to be used when referring to a particular AccessContext resource
  294. within the server.  These resources are used by the server to
  295. store client-specified authorization information.  This
  296. information may be used by the server to determine whether or not
  297. the client should be granted access to particular font data.
  298. .sp
  299. In order to preserve the integrity of font licensing being performed by
  300. the font server, care must be taken by a client to properly represent the
  301. identity of the true user of the font.  Some font clients will in fact
  302. be servers (for example, X servers) requesting fonts for their own clients.
  303. Other font clients may be doing work on behalf of a number of different
  304. users over time (for example, print spoolers).
  305. .sp
  306. .PN AccessContexts 
  307. must be created (with 
  308. .PN CreateAC ) 
  309. and switched among (with
  310. .PN SetAuthorization )
  311. to represent all of these ``font users'' properly.
  312. .LP
  313. ALTERNATESERVER:  [ name:  STRING8, 
  314. .br
  315.                                            subset:  BOOL ]
  316. .IP
  317. This structure specifies the NAME, encoded in ISO 8859-1 according
  318. to Section 3, of another font server that may be useful as a
  319. substitute for this font server.  The SUBSET field indicates
  320. whether or not the alternate server is likely to only contain a
  321. subset of the fonts available from this font server.  This
  322. information is returned during the initial connection setup and
  323. may be used by the client to find a backup server in case of
  324. failure.
  325. .LP
  326. AUTH:  [ name:  STRING8, 
  327. .br
  328.                 data:  LISTofBYTE ]
  329. .IP
  330. This structure specifies the name of an authorization protocol and
  331. initial data for that protocol.  It is used in the authorization
  332. negotiation in the initial connection setup and in the CreateAC
  333. request.
  334. .ne 5
  335. .LP
  336. BITMAPFORMAT:  
  337. .IP
  338. CARD32 containing the following fields defined by the
  339. sets of values given further below 
  340. .RS
  341. .DS
  342. .TA .75i .75i .75i .75i
  343. [
  344.      byte-order-msb:        1 bit, 
  345.     bit-order-msb:        1 bit,
  346.     image-rect:            2 bits { Min,
  347.                      MaxWidth, 
  348.                      Max },
  349.     zero-pad:            4 bits,
  350.     scanline-pad:        2 bits { ScanlinePad8, 
  351.                      ScanlinePad16, 
  352.                      ScanlinePad32,
  353.                      ScanlinePad64 },
  354.     zero-pad:            2 bits,
  355.     scanline-unit:        2 bits { ScanlineUnit8, 
  356.                      ScanlineUnit16,
  357.                      ScanlineUnit32,
  358.                      ScanlineUnit64 },
  359.     zero-pad:            2 bits,
  360.     zero-pad:            16 bits,
  361. ]
  362. .DE
  363. .RE
  364. This structure specifies how glyph images are transmitted in
  365. response to 
  366. .PN QueryXBitmaps8 
  367. and 
  368. .PN QueryXBitmaps16 
  369. requests.
  370. .sp
  371. If the BYTE-ORDER-MSB bit (1 << 0) is set, the Most Significant
  372. Byte of each scanline unit is returned first.  Otherwise, the
  373. Least Significant Byte is returned first.
  374. .sp
  375. If the BIT-ORDER-MSB bit (1 << 1) is set, the left-most bit in
  376. each glyph scanline unit is stored in the Most Significant Bit of
  377. each transmitted scanline unit.  Otherwise, the left-most bit is
  378. stored in the Least Significant Bit.
  379. .sp
  380. The IMAGE-RECT field specifies a rectangle of pixels within the
  381. glyph image.  It contains one of the following alternate values:
  382. .RS
  383. .DS
  384.  
  385.     ImageRectMin        (0 << 2)
  386.     ImageRectMaxWidth    (1 << 2)
  387.     ImageRectMax        (2 << 2)
  388. .DE
  389. .RE
  390. For a glyph with extents XCHARINFO in a font with header information
  391. XFONTINFO, the IMAGE-RECT values have the following meanings:
  392. .RS
  393. .in +5n
  394. .IP 
  395. .PN ImageRectMin -
  396. This refers to the minimal bounding rectangle 
  397. surrounding the inked pixels in the glyph.  This is the 
  398. most compact representation.  The edges of the rectangle
  399. are:
  400. .RS
  401. .DS
  402. .TA .75i .75i .75i .75i
  403.         left:    XCHARINFO.LBEARING
  404.         right:    XCHARINFO.RBEARING
  405.         top:    XCHARINFO.ASCENT
  406.         bottom:    XCHARINFO.DESCENT
  407. .DE
  408. .RE
  409. .IP 
  410. .PN ImageRectMaxWidth - 
  411. This refers to the scanlines between the 
  412. glyph's ascent and descent, padded on the left to the minimum 
  413. left-bearing (or 0, whichever is less) and on the right to 
  414. the maximum right-bearing (or logical-width, whichever is 
  415. greater).  All glyph images share a common horizontal
  416. origin.  This is a combination of ImageRectMax in the
  417. horizontal direction and ImageRectMin in the vertical 
  418. direction.  The edges of the rectangle are:
  419. .RS
  420. .DS
  421. .TA .75i .75i .75i .75i
  422. left:    min (XFONTINFO.MIN-BOUNDS.LBEARING, 0)
  423. right:    max (XFONTINFO.MAX-BOUNDS.RBEARING,
  424.              XFONTINFO.MAX-BOUNDS.WIDTH)
  425. top:        XCHARINFO.ASCENT
  426. bottom:    XCHARINFO.DESCENT
  427. .DE
  428. .RE
  429. .IP
  430. ImageRectMax - This refers to all scanlines, from the maximum 
  431. ascent (or the font ascent, whichever is greater) to the 
  432. maximum descent (or the font descent, whichever is greater),
  433. padded to the same horizontal extents as MaxWidth.
  434. All glyph images have the same sized bitmap and share a
  435. common origin.  This is the least compact representation, 
  436. but may be the easiest or most efficient (particularly for 
  437. character cell fonts) for some clients to use.  The edges of 
  438. the rectangle are:
  439. .RS
  440. .DS
  441. .TA .75i .75i .75i .75i
  442. left:    min (XFONTINFO.MIN-BOUNDS.LBEARING, 0)
  443. right:    max (XFONTINFO.MAX-BOUNDS.RBEARING,
  444.         XFONTINFO.MAX-BOUNDS.WIDTH)
  445. top:    max (XFONTINFO.FONT-ASCENT, 
  446.         XFONTINFO.MAX-BOUNDS.ASCENT)
  447. bottom:    max (XFONTINFO.FONT-DESCENT,
  448.         XFONTINFO.MAX-BOUNDS.DESCENT)
  449. .DE
  450. .RE
  451. The SCANLINE-PAD field specifies the number of bits (8, 16, 32,
  452. or 64) to which each glyph scanline is padded before transmitting.
  453. It contains one of the following alternate values:
  454. .RS
  455. .DS
  456. .TA .75i .75i .75i .75i
  457.     ScanlinePad8        (0 << 8)
  458.     ScanlinePad16        (1 << 8)
  459.     ScanlinePad32        (2 << 8)
  460.     ScanlinePad64        (3 << 8)
  461. .DE
  462. .RE
  463. The SCANLINE-UNIT field specifies the number of bits (8, 16, 32,
  464. or 64) that should be treated as a unit for swapping.  This value
  465. must be less than or equal to the number of bits specified by the
  466. SCANLINE-PAD.  It contains one of the following alternate values:
  467. .RS
  468. .DS
  469. .TA .75i .75i .75i .75i
  470.     ScanlineUnit8        (0 << 12)
  471.     ScanlineUnit16        (1 << 12)
  472.     ScanlineUnit32        (2 << 12)
  473.     ScanlineUnit64        (3 << 12)
  474. .DE
  475. .RE
  476. BITMAPFORMATs are byte-swapped as CARD32s.  All unspecified bits
  477. must be zero.
  478. .sp
  479. Use of an invalid BITMAPFORMAT causes a Format error to 
  480. be returned.
  481. .in -5n
  482. .RE
  483. .LP
  484. BITMAPFORMATMASK:    CARD32 mask
  485. .IP
  486. This is a mask of bits representing the fields in a BITMAPFORMAT:
  487. .RS
  488. .DS
  489. .TA .75i .75i .75i .75i
  490.     ByteOrderMask        (1 << 0)
  491.     BitOrderMask        (1 << 1)
  492.     ImageRectMask        (1 << 2)
  493.     ScanlinePadMask        (1 << 3)
  494.     ScanlineUnitMask        (1 << 4)
  495. .DE
  496. .RE
  497. Unspecified bits are required to be zero or else a Format error
  498. is returned.
  499. .LP
  500. BOOL:  CARD8
  501. .IP
  502. This is a boolean value containing one of the following alternate
  503. values:
  504. .RS
  505. .DS
  506. .TA .75i .75i .75i .75i
  507.  
  508.     False            0
  509.     True            1
  510. .DE
  511. .RE
  512. .LP
  513. BYTE:  8-bit value
  514. .IP
  515. This is an unsigned byte of data whose encoding 
  516. is determined by the context in which it is used.
  517. .sp 12p
  518. .LP
  519. CARD8:  8-bit unsigned integer
  520. .sp 12p
  521. .LP
  522. CARD16:  16-bit unsigned integer
  523. .sp 12p
  524. .LP
  525. CARD32:  32-bit unsigned integer
  526. .IP
  527. These are unsigned numbers.  The latter two are byte-swapped when
  528. the server and client have different byte orders.
  529. .sp 12p
  530. .LP
  531. CHAR2B:  [ byte1, byte2:  CARD8 ]
  532. .IP
  533. This structure specifies an individual character code within
  534. either a 2-dimensional matrix (using BYTE1 and BYTE2 as the row
  535. and column indices, respectively) or a vector (using BYTE1 and
  536. BYTE2 as most- and least-significant bytes, respectively).  This
  537. data type is treated as a pair of 8-bit values and is never
  538. byte-swapped.  Therefore, the client should always transmit BYTE1
  539. first.
  540. .sp 12p
  541. .LP
  542. EVENTMASK:  CARD32 mask
  543. .IP
  544. This is a mask of bits indicating which of an extension's (or the
  545. core's) maskable events the client would like to receive.  Each
  546. bit indicates one or more events, and a bit value of one indicates
  547. interest in a corresponding set of events.  The following bits are
  548. defined for event masks specified for the core protocol (i.e. an
  549. EXTENSION-OPCODE of zero in 
  550. .PN SetEventMask 
  551. and 
  552. .PN GetEventMask 
  553. requests):
  554. .RS
  555. .DS
  556. .TA .75i .75i .75i .75i
  557.  
  558.     CatalogueListChangeMask        (1 << 0)
  559.     FontListChangeMask            (1 << 1)
  560. .DE
  561. .RE
  562. If 
  563. .PN CatalogueListChangeMask 
  564. is set, client is interested in
  565. receiving 
  566. .PN CatalogueListNotify 
  567. events.  If 
  568. .PN FontListChangeMask 
  569. is set, the client is interested in 
  570. receiving 
  571. .PN FontListNotify 
  572. events.
  573. .sp
  574. Extensions that provide additional events may define their own
  575. event masks.  These event masks have their own scope and may use
  576. the same bit values as the core or other extensions.
  577. .sp
  578. All unused bits must be set to zero.  In 
  579. .PN SetEventMask 
  580. requests, if
  581. any bits are set that are not defined for the extension (or core)
  582. for which this EVENTMASK is intended (according to the EXTENSION-
  583. OPCODE given in the 
  584. .PN SetEventMask 
  585. request), an 
  586. .PN EventMask 
  587. error is generated.
  588. .sp
  589. This value is swapped as a CARD32.
  590. .LP
  591. FONTID:    ID
  592. .IP
  593. This is specified by the client in the request 
  594. .PN OpenBitmapFont 
  595. as the identifier to be used when referring to a particular open
  596. font.
  597. .LP
  598. ID:  CARD32
  599. .IP
  600. This is a 32-bit value in which the top 3 bits must be clear, and
  601. at least 1 other bit must be set (yielding a range of 1 through
  602. 2^29-1).  It is specified by the client to represent objects in
  603. the server.  Identifiers are scoped according to their type are
  604. private to the client; thus, the same identifier may be used for
  605. both a FONTID and an ACCESSCONTEXT as well as by multiple clients.
  606. .sp
  607. An ID of zero is referred to as None.
  608. .LP
  609. INT8:  8-bit signed integer
  610. .LP
  611. INT16:  16-bit signed integer
  612. .LP
  613. INT32:  32-bit signed integer
  614. .IP
  615. These are signed numbers.  The latter two are byte-swapped when
  616. the client and server have different byte orders.
  617. .LP
  618. OFFSET32:        [  position:    CARD32,
  619. .br
  620.               length:    CARD32 ]
  621. .IP
  622. This structure indicates a position and length within a block of
  623. data.
  624. .LP
  625. PROPINFO:    [ offsets:        LISTofPROPOFFSET,
  626. .br
  627.               data:            LISTofBYTE ]
  628. .IP
  629. This structure describes the list of properties provided by a
  630. font.  Strings for all of the properties names and values are
  631. stored within the data block and are located using a table of
  632. offsets and lengths.
  633. .sp
  634. This structure is padded to 32-bit alignment.
  635. .LP
  636. PROPOFFSET:    [ name:        OFFSET32,
  637. .br
  638.               value:        OFFSET32,
  639. .br
  640.               type:        CARD8,
  641. .br
  642.               zero-pad3:        BYTE, BYTE, BYTE ]
  643. .IP
  644. This structure specifies the position, length, and type of 
  645. of data for a property.
  646. .sp
  647. The NAME field specifies the position and length (which must be
  648. greater than zero) of the property name relative to the beginning
  649. of the PROPINFO.DATA block for this font.  The interpretation of
  650. the position and length of the VALUE field is determined by the
  651. TYPE field, which contains one of the following alternate values:
  652. .RS
  653. .DS
  654. .TA .75i .75i .75i .75i
  655.     String            0
  656.     Unsigned        1
  657.     Signed        2
  658. .DE
  659. .RE
  660. .IP
  661. which have the following meanings:
  662. .RS
  663. .in +5n
  664. .IP String
  665. .br
  666. This property contains a counted string of bytes.  The
  667. data is stored in the PROPINFO.DATA block beginning at 
  668. relative byte VALUE.POSITION (beginning with zero), extending
  669. for VALUE.LENGTH (at least zero) bytes.
  670. .IP Unsigned
  671. This property contains a unsigned, 32-bit number stored
  672. as a CARD32 in VALUE.POSITION (VALUE.LENGTH is zero).
  673. .IP Signed
  674. .br
  675. This property contains a signed, 32-bit number stored as
  676. an INT32 in VALUE.POSITION (VALUE.LENGTH is zero).
  677. .in -5n
  678. .RE
  679. .sp
  680. This structure is zero-padded to 32-bit alignment.
  681. .LP
  682. RANGE:    [ min-char, max-char:    CHAR2B ]
  683. .IP
  684. This structure specifies a range of character codes.  A single
  685. character is represented by MIN-CHAR equals MAX-CHAR.  If the
  686. linear interpretation of MAX-CHAR is less than that of MIN-CHAR,
  687. or if MIN-CHAR is less than the font's
  688. XFONTINFO.CHAR-RANGE.MIN-CHAR, or if MAX-CHAR is greater than the
  689. font's XFONTINFO.CHAR-RANGE.MAX-CHAR, the range is invalid.
  690. .LP
  691. RESOLUTION:    [ x-resolution:        CARD16,
  692. .br
  693.               y-resolution:        CARD16,
  694. .br
  695.               decipoint-size:        CARD16 ]
  696. .IP
  697. This structure specifies resolution and point size to be used in
  698. resolving partially-specified scaled font names.  The X-RESOLUTION
  699. and Y-RESOLUTION are measured in pixels-per-inch and must be
  700. greater than zero.  The DECIPOINT-SIZE is the preferred font
  701. size, measured in tenths of a point, and must be greater than zero.
  702. .LP
  703. STRING8:        LISTofCARD8
  704. .IP
  705. This is a counted list of 1-byte character codes, typically
  706. encoded in ISO 8859-1.  A character code ``c'' is equivalent to a
  707. CHAR2B structure whose BYTE1 is zero and whose BYTE2 is ``c''.
  708. .LP
  709. TIMESTAMP:    CARD32
  710. .IP
  711. This is the number of milliseconds that have passed since a server-
  712. dependent origin.  It is provided in errors and events and is 
  713. permitted to wrap.
  714. .LP
  715. XCHARINFO:    [ lbearing, rbearing:    INT16,
  716. .br
  717.               width:            INT16,
  718. .br
  719.               ascent, descent:        INT16,
  720. .br
  721.               attributes:            CARD16 ]
  722. .IP
  723. This structure specifies the ink extents and horizontal escapement
  724. (also known as the set- or logical width) of an individual
  725. character.  The first five values represent directed distances in
  726. a coordinate system whose origin is aligned with the lower-left
  727. edge of the left-most pixel of the glyph baseline (i.e. the
  728. baseline falls between two pixels as shown in Figure 3-1 of the
  729. ``Bitmap Distribution Format 2.1'' Consortium standard [2]).
  730. .sp
  731. The LBEARING field specifies the directed distance measured to the
  732. right from the origin to the left edge of the left-most inked
  733. pixel in the glyph.
  734. .sp
  735. The RBEARING field specifies the directed distance (measured to
  736. the right) from the origin to the right edge of the right-most
  737. inked pixel in the glyph.
  738. .sp
  739. The WIDTH field specifies the directed distance (measured to the
  740. right) from the origin to the position where the next character
  741. should appear (called the ``escapement point'').  This distance
  742. includes any whitespace used for intercharacter padding and is
  743. also referred to as the ``logical width'' or ``horizontal
  744. escapement.''
  745. .sp
  746. The ASCENT field specifies the directed distance (measured up)
  747. from the baseline to the top edge of the top-most inked pixel
  748. in the glyph.
  749. .sp
  750. The DESCENT field specifies the directed distance (measured
  751. down) from the baseline to the bottom edge of the bottom-most
  752. inked pixel.
  753. .sp
  754. The ATTRIBUTES field specifies glyph-specific information that
  755. is passed through the application.  If this value is not being
  756. used, it should be zero.
  757. .sp
  758. The ink bounding box of a glyph is defined to be the smallest 
  759. rectangle that encloses all of the inked pixels.  This box has
  760. a width of RBEARING - LBEARING pixels and a height of 
  761. ASCENT + DESCENT pixels.
  762. .LP
  763. XFONTINFO:    [ flags:            CARD32,
  764. .br
  765.               drawing-direction:    { LeftToRight, RightToLeft }
  766. .br
  767.               char-range:        RANGE,
  768. .br
  769.               default-char:        CHAR2B,
  770. .br
  771.               min-bounds:        XCHARINFO,
  772. .br
  773.               max-bounds:        XCHARINFO,
  774. .br
  775.               font-ascent:        INT16,
  776. .br
  777.               font-descent:        INT16,
  778. .br
  779.               properties:            PROPINFO ]
  780. .IP
  781. This structure specifies attributes related to the font as a
  782. whole.
  783. .sp
  784. The FLAGS field is a bit mask containing zero or more of the
  785. following boolean values (unspecified bits must be zero):
  786. .RS
  787. .DS
  788. .TA .75i .75i .75i .75i
  789.     AllCharactersExist    (1 << 0)
  790.     InkInside            (1 << 1)
  791.     HorizontalOverlap        (1 << 2)
  792. .DE
  793. .RE
  794. .IP
  795. which have the following meanings:
  796. .RS
  797. .in +5n
  798. .IP AllCharactersExist
  799. If this bit is set, all of the characters
  800. in the range given by CHAR-RANGE have glyphs encoded in
  801. the font.  If this bit is clear, some of the characters
  802. may not have encoded glyphs.
  803. .IP InkInside
  804. If this bit is set, the inked pixels of each glyph 
  805. fall within the rectangle described by the font's ascent, 
  806. descent, origin, and the glyph's escapement point.  If
  807. this bit is clear, there may be glyphs whose ink extends 
  808. outside this rectangle.
  809. .IP HorizontalOverlap
  810. If this bit is set, the two ink bounding
  811. boxes (smallest rectangle enclosing the inked pixels) of 
  812. some pairs of glyphs in the font may overlap when displayed 
  813. side-by-side (i.e. the second character is imaged at the 
  814. escapement point of the first) on a common baseline.  If
  815. this bit is clear, there are no pairs of glyphs whose ink
  816. bounding boxes overlap.
  817. .in -5n
  818. .RE
  819. .IP
  820. The DRAWING-DIRECTION field contains a hint indicating whether
  821. most of the character metrics have a positive (or ``LeftToRight'') 
  822. logical width or a negative (``RightToLeft'') logical width.  It
  823. contains the following alternate values:
  824. .RS
  825. .DS
  826.  
  827.     LeftToRight        0
  828.     RightToLeft        1
  829. .DE
  830. .RE
  831. The CHAR-RANGE.MIN-CHAR and CHAR-RANGE.MAX-CHAR fields specify the
  832. first and last character codes that have glyphs encoded in this font.
  833. All fonts must have at least one encoded glyph (in which case the
  834. MIN-CHAR and MAX-CHAR are equal), but are not required to have glyphs
  835. encoded at all positions between the first and last characters.
  836. .sp
  837. The DEFAULT-CHAR field specifies the character code of the glyph
  838. that the client should substitute for unencoded characters.  Requests
  839. for extents or bitmaps for an unencoded character generate zero-filled
  840. metrics and a zero-length glyph bitmap, respectively.
  841. .sp
  842. The MIN-BOUNDS and MAX-BOUNDS fields contain the minimum and maximum
  843. values of each of the extents field of all encoded characters in the
  844. font (i.e. non-existent characters are ignored).
  845. .sp
  846. The FONT-ASCENT and FONT-DESCENT fields specify the font designer's
  847. logical height of the font, above and below the baseline,
  848. respectively.  The sum of the two values is often used as the
  849. vertical line spacing of the font.  Individual glyphs are permitted
  850. to have ascents and descents that are greater than these values.
  851. .sp
  852. The PROPERTIES field contains the property data associated with
  853. this font.
  854. .sp
  855. This structure is padded to 32-bit alignment.
  856. .NH 2
  857. Requests
  858. .XS
  859. \*(SN Requests
  860. .XE
  861. .LP
  862. This section describes the requests that may be sent by the client and the
  863. replies or errors that are generated in response.  Versions of the protocol
  864. with the same major version are required to be upward-compatible.
  865. .LP
  866. Every request on a given connection is implicitly assigned a sequence number,
  867. starting with 1, that is used in replies, error, and events.  Servers are
  868. required to generate replies and errors in the order in which the corresponding
  869. requests are received.  Servers are permitted to add or remove fonts to the
  870. list visible to the client between any two requests, but requests must be
  871. processed atomically.  Each request packet is at least 4 bytes long and
  872. contains the following fields:
  873. .RS
  874. .DS
  875.     major-opcode:            CARD8
  876.     minor-opcode:            CARD8
  877.     length:                CARD16
  878. .DE
  879. .RE
  880. The MAJOR-OPCODE specifies which core request or extension package this packet
  881. represents.  If the MAJOR-OPCODE corresponds to a core request, the
  882. MINOR-OPCODE contains 8 bits of request-specific data.  Otherwise, the
  883. MINOR-OPCODE specifies which extension request this packet represents.  The
  884. LENGTH field specifies the number of 4-byte units contained within the packet
  885. and must be at least one.  If this field contains a value greater than one it
  886. is followed by (LENGTH - 1) * 4 bytes of request-specific data.  Unless
  887. otherwise specified, unused bytes are not required to be zero.
  888. .LP
  889. If a request packet contains too little or too much data, the server returns
  890. a Length error.  If the server runs out of internal resources (such as
  891. memory) while processing a request, it returns an Alloc error.  If a server is
  892. deficient (and therefore non-compliant) and is unable to process a request, it
  893. may return an Implementation error.  If a client uses an extension request
  894. without previously having issued a 
  895. .PN QueryExtension 
  896. request for that extension, the server responds with a 
  897. .PN Request 
  898. error.  If the server encounters a request
  899. with an unknown MAJOR-OPCODE or MINOR-OPCODE, it responds with a 
  900. .PN Request 
  901. error.
  902. At most one error is generated per request.  If more than one error condition
  903. is encountered in processing a requests, the choice of which error is returned
  904. is server-dependent.
  905. .LP
  906. Core requests have MAJOR-OPCODE values between 0 and 127, inclusive.  Extension
  907. requests have MAJOR-OPCODE values between 128 and 255, inclusive, that are
  908. assigned by by the server.  All MINOR-OPCODE values in extension requests are
  909. between 0 and 255, inclusive.
  910. .LP
  911. Each reply is at least 8 bytes long and contains the following fields:
  912. .RS
  913. .DS
  914. .TA .75i .75i .75i .75i
  915.  
  916.     type:                CARD8 value of 0
  917.     data-or-unused:        CARD8
  918.     sequence-number:        CARD16
  919.     length:            CARD32
  920. .DE
  921. .RE
  922. The TYPE field has a value of zero.  The DATA-OR-UNUSED field may be used to
  923. encode one byte of reply-specific data (see Section 5.2 on request encoding).
  924. The least-significant 16 bits of the sequence number of the request that
  925. generated the reply are stored in the SEQUENCE-NUMBER field.  The LENGTH field
  926. specifies the number of 4-byte units in this reply packet, including the fields
  927. described above, and must be at least two.  If LENGTH is greater than two, the
  928. fields described above are followed by (LENGTH - 2) * 4 bytes of additional
  929. data.
  930. .LP
  931. Requests that have replies are described using the following syntax:
  932. .RS
  933. .DS
  934.  
  935.     RequestName
  936.         \fIarg1\fP\^:  type1
  937.         \fIarg2\fP\^:  type2
  938.         ...
  939.         \fIargN\fP\^:  typeN
  940.          =>
  941.        \fIresult1\fP\^:  type1
  942.         \fIresult2\fP\^:  type2
  943.         ...
  944.         \fIresultM\fP\^:  typeM
  945.  
  946.     Errors:  \fIkind1\fR, \fIkind2\fR ..., \fIkindK\fR
  947.  
  948.     Description
  949. .DE
  950. .RE
  951. If a request does not generate a reply, the``=>'' and result lines are
  952. omitted.  If a request may generate multiple replies, the ``=>'' is replaced by
  953. a ``=>+''.  In the authorization data exchanges in the initial connection setup
  954. and the CreateAC request, ``->'' indicates data sent by the client in response
  955. to data sent by the server.
  956. .LP
  957. The protocol begins with the establishment of a connection over a 
  958. mutually-understood virtual stream:
  959. .RS
  960. .DS
  961.  
  962.     open connection
  963.     byte-order:                    BYTE
  964.     client-major-protocol-version:        CARD16
  965.     client-minor-protocol-version:        CARD16
  966.     authorization-protocols:            LISTofAUTH
  967. .DE
  968. .RE
  969. The initial byte of the connection specifies the BYTE-ORDER in
  970. which subsequent 16-bit and 32-bit numeric values are to be
  971. transmitted.  The octal value 102 (ASCII uppercase `B')
  972. indicates that the most-significant byte is to be transmitted
  973. first; the octal value 154 (ASCII lowercase `l') indicates
  974. that the least-significant byte is to be transmitted first.
  975. If any other value is encountered the server closes the
  976. connection without any response.
  977. .IP
  978. The CLIENT-MAJOR-PROTOCOL-VERSION and
  979. CLIENT-MINOR-PROTOCOL-VERSION specify which version of the
  980. font service protocol the client would like to use.  If the
  981. client can support multiple versions, the highest version
  982. should be given.  This version of the protocol has a
  983. major version of 2 and a minor version of 0.
  984. .IP
  985. The AUTHORIZATION-PROTOCOLS contains a list of protocol names and
  986. optional initial data for which the client can provide
  987. information.  The server may use this to determine which
  988. protocol to use or as part of the initial exchange of
  989. authorization data.
  990. .RS
  991. .DS
  992. =>
  993. status:                    { Success, Continue, 
  994.                           Busy, Denied }
  995. server-major-protocol-version:        CARD16
  996. server-minor-protocol-version:        CARD16
  997. alternate-servers-hint:            LISTofALTERNATESERVER
  998. authorization-index:            CARD8
  999. authorization-data:            LISTofBYTE
  1000. .DE
  1001. .RE
  1002. The SERVER-MAJOR-PROTOCOL-VERSION and
  1003. SERVER-MINOR-PROTOCOL-VERSION specify the version of the font
  1004. service protocol that the server expects from the client.  If
  1005. the server supports the version specified by the client, this
  1006. version number should be returned.  If the client has
  1007. requested a higher version than is supported by the server,
  1008. the server's highest version should be returned.  Otherwise,
  1009. if the client has requested a lower version than is supported
  1010. by the server, the server's lowest version should be returned.
  1011. It is the client's responsibility to decide whether or not it
  1012. can match this version of the protocol.
  1013. .IP
  1014. The ALTERNATE-SERVERS-HINT is a list of other font servers
  1015. that may have related sets of fonts (determined by means
  1016. outside this protocol, typically by the system administrator).
  1017. Clients may choose to contact these font servers if the
  1018. connection is rejected or lost.
  1019. .IP
  1020. The STATUS field indicates whether the server accepted,
  1021. rejected, or would like more information about the connection.
  1022. It has one of the following alternate values:
  1023. .RS
  1024. .DS
  1025.  
  1026.         Success        0
  1027.         Continue        1
  1028.         Busy            2
  1029.         Denied        3
  1030. .DE
  1031. .RE
  1032. If STATUS is Denied, the server has rejected the client's
  1033. authorization information.  If STATUS is Busy, the server has
  1034. simply decided that it cannot provide fonts to this client at
  1035. this time (it may be able to at a later time).  In both cases,
  1036. AUTHORIZATION-INDEX is set to zero, no authorization-data is
  1037. returned, and the server closes the connection after sending
  1038. the data described so far.
  1039. .IP
  1040. Otherwise the AUTHORIZATION-INDEX is set to the index
  1041. (beginning with 1) into the AUTHORIZATION-PROTOCOLS list of
  1042. the protocol that the server will use for this connection.  If
  1043. the server does not want to use any of the given protocols,
  1044. this value is set to zero.  The AUTHORIZATION-DATA field is
  1045. used to send back authorization protocol-dependent data to the
  1046. client (such as a challenge, authentication of the server,
  1047. etc.).
  1048. .LP
  1049. If STATUS is Success, the following section of protocol is
  1050. omitted.  Otherwise, if STATUS is Continue, the server expects
  1051. more authorization data from the client (i.e. the connection
  1052. setup is not finished, so no requests or events may be sent):
  1053. .RS
  1054. .DS
  1055. ->
  1056. more-authorization-data:        STRING8
  1057. =>
  1058. status:                { Success, Continue, 
  1059.                       Busy, Denied }
  1060. more-authorization-data:        LISTofBYTE
  1061. .DE
  1062. .RE
  1063. The values in STATUS have the same meanings as described
  1064. above.  This section of protocol is repeated until the server
  1065. either accepts (sets STATUS to Success) or rejects (sets
  1066. STATUS to Denied or Busy) the connection.
  1067. .LP
  1068. Once the connection has been accepted and STATUS is Success,
  1069. an implicit AccessContext is created for the authorization
  1070. data and the protocol continues with the following data sent
  1071. from the server:
  1072. .RS
  1073. .DS
  1074. =>
  1075. remaining-length:            CARD32
  1076. maximum-request-length:    CARD16
  1077. release-number:            CARD32
  1078. vendor:                STRING8
  1079. .DE
  1080. .RE
  1081. The REMAINING-LENGTH specifies the length in 4-byte units of
  1082. the remaining data to be transmitted to the client.  The
  1083. MAXIMUM-REQUEST-LENGTH specifies the largest request size in
  1084. 4-byte units that is accepted by the server and must have a
  1085. value of at least 4096.  Requests with a length field larger
  1086. than this value are ignored and a Length error is returned.
  1087. The VENDOR string specifies the name of the manufacturer of
  1088. the font server.  The RELEASE-NUMBER specifies the particular
  1089. release of the server in a manufacturer-dependent manner.
  1090. .LP
  1091. After the connection is established and the setup information has been
  1092. exchanged, the client may issue any of requests described below:
  1093. .LP
  1094. .IN "NoOp" "" "@DEF@"
  1095. .PN NoOp
  1096. .IP
  1097. Errors:  Alloc
  1098. .IP
  1099. This request does nothing.  It is typically used in response 
  1100. to a 
  1101. .PN KeepAlive 
  1102. event.
  1103. .LP
  1104. .IN "ListExtensions" "" "@DEF@"
  1105. .PN ListExtensions
  1106. .LP
  1107.   =>
  1108. .IP
  1109. \fInames\fP\^:  LISTofSTRING8
  1110. .IP
  1111. Errors:  Alloc
  1112. .IP
  1113. This request returns the names of the extension packages
  1114. that are supported by the server.  Extension names are 
  1115. case-sensitive and are encoded in ISO 8859-1.
  1116. .LP
  1117. .IN "QueryExtension" "" "@DEF@"
  1118. .PN QueryExtension
  1119. .IP
  1120. \fIname\fP\^:  STRING8
  1121. .LP
  1122.   =>
  1123. .IP
  1124. \fIpresent\fP\^:  BOOL
  1125. .br
  1126. \fImajor-version\fP\^:  CARD16
  1127. .br
  1128. \fIminor-version\fP\^:  CARD16
  1129. .br
  1130. \fImajor-opcode\fP\^:  CARD8
  1131. .br
  1132. \fIfirst-event\fP\^:  CARD8
  1133. .br
  1134. \fInumber-events\fP\^:  CARD8
  1135. .br
  1136. \fIfirst-error\fP\^:  CARD8
  1137. .br
  1138. \fInumber-errors\fP\^:  CARD8
  1139. .IP
  1140. Errors:  
  1141. .PN Alloc
  1142. .IP
  1143. This request determines whether or not the extension package
  1144. specified by NAME (encoded in ISO 8859-1) is supported by the
  1145. server and that there is sufficient number of major opcode,
  1146. event, and error codes available.  If so, then PRESENT is set
  1147. to True, MAJOR-VERSION and MINOR-VERSION are set to the
  1148. respective major and minor version numbers of the protocol
  1149. that the server would prefer; MAJOR-OPCODE is set to the value
  1150. to use in extension requests; FIRST-EVENT is set to the value
  1151. of the first extension-specific event code or zero if the
  1152. extension does not have any events; NUMBER-EVENTS is set to
  1153. the number of new events that the event defines; FIRST-ERROR
  1154. is set to the value of the first extension-specific error code
  1155. or zero if the extension does not define any new errors; and
  1156. NUMBER-ERRORS is set to the number of new errors the extension
  1157. defines.
  1158. .sp
  1159. Otherwise, PRESENT is set to False and the remaining fields are
  1160. set to zero.
  1161. .sp
  1162. The server is free to return different values to different
  1163. clients.  Therefore, clients must use this request before
  1164. issuing any of the requests in the named extension package or
  1165. using the 
  1166. .PN SetEventMask request to express interest in any of
  1167. this extension's events.  Otherwise, a 
  1168. .PN Request 
  1169. error is returned.
  1170. .LP
  1171. .IN "ListCatalogues" "" "@DEF@"
  1172. .PN ListCatalogues
  1173. .IP
  1174. \fIpattern\fP\^:  STRING8
  1175. \fImax-names\fP\^:  CARD32
  1176. .LP
  1177.   =>+
  1178. .IP
  1179. \fIreplies-following-hint\fP\^:  CARD32
  1180. .br
  1181. \fInames\fP\^:     LISTofSTRING8
  1182. .IP
  1183. Errors:  
  1184. .PN Alloc
  1185. .IP
  1186. This request returns a list of at most MAX-NAMES names
  1187. of collections (called catalogues) of fonts that match
  1188. the specified PATTERN.  In the pattern (which is encoded
  1189. in ISO 8859-1), the `?' character (octal 77) matches any
  1190. single character; the `*' character (octal 52) matches
  1191. any series of zero or more characters; and alphabetic
  1192. characters match either upper- or lowercase.  The
  1193. returned NAMES are encoded in ISO 8859-1 and may contain
  1194. mixed character cases.
  1195. .sp
  1196. If PATTERN is of zero length or MAX-NAMES is equal to zero,
  1197. one reply containing a zero-length list of names is returned.
  1198. This may be used to synchronize the client with the server.
  1199. .sp
  1200. Servers are free to add or remove catalogues to the set returned by
  1201. .PN ListCatalogues
  1202. between any two requests.  This request is not
  1203. cumulative; repeated uses are processed in isolation and do
  1204. result in an iteration through the list.
  1205. .sp
  1206. To reduce the amount of buffering needed by the server, the
  1207. list of names may be split across several reply packets, so
  1208. long as the names arrive in the same order that they would
  1209. have appeared had they been in a single packet.  The
  1210. REPLIES-FOLLOWING-HINT field in all but the last reply
  1211. contains a positive value that specifies the number of
  1212. replies that are likely, but not required, to follow.  In the
  1213. last reply, which may contain zero or more names, this field
  1214. is set to zero.
  1215. .LP
  1216. .IN "SetCatalogues" "" "@DEF@"
  1217. .PN SetCatalogues
  1218. .IP
  1219. \fInames\fP\^:  LISTofSTRING8
  1220. .IP
  1221. Errors:  
  1222. .PN Alloc , 
  1223. .PN Name
  1224. .IP
  1225. This request sets the list of catalogues whose fonts should be
  1226. visible to the client.  The union of the fonts provided by
  1227. each of the named catalogues forms the set of fonts whose
  1228. names match patterns in 
  1229. .PN ListFonts , 
  1230. .PN ListFontsWithXInfo , 
  1231. and
  1232. .PN OpenBitmapFont 
  1233. requests.  The catalogue names are
  1234. case-insensitive and are encoded in ISO 8859-1.  A zero-length
  1235. list resets the client's catalogue list to the
  1236. server-dependent default.
  1237. .sp
  1238. If any of the catalogue names are invalid, a 
  1239. .PN Name 
  1240. error is returned and the request is ignored.
  1241. .LP
  1242. .IN "GetCatalogues" "" "@DEF@"
  1243. .PN GetCatalogues
  1244. .LP
  1245.    =>
  1246. .IP
  1247. \fInames\fP\^:  LISTofSTRING8
  1248. .IP
  1249. Errors:  
  1250. .PN Alloc
  1251. .IP
  1252. This request returns the current list of catalogue names
  1253. (encoded in ISO 8859-1) associated with the client.  These
  1254. catalogues determine the set of fonts that are visible
  1255. to 
  1256. .PN ListFonts , 
  1257. .PN ListFontsWithXInfo , 
  1258. and 
  1259. .PN OpenBitmapFont .  
  1260. A zero-length list indicates the server's default set of 
  1261. fonts.  Catalogue names are case-insensitive and may be
  1262. returned in mixed case.
  1263. .LP
  1264. .IN "SetEventMask" "" "@DEF@"
  1265. .PN SetEventMask
  1266. .IP
  1267. \fIextension-opcode\fP\^:  CARD8
  1268. .br
  1269. \fIevent-mask\fP\^:  EVENTMASK
  1270. .IP
  1271. Errors:
  1272. .PN EventMask ,
  1273. .PN Request
  1274. .IP
  1275. This request specifies the set of maskable events that the
  1276. extension indicated by EXTENSION-OPCODE (or zero for the core)
  1277. should generate for the client.  Event masks are limited in
  1278. scope to the extension (or core) for which they are defined,
  1279. so expressing interest in events from one or more extensions
  1280. requires multiple uses of this request.
  1281. .sp
  1282. The default event mask if 
  1283. .PN SetEventMask 
  1284. has not been called 
  1285. is zero, indicating no interest in any maskable events.  
  1286. Some events are not maskable and cannot be blocked.
  1287. .sp
  1288. If EXTENSION-OPCODE is not a valid extension opcode previously
  1289. returned by 
  1290. .PN QueryExtension 
  1291. or zero, a 
  1292. .PN Request 
  1293. error is
  1294. returned.  If EVENT-MASK contains any bits that do not
  1295. correspond to valid events for the specified extension (or
  1296. core), an 
  1297. .PN EventMask 
  1298. error is returned and the request is
  1299. ignored.
  1300. .LP
  1301. .IN "GetEventMask" "" "@DEF@"
  1302. .PN GetEventMask
  1303. .IP
  1304. \fIextension-opcode\fP\^:  CARD8
  1305. .LP
  1306.   =>
  1307. .IP
  1308. \fIevent-mask\fP\^:  EVENTMASK
  1309. .IP
  1310. Errors:
  1311. .PN Request
  1312. .IP
  1313. This request returns the set of maskable core events the
  1314. extension indicated by EXTENSION-OPCODE (or the core if zero)
  1315. should generate for the client.  Non-maskable events are
  1316. always sent to the client.
  1317.  
  1318. If EXTENSION-OPCODE is not a valid extension opcode 
  1319. previously returned by 
  1320. .PN QueryExtension 
  1321. or zero, a 
  1322. .PN Request
  1323. error is returned.
  1324. .LP
  1325. .IN "CreateAC" "" "@DEF@"
  1326. .PN CreateAC
  1327. .IP
  1328. \fIac\fP\^:  ACCESSCONTEXT
  1329. .br
  1330. \fIauthorization-protocols\fP\^:  LISTofAUTH
  1331. .LP
  1332.   =>
  1333. .IP
  1334. \fIstatus\fP\^:      { Success, Continue, Denied }
  1335.     authorization-index:        CARD8
  1336.     authorization-data:        LISTofBYTE
  1337. .IP
  1338. Errors:
  1339. .PN IDChoice
  1340. .IP
  1341. This request creates a new 
  1342. .PN AccessContext 
  1343. object within the
  1344. server containing the specified authorization data.  When
  1345. this 
  1346. .PN AccessContext
  1347. is selected by the client using the
  1348. .PN SetAuthorization 
  1349. request, the data may be used by the server
  1350. to determine whether or not the client should be granted
  1351. access to particular font information.
  1352. .sp
  1353. If STATUS is Denied, the server rejects the client's
  1354. authorization information and does not associate AC with any
  1355. valid 
  1356. .PN AccessContext .  
  1357. In this case, AUTHORIZATION-INDEX is set
  1358. to zero, and zero bytes of AUTHORIZATION-DATA is returned.
  1359. .sp
  1360. Otherwise, AUTHORIZATION-INDEX is set to the index (beginning
  1361. with 1) into the AUTHORIZATION-PROTOCOLS list of the protocol
  1362. that the server will use for this connection.  If the server
  1363. does not want to use any of the given protocols, this value is
  1364. set to zero.  The AUTHORIZATION-DATA field is used to send
  1365. back authorization protocol-dependent data to the client (such
  1366. as a challenge, authentication of the server, etc.).
  1367. .sp
  1368. If STATUS is Continue, the client is expected to continue
  1369. the request by sending the following protocol and receiving
  1370. the indicated response from the server.  This continues
  1371. until STATUS is set to either Success or Denied.
  1372. .RS
  1373. .DS
  1374.  
  1375.     ->
  1376.     more-authorization-data:        STRING8
  1377.     =>
  1378.     status:                    { Success, Continue, Denied }
  1379.     more-authorization-data:        LISTofBYTE
  1380. .DE
  1381. .RE
  1382. Once the connection has been accepted and STATUS is Success,
  1383. the request is complete.
  1384. .sp
  1385. If AC is not in the range [1..2^29-1] or is already associated 
  1386. with an access context, an IDChoice error is returned.
  1387. .LP
  1388. .IN "FreeAC" "" "@DEF@"
  1389. .PN FreeAC
  1390. .IP
  1391. \fIac\fP\^:  ACCESSCONTEXT
  1392. .IP
  1393. Errors:  
  1394. .PN AccessContext , 
  1395. .PN Alloc
  1396. .IP
  1397. This request indicates that the specified AC should no longer
  1398. be associated with a valid access context.  If AC is also the
  1399. current 
  1400. .PN AccessContext
  1401. (as set by the 
  1402. .PN SetAuthorization
  1403. request), an implicit 
  1404. .PN SetAuthorization
  1405. of None is done to
  1406. restore the 
  1407. .PN AccessContext
  1408. established for the initial
  1409. connection setup.  Operations on fonts that were opened under
  1410. AC are not affected.  The client may reuse the value of AC in
  1411. a subsequent 
  1412. .PN CreateAC 
  1413. request.
  1414. .sp
  1415. If AC isn't associated with any valid authorization previously
  1416. created by 
  1417. .PN CreateAC , an 
  1418. .PN AccessContext 
  1419. error is returned.
  1420. .LP
  1421. .IN "SetAuthorization" "" "@DEF@"
  1422. .PN SetAuthorization
  1423. .IP
  1424. \fIac\fP\^:  ACCESSCONTEXT
  1425. .IP
  1426. Errors:  
  1427. .PN AccessContext
  1428. .IP
  1429. This request sets the 
  1430. .PN AccessContext 
  1431. to be used for subsequent
  1432. requests (except for 
  1433. .PN QueryXInfo , 
  1434. .PN QueryXExtents8 ,
  1435. .PN QueryXExtents16 , 
  1436. .PN QueryXBitmaps8 , 
  1437. .PN QueryXBitmaps16 , 
  1438. and
  1439. .PN CloseFont 
  1440. which are done under the 
  1441. .PN AccessContext 
  1442. of the
  1443. corresponding
  1444. .PN  OpenBitmapFont ")."  
  1445. An AC of None restores the
  1446. .PN AccessContext 
  1447. established for the initial connection setup.
  1448. .sp
  1449. If AC is neither None nor a value associated with a valid
  1450. .PN AccessContext 
  1451. previously created by 
  1452. .PN CreateAC , 
  1453. an 
  1454. .PN AccessContext
  1455. error is returned.
  1456. .LP
  1457. .IN "SetResolution" "" "@DEF@"
  1458. .PN SetResolution
  1459. .IP
  1460. \fIresolutions\fP\^:  LISTofRESOLUTION
  1461. .IP
  1462. Errors:  
  1463. .PN Resolution , 
  1464. .PN Alloc
  1465. .IP
  1466. This request provides a hint as to the resolution and
  1467. preferred point size of the drawing surfaces for which the
  1468. client will be requesting fonts.  The server may use this
  1469. information to set the RESOLUTION_X and RESOLUTION_Y fields
  1470. of scalable XLFD font names, to order sets of names based on
  1471. their resolutions, and to choose the server-dependent
  1472. instance that is used when a partially-specified scalable
  1473. fontname is opened.
  1474. .sp
  1475. If a zero-length list of RESOLUTIONS is given, the
  1476. server-dependent default value is restored.  Otherwise, if
  1477. elements of all of the specified RESOLUTIONS are non-zero, the
  1478. default resolutions for this client are changed.
  1479. .sp
  1480. If a RESOLUTION entry contains a zero, a Resolution error is
  1481. returned and the default resolutions are not changed.
  1482. .LP
  1483. .IN "GetResolution" "" "@DEF@"
  1484. .PN GetResolution
  1485. .LP
  1486.   =>
  1487. .IP
  1488. \fIresolutions\fP\^:  LISTofRESOLUTION
  1489. .IP
  1490. Errors:  
  1491. .PN Alloc
  1492. .IP
  1493. This request returns the current list of default resolutions.
  1494. If a client has not performed a 
  1495. .PN SetResolution , 
  1496. a server-dependent default value is returned.
  1497. .LP
  1498. .IN "ListFonts" "" "@DEF@"
  1499. .PN ListFonts
  1500. .IP
  1501. \fIpattern\fP\^:  STRING8
  1502. \fImax-names\fP\^:  CARD32
  1503. .LP
  1504.   =>+
  1505. .IP
  1506. \fIreplies-following-hint\fP\^:  CARD32
  1507. .br
  1508. \fInames\fP\^:  LISTofSTRING8
  1509. .IP
  1510. Errors:  
  1511. .PN Alloc
  1512. .IP
  1513. This request returns a list of at most MAX-NAMES font names
  1514. that match the specified PATTERN, according to matching rules
  1515. of the X Logical Font Description Conventions [3].  In the
  1516. pattern (which is encoded in ISO 8859-1) the `?' character
  1517. (octal 77) matches any single character; the `*' character
  1518. (octal 52) matches any series of zero or more characters; and
  1519. alphabetic characters match either upper- or lowercase.  The
  1520. returned NAMES are encoded in ISO 8859-1 and may contain mixed
  1521. character cases.  Font names are not required to be in XLFD
  1522. format.
  1523. .sp
  1524. If PATTERN is of zero length or MAX-NAMES is equal to zero,
  1525. one reply containing a zero-length list of names is returned.
  1526. This may be used to synchronize the client with the server.
  1527. .sp
  1528. Servers are free to add or remove fonts to the set returned by
  1529. .PN ListFonts 
  1530. between any two requests.  This request is not
  1531. cumulative; repeated uses are processed in isolation and do
  1532. result in an iteration through the list.
  1533. .sp
  1534. To reduce the amount of buffering needed by the server, the
  1535. list of names may be split across several reply packets, so
  1536. long as the names arrive in the same order that they would
  1537. have appeared had they been in a single packet.  The
  1538. REPLIES-FOLLOWING-HINT field in all but the last reply
  1539. contains a positive value that specifies the number of
  1540. replies that are likely, but not required, to follow.  In the
  1541. last reply, which may contain zero or more names, this field
  1542. is set to zero.
  1543. .LP
  1544. .IN "ListFontsWithXInfo" "" "@DEF@"
  1545. .PN ListFontsWithXInfo
  1546. .IP
  1547. \fIpattern\fP\^:  STRING8
  1548. .br
  1549. \fImax-names\fP\^:  CARD32
  1550. .LP
  1551.   =>+
  1552. .IP
  1553. \fIreplies-following-hint\fP\^:  CARD32
  1554. .br
  1555. \fIinfo\fP\^:  XFONTINFO
  1556. .br
  1557. \fIname\fP\^:  STRING8
  1558. .IP
  1559. Errors:  
  1560. .PN Alloc
  1561. .IP
  1562. This request is similar to 
  1563. .PN ListFonts 
  1564. except that a separate
  1565. reply containing the name, header, and property data is
  1566. generated for each matching font name.  Following these
  1567. replies, if any, a final reply containing a zero-length NAME
  1568. and no INFO is sent.
  1569. .sp
  1570. The REPLIES-FOLLOWING-HINT field in all but the last reply
  1571. contains a positive value that specifies the number of replies
  1572. that are likely, but not required, to follow.  In the last
  1573. reply, this field is set to zero.
  1574. .sp
  1575. If PATTERN is of zero length or if MAX-NAMES is equal to
  1576. zero, only the final reply containing a zero-length NAME and
  1577. no INFO is returned.  This may be used to synchronize the
  1578. client with the server.
  1579. .LP
  1580. .IN "OpenBitmapFont" "" "@DEF@"
  1581. .PN OpenBitmapFont
  1582. .IP
  1583. \fIfontid\fP\^:  FONTID
  1584. .br
  1585. \fIpattern\fP\^:  STRING8
  1586. .br
  1587. \fIformat-mask\fP\^:  BITMAPFORMATMASK
  1588. .br
  1589. \fIformat-hint\fP\^:  BITMAPFORMAT
  1590. .LP
  1591.   =>
  1592. .IP
  1593. \fIotherid\fP\^:  FONTID or None
  1594. .br
  1595. \fIotherid-valid\fP\^:  BOOL
  1596. .br
  1597. \fIcachable\fP\^:  BOOL
  1598. .IP
  1599. Errors:  
  1600. .PN IDChoice , 
  1601. .PN Name , 
  1602. .PN Format , 
  1603. .PN AccessContext , 
  1604. .PN Alloc
  1605. .IP
  1606. This request looks for a server-dependent choice of the
  1607. font names that match the specified PATTERN according to the
  1608. rules described for 
  1609. .PN ListFonts .  
  1610. If no matches are found, a
  1611. .PN Name 
  1612. error is returned.  Otherwise, the server attempts to
  1613. open the font associated with the chosen name.
  1614. .sp
  1615. Permission to access the font is determined by the server
  1616. according the licensing policy used for this font.  The server
  1617. may use the client's current 
  1618. .PN AccessContext
  1619. (as set by the most
  1620. recent 
  1621. .PN SetAuthorization 
  1622. request or the original connection
  1623. setup) to determine any client-specific sets of permissions.
  1624. After the font has been opened, the client is allowed to
  1625. specify a new 
  1626. .PN AccessContext
  1627. with 
  1628. .PN SetAuthorization
  1629. or release
  1630. the 
  1631. .PN AccessContext
  1632. using 
  1633. .PN FreeAC .  Subsequent 
  1634. .PN QueryXInfo ,
  1635. .PN QueryXExtents8 , 
  1636. .PN QueryXExtents16 , 
  1637. .PN QueryXBitmaps8 ,
  1638. .PN QueryXBitmaps16 , and 
  1639. .PN CloseFont 
  1640. requests on this FONTID are
  1641. performed according to permissions granted at the time of the
  1642. .PN OpenBitmapFont 
  1643. request.
  1644. .sp
  1645. If the server is willing and able to detect that the client
  1646. has already opened the font successfully (possibly under a
  1647. different name), the OTHERID field may be set to one of the
  1648. identifiers previously used to open the font.  The
  1649. OTHERID-VALID field indicates whether or not OTHERID is
  1650. still associated with an open font: if it is True, the
  1651. client may use OTHERID as an alternative to FONTID.
  1652. Otherwise, if OTHERID-VALID is False, OTHERID is no longer
  1653. open but has not been reused by a subsequent 
  1654. .PN OpenBitmapFont
  1655. request.
  1656. .sp
  1657. If OTHERID is set to None, then OTHERID-VALID should be set
  1658. to False.
  1659. .sp
  1660. If the client is allowed to access the font and the server is
  1661. able and willing to detect that the client has already
  1662. successfully opened the font (possibly under a different name), 
  1663. OTHERID may be set to a font identifier used to previously
  1664. open the font.  If the font is currently open and associated
  1665. with one or more identifiers, one of those FONTIDs should be
  1666. used for OTHERID and OTHERID-VALID should be set to True.
  1667. If the font is not currently open
  1668. to another valid font identifier that the client currently has
  1669. associated with this font and OTHERID-VALID is set to True.  
  1670. If the 
  1671. Otherwise, OTHERID is set to
  1672. None.
  1673. .sp
  1674. The FORMAT-MASK indicates which fields in FORMAT-HINT
  1675. the client is likely to use in subsequent 
  1676. .PN GetXBitmaps8
  1677. and 
  1678. .PN GetXBitmaps16 
  1679. requests.  Servers may wish to use
  1680. this information to precompute certain values.
  1681. .sp
  1682. If CACHABLE is set to True, the client may cache the font
  1683. (so that redundant opens of the same font may be avoided)
  1684. and use it with all 
  1685. .PN AccessContexts 
  1686. during the life of the
  1687. client without violating the font's licensing policy.  This
  1688. flag is typically set whenever a font is unlicensed or is
  1689. licensed on a per-display basis.  If CACHABLE is False, the
  1690. client should reopen the font for each 
  1691. .PN AccessContext .
  1692. .sp
  1693. The server is permitted to add to or remove from the set of
  1694. fonts returned by 
  1695. .PN ListFonts 
  1696. between any two requests, though
  1697. mechanisms outside the protocol.  Therefore, it is possible
  1698. for this request (which is atomic) to return a different font
  1699. than would result from separate a
  1700. .PN  ListFonts 
  1701. followed by an
  1702. .PN OpenBitmapFont 
  1703. with a non-wildcarded font name.
  1704. .sp
  1705. If FONTID is not in the range [1..2^29-1] or if it is already
  1706. associated with an open font, an 
  1707. .PN IDChoice 
  1708. error is returned.
  1709. If no font is available that matches the specified PATTERN, a
  1710. .PN Name 
  1711. error is returned.  If the font is present but the client
  1712. is not permitted access, an 
  1713. .PN AccessContext 
  1714. error is returned.
  1715. If FORMAT-MASK has any unspecified bits set or if any of the
  1716. fields in FORMAT-HINT indicated by FORMAT-MASK are invalid, a
  1717. .PN Format 
  1718. error is returned.
  1719. .LP
  1720. .IN "QueryXInfo" "" "@DEF@"
  1721. .PN QueryXInfo
  1722. .IP
  1723. \fIfontid\fP\^:  FONTID
  1724. .LP
  1725.   =>
  1726. .IP
  1727. \fIinfo\fP\^:  XFONTINFO
  1728. .IP
  1729. Errors:  
  1730. .PN Font , 
  1731. .PN Alloc
  1732. .IP
  1733. This request returns the font header and property information
  1734. for the open font associated with FONTID.
  1735. .sp
  1736. If FONTID is not associated with any open fonts, a
  1737. .PN  Font 
  1738. error
  1739. is returned.
  1740. .LP
  1741. .IN "QueryXExtents8" "" "@DEF@"
  1742. .PN QueryXExtents8
  1743. .IP
  1744. \fIfontid\fP\^:  FONTID
  1745. .br
  1746. \fIrange\fP\^:  BOOL
  1747. .br
  1748. \fIchars\fP\^:  STRING8
  1749. .LP
  1750.   =>
  1751. .IP
  1752. \fIextents\fP\^:  LISTofXCHARINFO
  1753. .IP
  1754. Errors: 
  1755. .PN  Font , 
  1756. .PN Range , 
  1757. .PN Alloc
  1758. .IP
  1759. This request is equivalent to 
  1760. .PN QueryXExtents16 
  1761. except that it
  1762. uses 1-byte character codes.
  1763. .LP
  1764. .IN "QueryXExtents16" "" "@DEF@"
  1765. .PN QueryXExtents16
  1766. .IP
  1767. \fIfontid\fP\^:  FONTID
  1768. .br
  1769. \fIrange\fP\^:  BOOL
  1770. .br
  1771. \fIchars\fP\^:  LISTofCHAR2B
  1772. .LP
  1773.   =>
  1774. .IP
  1775. \fIextents\fP\^:  LISTofXCHARINFO
  1776. .IP
  1777. Errors:  
  1778. .PN Font , 
  1779. .PN Range , 
  1780. .PN Alloc
  1781. .IP
  1782. This request returns a list of glyph extents from the open
  1783. font associated with FONTID for the series of characters
  1784. specified by RANGE and CHARS.
  1785. .sp
  1786. If RANGE is True, each succeeding pair of elements in CHARS is
  1787. treated as a range of characters for which extents should be
  1788. returned.  If CHARS contains an odd number of elements, the
  1789. font's XFONTINFO.CHAR-RANGE.MAX-CHAR is implicitly appended to
  1790. the list.  If CHARS contains no elements, the list is
  1791. implicitly replaced with the font's XFONTINFO.CHAR-RANGE.  If
  1792. any of the resulting character ranges are invalid, a Range
  1793. error is returned.  Otherwise, the character ranges are
  1794. concatenated in the order given by CHARS to produce a set of
  1795. character codes for which extents are returned.
  1796. .sp
  1797. If RANGE is False, then CHARS specifies the set of character
  1798. codes for which extents are returned.  If CHARS is of
  1799. zero length, then a zero-length list of extents is returned.
  1800. .sp
  1801. The extents for each character code in the resulting set (which
  1802. may contain duplicates) are returned in the order in
  1803. which the character codes appear in the set.
  1804. At least one metric for each character shall be non-zero
  1805. unless the character is not encoded in the font, in which case
  1806. all-zero metrics are returned.
  1807. A blank, zero-width character can be encoded
  1808. with non-zero but equal left and right bearings.
  1809. .sp
  1810. If FONTID is not associated with any open fonts, a 
  1811. .PN Font 
  1812. error is
  1813. returned.  If RANGE is True and CHARS contains any invalid
  1814. ranges, a 
  1815. .PN Range 
  1816. error is returned.
  1817. .LP
  1818. .IN "QueryXBitmaps8" "" "@DEF@"
  1819. .PN QueryXBitmaps8
  1820. .IP
  1821. \fIfontid\fP\^:  FONTID
  1822. .br
  1823. \fIrange\fP\^:  BOOL
  1824. .br
  1825. \fIchars\fP\^:  STRING8
  1826. .br
  1827. \fIformat\fP\^:  BITMAPFORMAT
  1828. .LP
  1829.   =>+
  1830. .IP
  1831. \fIreplies-following-hint\fP\^:  CARD32
  1832. .br
  1833. \fIoffsets\fP\^:  LISTofOFFSET32
  1834. .br
  1835. \fIbitmaps\fP\^:  LISTofBYTE
  1836. .IP
  1837. Errors:  
  1838. .PN Font , 
  1839. .PN Range , 
  1840. .PN Format , 
  1841. .PN Alloc
  1842. .IP
  1843. This request is equivalent to 
  1844. .PN QueryXBitmaps16 
  1845. except that it
  1846. uses 1-byte character codes.
  1847. .LP
  1848. .IN "QueryXBitmaps16" "" "@DEF@"
  1849. .PN QueryXBitmaps16
  1850. .IP
  1851. \fIfontid\fP\^:  FONTID
  1852. .br
  1853. \fIrange\fP\^:  BOOL
  1854. .br
  1855. \fIchars\fP\^:  LISTofCHAR2B
  1856. .br
  1857. \fIformat\fP\^:  BITMAPFORMAT
  1858. .LP
  1859.   =>+
  1860. .IP
  1861. \fIreplies-following-hint\fP\^:  CARD32
  1862. .br
  1863. \fIoffsets\fP\^:  LISTofOFFSET32
  1864. .br
  1865. \fIbitmaps\fP\^:  LISTofBYTE
  1866. .IP
  1867. Errors:  
  1868. .PN Font , 
  1869. .PN Range , 
  1870. .PN Format , 
  1871. .PN Alloc
  1872. .IP
  1873. This request returns a list of glyph bitmaps from the open
  1874. font associated with FONTID for the series of characters
  1875. specified by RANGE and CHARS.
  1876. .sp
  1877. If RANGE is True, each succeeding pair of elements in CHARS is
  1878. treated as a range of characters for which bitmaps should be
  1879. returned.  If CHARS contains an odd number of elements, the
  1880. font's XFONTINFO.CHAR-RANGE.MAX-CHAR is implicitly appended to
  1881. the list.  If CHARS contains no elements, the list is
  1882. implicitly replaced with the font's XFONTINFO.CHAR-RANGE.  If
  1883. any of the resulting character ranges are invalid, a Range
  1884. error is returned.  Otherwise, the character ranges are
  1885. concatenated in the order given by CHARS to produce a set of
  1886. character codes for which bitmaps are returned.
  1887. .sp
  1888. If RANGE is False, then CHARS specifies the set of character
  1889. codes for which bitmaps are returned.  If CHARS is of zero
  1890. length, then a single reply containing a zero-length list of
  1891. offsets and bitmaps is returned.
  1892. .sp
  1893. If any of the resulting character ranges are invalid, a Range
  1894. error is returned.  Otherwise, the resulting character ranges
  1895. are concatenated in the order given by CHARS to produce a set
  1896. of character codes for which bitmaps are returned.
  1897. .sp
  1898. The server is free to return the glyph bitmaps in multiple
  1899. replies to reduce the amount of buffering that is necessary.
  1900. In this situation, the set of characters obtained above is
  1901. partitioned into an implementation-dependent number of
  1902. ordered, non-overlapping subsets containing runs of one or
  1903. more consecutive characters.  The global ordering of
  1904. characters must be maintained such that concatenating the
  1905. subsets in order that they were produced yields the original
  1906. set.  A reply is generated for each subset, in the order that
  1907. it was produced.
  1908. .sp
  1909. For each character in a subset, an image of that character's
  1910. glyph is described by a rectangle of bits corresponding to the
  1911. pixels specified by FORMAT.IMAGE-RECT.  Within the image, set
  1912. and clear bits represent inked and non-inked pixels,
  1913. respectively.
  1914. .sp
  1915. Each scanline of a glyph image, from top to bottom, is zero-padded
  1916. on the right to a multiple of the number of bits specified by
  1917. FORMAT.SCANLINE-PAD.  The scanline is then divided from left
  1918. to right into a sequence of FORMAT.SCANLINE-UNIT bits.  The
  1919. bits of each unit are then arranged such that the left-most
  1920. pixel is stored in the most- or least-significant bit,
  1921. according to FORMAT.BIT-ORDER-MSB.  The bytes of each unit are
  1922. then arranged such that the most- or least-significant byte,
  1923. according to FORMAT.BYTE-ORDER-MSB, is transmitted first.
  1924. Finally, the units are arranged such that the left-most is
  1925. transmitted first and the right-most is transmitted last.
  1926. .sp
  1927. The individual images within a subset are then concatenated in
  1928. a server-dependent order to form the BITMAPS data of the
  1929. reply.  If a glyph image is duplicated within a reply, the
  1930. server is free to return fewer (but at least one) copies of
  1931. the image.  If a character is not encoded within the font, a
  1932. zero-length bitmap is substituted for this character.  Each 
  1933. glyph image must begin at a bit position that is a multiple of
  1934. the FORMAT.SCANLINE-UNIT.
  1935. .sp
  1936. The OFFSETS array in a reply contains one entry for each
  1937. character in the subset being returned, in the order that the
  1938. characters appear in the subset.  Each entry specifies the
  1939. starting location in bytes and size in bytes of the
  1940. corresponding glyph image in the BITMAPS data of that reply
  1941. (i.e. an offset may not refer to data in another reply).
  1942. .sp
  1943. The REPLIES-FOLLOWING-HINT field in all but the last reply
  1944. contains a positive value that specifies the number of replies
  1945. that are likely, but not required, to follow.  In the last
  1946. reply, which may contain data for zero or more characters,
  1947. this field is set to zero.
  1948. .sp
  1949. If FONTID is not associated with any open fonts, a Font error
  1950. is returned.  If RANGE is True and CHARS contains any invalid
  1951. ranges, a Range error is returned.  If FORMAT is invalid, a
  1952. Format error is returned.
  1953. .LP
  1954. .IN "CloseFont" "" "@DEF@"
  1955. .PN CloseFont
  1956. .IP
  1957. \fIfontid\fP\^:  FONTID
  1958. .IP
  1959. Errors:  
  1960. .PN Font , 
  1961. .PN Alloc
  1962. .IP
  1963. This request indicates that the specified FONTID should no
  1964. longer be associated with an open font.  The server is free to
  1965. release any client-specific storage or licenses allocated for
  1966. the font.  The client may reuse the value of FONTID in a
  1967. subsequent 
  1968. .PN OpenBitmapFont 
  1969. request.
  1970. .sp
  1971. If FONTID is not associated with any open fonts, a
  1972. .PN  Font 
  1973. error is returned.
  1974. .LP
  1975. .PN "close connection"
  1976. .IN "close connection" "" "@DEF@"
  1977. .IP
  1978. When a connection is closed, a 
  1979. .PN CloseFont 
  1980. is done on all fonts
  1981. that are open on the connection.  In addition, the server is
  1982. free to release any storage or licenses allocated on behalf of
  1983. the client that made the connection.
  1984. .NH 2
  1985. Errors
  1986. .XS
  1987. \*(SN Errors
  1988. .XE
  1989. .LP
  1990. All errors are at least 16 bytes long and contain the following fields:
  1991. .TA .75i
  1992. .ta .75i
  1993. .IP
  1994. \fItype\fP\^:  CARD8  value of 1
  1995. .br
  1996. \fIerror-code\fP\^:  CARD8
  1997. .br
  1998. \fIsequence-number\fP\^:  CARD16
  1999. .br
  2000. \fIlength\fP\^:  CARD32
  2001. .br
  2002. \fItimestamp\fP\^:  TIMESTAMP
  2003. .br
  2004. \fImajor-opcode\fP\^:  CARD8
  2005. .br
  2006. \fIminor-opcode\fP\^:  CARD8
  2007. .br
  2008. \fIdata-or-unused\fP\^:  CARD16
  2009. .LP
  2010. The TYPE field has a value of one.  The ERROR-CODE field specifies which error
  2011. occurred.  Core errors codes are in the range 0 through 127, extension error
  2012. codes are in the range 128 through 255.  The SEQUENCE-NUMBER field contains the
  2013. least significant 16 bits of the sequence number of the request that caused the
  2014. error.  The LENGTH field specifies the length of the error packet in 4-byte
  2015. units and must have a value of at least 4.  The TIMESTAMP specifies the server
  2016. time when the error occurred.  The MAJOR-OPCODE and MINOR-OPCODE (zero for core
  2017. requests) fields specify the type of request that generated the error.  The
  2018. DATA-OR-UNUSED field may be used for 16 bits of error-specific information.  If
  2019. LENGTH is greater than four, these fields are followed by (LENGTH - 4) * 4
  2020. bytes of extra data.
  2021. .LP
  2022. The following errors are defined for the core protocol:
  2023. .LP
  2024. .IN "Error Codes" "Request" "@DEF@"
  2025. .PN Request
  2026. .IP
  2027. .TA .75i .75i .75i .75i
  2028. \fIdata-or-unused\fP\^:  CARD16    unused
  2029. .IP
  2030. This error is generated by any request that has an unknown 
  2031. combination of major and minor request numbers, or by any
  2032. extension request that is issued before a 
  2033. .PN QueryExtension 
  2034. of that extension.
  2035. .LP
  2036. .IN "Error Codes" "Format" "@DEF@"
  2037. .PN Format
  2038. .IP
  2039. .TA .75i .75i .75i .75i
  2040. \fIdata-or-unused\fP\^:  CARD16    unused
  2041. .br
  2042. \fIformat\fP\^:  BITMAPFORMAT    bad format value
  2043. .IP
  2044. This error is generated by the use of an invalid BITMAPFORMAT
  2045. in the 
  2046. .PN OpenBitmapFont , 
  2047. .PN QueryXBitmaps8 , 
  2048. and 
  2049. .PN QueryXBitmaps16 
  2050. requests.
  2051. The value that caused the error is included as extra data.
  2052. .LP
  2053. .IN "Error Codes" "Font" "@DEF@"
  2054. .PN Font
  2055. .IP
  2056. .TA .75i .75i .75i .75i
  2057. \fIdata-or-unused\fP\^:  CARD16    unused
  2058. .br
  2059. \fIfontid\fP\^:  FONTID    bad font identifier
  2060. .IP
  2061. This error is generated by an invalid FONTID in the
  2062. .PN QueryXInfo , 
  2063. .PN QueryXExtents8 , 
  2064. .PN QueryXExtents16 , 
  2065. .PN QueryXBitmaps8 , 
  2066. .PN QueryXBitmaps16 , 
  2067. and 
  2068. .PN CloseFont 
  2069. requests.  The value that caused
  2070. the error is included as extra data.
  2071. .LP
  2072. .IN "Error Codes" "Range" "@DEF@"
  2073. .PN Range
  2074. .IP
  2075. .TA .75i .75i .75i .75i
  2076. \fIdata-or-unused\fP\^:  CARD16    unused
  2077. .br
  2078. \fIrange\fP\^:  RANGE    bad range
  2079. .IP
  2080. This error is generated by an invalid RANGE in the
  2081. .PN  QueryXExtents8 , 
  2082. .PN QueryXExtents16 , 
  2083. .PN QueryXBitmaps8 , and 
  2084. .PN QueryXBitmaps16 
  2085. requests.  The
  2086. value that caused the error is included as extra data.
  2087. .LP
  2088. .IN "Error Codes" "EventMask" "@DEF@"
  2089. .PN EventMask
  2090. .IP
  2091. .TA .75i .75i .75i .75i
  2092. \fIdata-or-unused\fP\^:  CARD16    unused
  2093. .br
  2094. \fIevent-mask\fP\^:  EVENTMASK    bad event mask
  2095. .IP
  2096. This error is generated by an invalid EVENTMASK in the 
  2097. .PN SetEventMask 
  2098. request.  The value that caused the error is 
  2099. included as extra data.
  2100. .LP
  2101. .IN "Error Codes" "AccessContext" "@DEF@"
  2102. .PN AccessContext
  2103. .IP
  2104. .TA .75i .75i .75i .75i
  2105. \fIdata-or-unused\fP\^:  CARD16    unused
  2106. .br
  2107. \fIac\fP\^:  ACCESSCONTEXT    unaccepted 
  2108. .PN AccessContext
  2109. .IP
  2110. This error is generated by an invalid ACCESSCONTEXT in the
  2111. .PN FreeAC 
  2112. or 
  2113. .PN SetAuthorization 
  2114. request or by an 
  2115. .PN OpenBitmapFont
  2116. request performed without sufficient authorization.  In the
  2117. first two cases, the ACCESSCONTEXT of the errant request is
  2118. returned as extra data.  In the third case, the current
  2119. ACCESSCONTEXT is returned as extra data.
  2120. .LP
  2121. .IN "Error Codes" "IDChoice" "@DEF@"
  2122. .PN IDChoice
  2123. .IP
  2124. .TA .75i .75i .75i .75i
  2125. \fIdata-or-unused\fP\^:  CARD16    unused
  2126. .br
  2127. \fIid\fP\^:  ID    bad identifier
  2128. .IP
  2129. This error is generated by an invalid or already associated 
  2130. ACCESSCONTEXT identifier in a 
  2131. .PN CreateAC 
  2132. request or FONTID identifier
  2133. in an 
  2134. .PN OpenBitmapFont 
  2135. request.  The value that caused the error
  2136. is included as extra data.
  2137. .LP
  2138. .IN "Error Codes" "Name" "@DEF@"
  2139. .PN Name
  2140. .IP
  2141. .TA .75i .75i .75i .75i
  2142. \fIdata-or-unused\fP\^:  CARD16    unused
  2143. .IP
  2144. This error is generated by a font name pattern that matches
  2145. no fonts in an 
  2146. .PN OpenBitmapFont 
  2147. request or no catalogue names in a 
  2148. .PN SetCatalogues 
  2149. request.
  2150. .LP
  2151. .IN "Error Codes" "Resolution" "@DEF@"
  2152. .PN Resolution
  2153. .IP
  2154. .TA .75i .75i .75i .75i
  2155. \fIdata-or-unused\fP\^:  CARD16    X value of errant resolution
  2156. .br
  2157. \fIy-resolution\fP\^:  CARD16        Y value of errant resolution
  2158. .br
  2159. \fIpoint-size\fP\^:  CARD16        point size of errant resolution
  2160. .IP
  2161. This error is generated in response to an invalid RESOLUTION 
  2162. structure in a 
  2163. .PN SetResolution 
  2164. request.  The value that caused the
  2165. error is included in the DATA-OR-UNUSED field and as extra data.
  2166. .LP    
  2167. .IN "Error Codes" "Alloc" "@DEF@"
  2168. .PN Alloc
  2169. .IP
  2170. .TA .75i .75i .75i .75i
  2171. \fIdata-or-unused\fP\^:  CARD16    unused
  2172. .IP
  2173. This error is generated by any request for which the server
  2174. lacks sufficient resources (especially memory).
  2175. .LP
  2176. .IN "Error Codes" "Length" "@DEF@"
  2177. .PN Length
  2178. .IP
  2179. .TA .75i .75i .75i .75i
  2180. \fIdata-or-unused\fP\^:  CARD16    unused
  2181. .br
  2182. \fIlength\fP\^:  CARD32    bad length value
  2183. .IP
  2184. This error is generated by any request that has a length field
  2185. greater than (MAXIMUM-REQUEST-LENGTH * 4) bytes.  The value that 
  2186. caused the error is included as extra data.
  2187. .LP
  2188. .IN "Error Codes" "Implementation" "@DEF@"
  2189. .PN Implementation
  2190. .IP
  2191. .TA .75i .75i .75i .75i
  2192. \fIdata-or-unused\fP\^:  CARD16    unused
  2193. .IP
  2194. This error may be generated in response to any request that
  2195. the server is unable to process because it is deficient.  Use
  2196. of this error is highly discouraged and indicates lack of
  2197. conformance to the protocol.
  2198. .sp
  2199. Additional errors may be defined by extensions.
  2200. .NH 2
  2201. Events
  2202. .XS
  2203. \*(SN Events
  2204. .XE
  2205. .LP
  2206. Events may be generated in response to requests or at the server's discretion
  2207. after the initial connection setup information has been exchanged.  Each event
  2208. is at least 12 bytes long and contains the following fields:
  2209. .IP
  2210. .TA .75i .75i .75i .75i
  2211. \fItype\fP\^:  CARD8    value of 2
  2212. .br
  2213. \fIevent-code\fP\^:  CARD8
  2214. .br
  2215. \fIsequence-number\fP\^:  CARD16
  2216. .br
  2217. \fIlength\fP\^:  CARD32
  2218. .br
  2219. \fItimestamp\fP\^:  TIMESTAMP
  2220. .LP
  2221. The TYPE field contains the value 2.  The EVENT-CODE field specifies the number
  2222. of the event and is in the range 0-127 for core events or the range 128-255 for
  2223. extensions.  The SEQUENCE-NUMBER field specifies the least significant 16 bits
  2224. of the sequence number of the last request to have been processed by the
  2225. server.  The LENGTH field specifies the number of 4-byte units in this event
  2226. packet and must always have a value of at least 3.  The TIMESTAMP field
  2227. specifies the server time when the event occurred.  If LENGTH is greater than
  2228. three, these fields are followed by (LENGTH - 3) * 4 bytes of additional data.
  2229. .LP
  2230. Events are described using the following syntax:
  2231. .LP
  2232. .RS
  2233. .DS
  2234. .TA .75i
  2235. .ta .75i
  2236. .PN EventName
  2237.         \fIarg1\fP\^: type1
  2238.         ...
  2239.         \fIargN\fP\^: typeN
  2240.  
  2241.         Description
  2242. .DE
  2243. .RE
  2244. If an event does not provide any extra arguments, the \fIarg1\fP...\fIargN\fP 
  2245. lines are omitted from the description.
  2246. .LP
  2247. The core X Font Service protocol defines the following events:
  2248. .LP
  2249. .IN "KeepAlive" "" "@DEF@"
  2250. .PN KeepAlive
  2251. .IP
  2252. This unsolicited, nonmaskable event may be sent by the
  2253. server to verify that the connection has not been broken
  2254. (for transports that do not provide this information).
  2255. Clients should acknowledge receipt of this request
  2256. by sending any request (such as 
  2257. .PN NoOp ")."
  2258. .LP
  2259. .IN "CatalogueListNotify" "" "@DEF@"
  2260. .PN CatalogueListNotify
  2261. .IP
  2262. \fIadded\fP\^:  BOOL
  2263. .br
  2264. \fIdeleted\fP\^:  BOOL
  2265. .IP
  2266. This event is sent to clients that have included
  2267. .PN CatalogueListChangeMask 
  2268. in their core event mask
  2269. whenever the list of catalogues that are available has
  2270. changed.  The ADDED field is True if new catalogues have
  2271. been added to the server, otherwise it is False.  The
  2272. DELETED field is True if any existing catalogues have
  2273. been removed from the server, otherwise it is False.
  2274. .LP    
  2275. .IN "FontListNotify" "" "@DEF@"
  2276. .PN FontListNotify
  2277. .IP
  2278. \fIadded\fP\^:  BOOL
  2279. .br
  2280. \fIdeleted\fP\^:  BOOL
  2281. .IP
  2282. This event is sent to clients that have included
  2283. .PN FontListChangeMask 
  2284. in their event mask whenever the
  2285. list of fonts that are provided by the currently selected
  2286. catalogues has changed.  The ADDED field is True if new
  2287. fonts have been added to any of the catalogues currently
  2288. used by the client, otherwise it is False.  The DELETED
  2289. field is True if any existing fonts have been removed
  2290. from any of catalogues used by the client, otherwise it
  2291. is False.
  2292. .sp
  2293. Additional events may be defined by extensions.
  2294. .NH 1
  2295. Protocol Encoding
  2296. .XS
  2297. \*(SN Protocol Encoding
  2298. .XE
  2299. .LP
  2300. Numbers that are prefixed with ``#x'' are in hexadecimal (base 16).  All other
  2301. numbers are in decimal.  Requests, replies, errors, events, and compound types
  2302. are described using the syntax:
  2303. .RS
  2304. .DS
  2305. .TA .75i .75i .75i .75i
  2306.  
  2307.     Name
  2308.     \fIcount\fP        \fIcontents\fP    \fIname\fP
  2309.     ...
  2310.     \fIcount\fP        \fIcontents\fP    \fIname\fP
  2311. .DE
  2312. .RE
  2313. where COUNT is the number of bytes in the data stream occupied by this 
  2314. field, CONTENTS is the name of the type as given in Section 4 or the value if
  2315. this field contains a constant, and NAME is a description of this field.
  2316. .LP
  2317. Objects containing counted lists use a lowercase single-letter variable (whose
  2318. scope is limited to the request, reply, event, or error in which it is found)
  2319. to represent the number of objects in the list.  These variables, and any
  2320. expressions in which they are used, should be treated as unsigned integers.
  2321. Multiple copies of an object are indicated by CONTENTS prefix ``LISTof''.
  2322. .LP
  2323. Unused bytes (whose value is undefined) will have a blank CONTENTS field and a
  2324. NAME field of ``unused''.  Zeroed bytes (whose value must be zero) will have a
  2325. blank CONTENTS field and a NAME field of ``zero''.  The expression pad(e)
  2326. refers to the number of bytes needed to round a value ``e'' up to the closed
  2327. multiple of four:
  2328. .RS
  2329. .DS
  2330.  
  2331.     pad(e) = (4 - (e mod 4)) mod 4
  2332. .DE
  2333. .RE
  2334. .NH 2
  2335. Data Types
  2336. .XS
  2337. \*(SN Data Types
  2338. .XE
  2339. .sp 6p
  2340. .LP
  2341. ACCESSCONTEXT
  2342. .sp 6p
  2343. .TA .75i .75i .75i .75i
  2344. 4    CARD32    access context with at least one of the following bits set:
  2345. .sp 6p
  2346. #x1fffffff
  2347. .sp 6p
  2348. but none of the following bits set:
  2349. .sp 6p
  2350. #xe0000000        zero
  2351. .sp 18p
  2352. .LP
  2353. .TS
  2354. tab (@) ;
  2355. l s s
  2356. l l l.
  2357. ALTERNATESERVER
  2358. .sp 6p
  2359. 1@BOOL@subset
  2360. 1@n@length of name
  2361. n@STRING8@name
  2362. p@@unused, p=pad(n+2)
  2363. .TE
  2364. .sp 6p
  2365. .TS
  2366. tab (@) ;
  2367. l s s
  2368. l l l.
  2369. AUTH
  2370. .sp 6p
  2371. 2@n@length of name
  2372. 2@d@length of data
  2373. n@STRING8@name
  2374. p@@unused, p=pad(n)
  2375. d@STRING8@data
  2376. q@@unused, q=pad(d)
  2377. .TE
  2378. .sp 12p
  2379. .LP
  2380. BITMAPFORMAT
  2381. .TA .75i .75i .75i .75i
  2382. .sp 6p
  2383. 4    CARD32    value, union of the following bits:
  2384. .TS
  2385. tab (@) ;
  2386. n l.
  2387. #x00000001@ByteOrderMSB
  2388. #x00000002@BitOrderMSB
  2389. #x00000000@ImageRectMin
  2390. #x00000004@ImageRectMaxWidth
  2391. #x00000008@ImageRectMax
  2392. #x00000000@ScanlinePad8
  2393. #x00000100@ScanlinePad16
  2394. #x00000200@ScanlinePad32
  2395. #x00000300@ScanlinePad64
  2396. #x00000000@ScanlineUnit8
  2397. #x00001000@ScanlineUnit16
  2398. #x00002000@ScanlineUnit32
  2399. #x00003000@ScanlineUnit64
  2400. .T&
  2401. l s
  2402. n l.
  2403. .sp 6p
  2404. except for the following bits which must be zero:
  2405. .sp 6p
  2406. #xffffccf0@zero
  2407. .T&
  2408. l s
  2409. n l.
  2410. .sp 6p
  2411. and the following of which at most one bit may be set:
  2412. .sp 6p
  2413. #x0000000c@at most one bit can be set
  2414. .TE
  2415. .sp 12p
  2416. .LP
  2417. BITMAPFORMATMASK
  2418. .sp 6p
  2419. .TA .75i .75i .75i .75i
  2420. 4    CARD32    value, mask of the following bits:
  2421. .TS
  2422. tab (@) ;
  2423. n l.
  2424. #x00000001@ByteOrderMask
  2425. #x00000002@BitOrderMask
  2426. #x00000004@ImageRectMask
  2427. #x00000008@ScanlinePadMask
  2428. #x00000010@ScanlineUnitMask
  2429. .T&
  2430. l s
  2431. n l.
  2432. .sp 6p
  2433. except for the following bits which must be zero:
  2434. .sp 6p
  2435. #xffffffe0@zero
  2436. .TE
  2437. .sp 12p
  2438. .KS
  2439. .LP
  2440. BOOL
  2441. .sp 6p
  2442. .TA .75i .75i .75i .75i
  2443. 1    BOOL    boolean, one of the following values:
  2444. .sp 6p
  2445.         0    False
  2446. .br
  2447.         1    True
  2448. .sp 6p
  2449. .KE
  2450. .sp 18p
  2451. .LP
  2452. BYTE
  2453. .sp 6p
  2454. .TA .75i .75i .75i .75i
  2455. 1    BYTE    unsigned byte of data
  2456. .sp 18p
  2457. .LP
  2458. CARD8
  2459. .sp 6p
  2460. .TA .75i .75i .75i .75i
  2461. 1    CARD8    8-bit unsigned integer
  2462. .sp 18p
  2463. .LP
  2464. CARD16
  2465. .sp 6p
  2466. .TA .75i .75i .75i .75i
  2467. 2    CARD16    16-bit unsigned integer
  2468. .sp 18p
  2469. .LP
  2470. CARD32
  2471. .sp 6p
  2472. .TA .75i .75i .75i .75i
  2473. 4    CARD32    32-bit unsigned integer
  2474. .sp 18p
  2475. .LP
  2476. CHAR2B
  2477. .sp 6p
  2478. .TA .75i .75i .75i .75i
  2479. 1    CARD8    byte1
  2480. .br
  2481. 1    CARD8    byte2
  2482. .sp 18p
  2483. .LP
  2484. EVENTMASK
  2485. .sp 6p
  2486. .TA .75i .75i .75i .75i
  2487. 4        CARD32        event mask
  2488. .br
  2489. .TS
  2490. tab (@) ;
  2491. l s
  2492. n l.
  2493. for core events, this is union of the following bits:
  2494. .sp 6p
  2495. #00000001@CatalogueListChangeMask
  2496. #00000002@FontListChangeMask
  2497. .T&
  2498. l s
  2499. n l.
  2500. .sp 6p
  2501. but none of the following bits set:
  2502. .sp 6p
  2503. #fffffffc@
  2504. .TE
  2505. extensions define their own sets of bits
  2506. .sp 18p
  2507. .LP
  2508. FONTID
  2509. .sp 6p
  2510. .TA .75i .75i .75i .75i
  2511. 4    CARD32    font identifier with at least one of
  2512. .br
  2513.                     the following bits set:
  2514. .TS
  2515. tab (@) ;
  2516. n l.
  2517. #x1fffffff
  2518. .sp 6p
  2519. .T&
  2520. l s
  2521. n l.
  2522. but none of the following bits set:
  2523. .sp 6p
  2524. #xe0000000@zero
  2525. .TE
  2526. .sp 18p
  2527. .LP
  2528. INT8
  2529. .br
  2530. .TA .75i .75i .75i .75i
  2531. 1    INT8        8-bit signed integer
  2532. .sp 18p
  2533. .LP
  2534. INT16
  2535. .br
  2536. .TA .75i .75i .75i .75i
  2537. 2    INT16    16-bit signed integer
  2538. .sp 18p
  2539. .LP
  2540. INT32
  2541. .br
  2542. .TA .75i .75i .75i .75i
  2543. 4    INT32    32-bit signed integer
  2544. .sp 18p
  2545. .LP
  2546. OFFSET32
  2547. .br
  2548. .TA .75i .75i .75i .75i
  2549. 4    CARD32    position
  2550. .br
  2551. 4    CARD32    length
  2552. .sp 18p
  2553. .LP
  2554. PROPINFO
  2555. .br
  2556. .TA .75i .75i .75i .75i
  2557. 4    n            number of PROPOFFSET components
  2558. .br
  2559. 4    m            number of bytes of property data
  2560. .br
  2561. 20*n    PROPOFFSET    property offsets into data block
  2562. .br
  2563. m    LISTofBYTE    property data block
  2564. .br
  2565. p                unused, p = pad(m)
  2566. .sp 18p
  2567. .LP
  2568. PROPOFFSET
  2569. .br
  2570. .TA .75i .75i .75i .75i
  2571. 8    OFFSET32        name in data block
  2572. .br
  2573. 8    OFFSET32        value in data block
  2574. .br
  2575. 1    CARD8        type, one of the following values:
  2576. .sp 6p
  2577.     0        String
  2578. .br
  2579.     1        Unsigned
  2580. .br
  2581.     2        Signed
  2582. .br
  2583. 3            zero
  2584. .sp 18p
  2585. .LP
  2586. RANGE
  2587. .sp 6p
  2588. .TA .75i .75i .75i .75i
  2589. 2    CHAR2B    minimum character code
  2590. .br
  2591. 2    CHAR2B    maximum character code
  2592. .sp 18p
  2593. .LP
  2594. RESOLUTION
  2595. .sp 6p
  2596. .TA .75i .75i .75i .75i
  2597. 2    CARD16    x resolution in pixels per inch
  2598. .br
  2599. 2    CARD16    y resolution in pixels per inch
  2600. .br
  2601. 2    CARD16    point size in decipoints
  2602. .sp 18p
  2603. .LP
  2604. STRNAME
  2605. .sp 6p
  2606. .TA .75i .75i .75i .75i
  2607. 1    n    length of name
  2608. .br
  2609. n    STRING8    name
  2610. .sp 18p
  2611. .LP
  2612. STRING8
  2613. .sp 6p
  2614. .TA .75i .75i .75i .75i
  2615. n    LISTofBYTE    array of 8-bit character values
  2616. .sp 18p
  2617. .LP
  2618. TIMESTAMP
  2619. .sp 6p
  2620. .TA .75i .75i .75i .75i
  2621. 4    CARD32    milliseconds since server time origin
  2622. .sp 18p
  2623. .LP
  2624. XCHARINFO
  2625. .sp 6p
  2626. .TA .75i .75i .75i .75i
  2627. 2    INT16    left bearing
  2628. .br
  2629. 2    INT16    right bearing
  2630. .br
  2631. 2    INT16    width
  2632. .br
  2633. 2    INT16    ascent
  2634. .br
  2635. 2    INT16    descent
  2636. .br
  2637. 2    CARD16    attributes
  2638. .sp 18p
  2639. .LP
  2640. XFONTINFO
  2641. .sp 6p
  2642. .TA .75i .75i .75i .75i
  2643. 4    CARD32    flags, union of the following bits:
  2644. .TS
  2645. n l.
  2646. #x00000001    AllCharactersExist
  2647. #x00000002    InkInside
  2648. #x00000004    HorizontalOverlap
  2649. .T&
  2650. l s
  2651. n l.
  2652. .sp 6p
  2653. but none of the following bits set:
  2654. .sp 6p
  2655. #xfffffff8    zero
  2656. .TE
  2657. .TA .75i .75i .75i .75i
  2658. 4        RANGE        range of characters in font
  2659. .br
  2660. 1        CARD8        drawing direction
  2661. .sp 6p
  2662.         0        LeftToRight
  2663. .br
  2664.         1        RightToLeft
  2665. .sp 6p
  2666. 1                    unused
  2667. .br
  2668. 2        CHAR2B        default character
  2669. .br
  2670. 12        XCHARINFO    minimum bounds
  2671. .br
  2672. 12        XCHARINFO    maximum bounds
  2673. .br
  2674. 2        INT16        font ascent
  2675. .br
  2676. 2        INT16        font descent
  2677. .br
  2678. n        PROPINFO        property data
  2679. .NH 2
  2680. Requests
  2681. .XS
  2682. \*(SN Requests
  2683. .XE
  2684. .LP
  2685. .TS
  2686. tab (@) ;
  2687. lfB s s
  2688. lw(.25i) lw(2i) l.
  2689. open connection
  2690. .sp 6p
  2691. 1@BYTE@byte order, one of the values:
  2692. @#x42@Most Significant Byte first
  2693. @#x6c@Least Significant Byte first
  2694. 1@CARD8@number of auth in auth-data
  2695. 2@2@client-major-protocol-version
  2696. 2@0@client-minor-protocol-version
  2697. 2@a/4@length of auth-data
  2698. a@LISTofAUTH@auth-data
  2699. =>@@
  2700. 2@CARD16@status
  2701. @0@Success
  2702. @1@Continue
  2703. @2@Busy
  2704. @3@Denied
  2705. 2@2@major version
  2706. 2@0@minor version
  2707. 1@CARD8@number of alternate-servers-hint
  2708. 1@CARD8@authorization-index
  2709. 2@a/4@length of alternate-servers-hint
  2710. 2@(d+q)/4@length of authorization-data
  2711. a@LISTofALTERNATESERVER@alternate-servers-hint
  2712. d@LISTofBYTE@authorization-data
  2713. q@@unused, q=pad(d)
  2714. .TE
  2715. .LP
  2716. If STATUS is Busy or Denied, the protocol stops and
  2717. the connection is closed.  If STATUS is Continue, the 
  2718. client is expected to respond with additional data, to 
  2719. which the server responds with a new status value and 
  2720. more data.  This dialog continues until the status is 
  2721. set to Success, or until the server sets STATUS to Busy 
  2722. or Denied and closes the connection:
  2723. .LP
  2724. .TS
  2725. tab (@) ;
  2726. lw(.25i) lw(2i) l.
  2727. ->
  2728. 4@1+(d+q)/4@length
  2729. d@LISTofBYTE@more-authorization-data
  2730. q@@unused, q=pad(d)
  2731. =>
  2732. 4@2+(d+q)/4@length
  2733. 2@CARD16@status
  2734. @0@Success
  2735. @1@Continue
  2736. @2@Busy
  2737. @3@Denied
  2738. 2@@unused
  2739. d@LISTofBYTE@more-authorization-data
  2740. q@@unused, q=pad(d)
  2741. .TE
  2742. .LP
  2743. When STATUS is Success, the protocol resumes with the
  2744. following sent by the server:
  2745. .LP
  2746. .TS
  2747. tab (@) ;
  2748. lw(.25i) lw(2i) l.
  2749. 4@3+(v+w)/4@length of rest of data
  2750. 2@CARD16@maximum-request-length
  2751. 2@v@length of vendor string
  2752. 4@CARD32@release-number
  2753. v@STRING8@vendor-string
  2754. w@@unused, w=pad(v)
  2755. .TE
  2756. .LP
  2757. Once the connection has been established, the client may send the
  2758. following requests:
  2759. .TS
  2760. tab (@) ;
  2761. lfB s s
  2762. lw(.25i) lw(2i) l.
  2763. NoOp
  2764. .sp 6p
  2765. 1@0@major-opcode
  2766. 1@@unused
  2767. 2@1@length
  2768. .TE
  2769. .sp 12p
  2770. .TS
  2771. tab (@) ;
  2772. lfB s s
  2773. lw(.25i) lw(2i) l.
  2774. ListExtensions
  2775. 1@1@major-opcode
  2776. 1@@unused
  2777. 2@1@length
  2778. =>
  2779. 1@0@type reply
  2780. 1@CARD8@number of names
  2781. 2@CARD16@sequence-number
  2782. 4@2+(n+p)/4@length
  2783. n@LISTofSTRNAME@names
  2784. p@@unused, p=pad(n)
  2785. .TE
  2786. .sp 12p
  2787. .TS
  2788. tab (@) ;
  2789. lfB s s
  2790. lw(.25i) lw(2i) l.
  2791. QueryExtension
  2792. .sp 6p
  2793. 1@2@major-opcode
  2794. 1@n@length of name
  2795. 2@1+(n+p)/4@length
  2796. n@STRING8@name
  2797. p@@unused, p=pad(n)
  2798. =>
  2799. 1@0@type reply
  2800. 1@BOOL@present
  2801. 2@CARD16@sequence-number
  2802. 4@5@length
  2803. 2@CARD16@major-version
  2804. 2@CARD16@minor-version
  2805. 1@CARD8@major-opcode
  2806. 1@CARD8@first-event
  2807. 1@CARD8@number-events
  2808. 1@CARD8@first-error
  2809. 1@CARD8@number-errors
  2810. 3@@unused
  2811. .TE
  2812. .sp 12p
  2813. .TS
  2814. tab (@) ;
  2815. lfB s s
  2816. lw(.25i) lw(2i) l.
  2817. ListCatalogues
  2818. 1@3@major-opcode
  2819. 1@@unused
  2820. 2@3+(n+p)/4@length
  2821. 4@CARD32@max-names
  2822. 2@n@length of pattern
  2823. 2@@unused
  2824. n@STRING8@pattern
  2825. p@@unused, p=pad(n)
  2826. =>+
  2827. 1@0@type reply
  2828. 1@@unused
  2829. 2@CARD16@sequence-number
  2830. 4@4+(n+p)/4@length
  2831. 4@CARD32@replies-following-hint
  2832. 4@CARD32@number of catalogue-names
  2833. n@LISTofSTRNAME@catalogue-names
  2834. p@@unused, p=pad(n)
  2835. .TE
  2836. .sp 12p
  2837. .TS
  2838. tab (@) ;
  2839. lfB s s
  2840. lw(.25i) lw(2i) l.
  2841. SetCatalogues
  2842. 1@4@major-opcode
  2843. 1@CARD8@number of catalogue-names
  2844. 2@1+(n+p)/4@length
  2845. n@LISTofSTRNAME@catalogue-names
  2846. p@@unused, p=pad(n)
  2847. .TE
  2848. .sp 12p
  2849. .TS
  2850. tab (@) ;
  2851. lfB s s
  2852. lw(.25i) lw(2i) l.
  2853. GetCatalogues
  2854. .sp 6p
  2855. 1@5@major-opcode
  2856. 1@@unused
  2857. 2@1@length
  2858. =>
  2859. 1@0@type reply
  2860. 1@CARD8@number of catalogue-names
  2861. 2@CARD16@sequence-number
  2862. 4@2+(n+p)/4@length
  2863. n@LISTofSTRNAME@catalogue-names
  2864. p@@unused, p=pad(n)
  2865. .TE
  2866. .sp 12p
  2867. .TS
  2868. tab (@) ;
  2869. lfB s s
  2870. lw(.25i) lw(2i) l.
  2871. SetEventMask
  2872. .sp 6p
  2873. 1@6@major-opcode
  2874. 1@CARD8@extension-opcode
  2875. 2@2@length
  2876. 4@EVENTMASK@event-mask
  2877. .TE
  2878. .sp 12p
  2879. .TS
  2880. tab (@) ;
  2881. lfB s s
  2882. lw(.25i) lw(2i) l.
  2883. GetEventMask
  2884. .sp 6p
  2885. 1@7@major-opcode
  2886. 1@CARD8@extension-opcode
  2887. 2@1@length
  2888. =>
  2889. 1@0@type reply
  2890. 1@@unused
  2891. 2@CARD16@sequence-number
  2892. 4@3@length
  2893. 4@EVENTMASK@event-mask
  2894. .TE
  2895. .sp 12p
  2896. .TS
  2897. tab (@) ;
  2898. lfB s s
  2899. lw(.25i) lw(2i) l.
  2900. CreateAC
  2901. .sp 6p
  2902. 1@8@major-opcode
  2903. 1@CARD8@number of authorization-protocols
  2904. 2@2+a/4@length
  2905. 4@ACCESSCONTEXT@ac
  2906. a@LISTofAUTH@authorization-protocols
  2907. =>
  2908. 1@0@type reply
  2909. 1@CARD8@authorization-index
  2910. 2@CARD16@sequence-number
  2911. 4@3+(d+q)/4@length
  2912. 2@CARD16@status
  2913. @0@Success
  2914. @1@Continue
  2915. @2@Busy
  2916. @3@Denied
  2917. 2@@unused
  2918. d@LISTofBYTE@authorization-data
  2919. q@@unused, q=pad(d)
  2920. .TE
  2921. .LP
  2922. If STATUS is Continue, the client is expected to respond
  2923. with additional data, to which the server responds with
  2924. a new status value and more data.  This dialog continues
  2925. until the status is set to Success, Busy, or Denied at
  2926. which point the request is finished.
  2927. .LP
  2928. .TS
  2929. tab (@) ;
  2930. lw(.25i) lw(2i) l.
  2931. ->
  2932. 4@1+(d+q)/4@length
  2933. d@LISTofBYTE@more-authorization-data
  2934. q@@unused, q=pad(d)
  2935. =>
  2936. 4@2+(d+q)/4@length
  2937. 2@CARD16@status
  2938. @0@Success
  2939. @1@Continue
  2940. @2@Busy
  2941. @3@Denied
  2942. 2@@unused
  2943. d@LISTofBYTE@authorization-data
  2944. q@@unused, q=pad(d)
  2945. .TE
  2946. .sp 12p
  2947. .ne 3
  2948. .TS
  2949. tab (@) ;
  2950. lfB s s
  2951. lw(.25i) lw(2i) l.
  2952. FreeAC
  2953. .sp 6p
  2954. 1@9@major-opcode
  2955. 1@@unused
  2956. 2@2@length
  2957. 4@ACCESSCONTEXT@ac
  2958. .TE
  2959. .sp 12p
  2960. .TS
  2961. tab (@) ;
  2962. lfB s s
  2963. lw(.25i) lw(2i) l.
  2964. SetAuthorization
  2965. .sp 6p
  2966. 1@10@major-opcode
  2967. 1@@unused
  2968. 2@2@length
  2969. 4@ACCESSCONTEXT@ac
  2970. .TE
  2971. .sp 12p
  2972. .TS
  2973. tab (@) ;
  2974. lfB s s
  2975. lw(.25i) lw(2i) l.
  2976. SetResolution
  2977. .sp 6p
  2978. 1@11@major-opcode
  2979. 1@n@number of resolutions
  2980. 2@1+(6*n+p)/4@length
  2981. 6*n@LISTofRESOLUTION@resolutions
  2982. p@p=pad(6*n)
  2983. .TE
  2984. .sp 12p
  2985. .TS
  2986. tab (@) ;
  2987. lfB s s
  2988. lw(.25i) lw(2i) l.
  2989. GetResolution
  2990. .sp 6p
  2991. 1@12@major-opcode
  2992. 1@@unused
  2993. 2@1@length
  2994. =>
  2995. 1@0@type reply
  2996. 1@n@number of resolutions
  2997. 2@CARD16@sequence-number
  2998. 4@2+(6*n+p)/4@length
  2999. 6*n@LISTofRESOLUTION@resolutions
  3000. p@@p=pad(6*n)
  3001. .TE
  3002. .sp 12p
  3003. .TS
  3004. tab (@) ;
  3005. lfB s s
  3006. lw(.25i) lw(2i) l.
  3007. ListFonts
  3008. .sp 6p
  3009. 1@13@major-opcode
  3010. 1@@unused
  3011. 2@3+(n+p)/4@length
  3012. 4@CARD32@max-names
  3013. 2@n@length of pattern
  3014. 2@@unused
  3015. n@STRING8@pattern
  3016. p@@unused, p=pad(n)
  3017. =>+
  3018. 1@0@type reply
  3019. 1@@unused
  3020. 2@CARD16@sequence-number
  3021. 4@4+(n+p)/4@length
  3022. 4@CARD32@replies-following-hint
  3023. 4@CARD32@number of font-names
  3024. n@LISTofSTRNAME@font-names
  3025. p@@unused, p=pad(n)
  3026. .TE
  3027. .sp 12p
  3028. .TS
  3029. tab (@) ;
  3030. lfB s s
  3031. lw(.25i) lw(2i) l.
  3032. ListFontsWithXInfo
  3033. .sp 6p
  3034. 1@14@major-opcode
  3035. 1@@unused
  3036. 2@3+(n+p)/4@length
  3037. 4@CARD32@max-names
  3038. 2@n@length of pattern
  3039. 2@@unused
  3040. n@STRING8@pattern
  3041. p@@unused, p=pad(n)
  3042. .T&
  3043. l s s
  3044. lw(.25i) lw(2i) l.
  3045. =>+(except for last in series)
  3046. 1@0@type reply
  3047. 1@n@length of name
  3048. 2@CARD16@sequence-number
  3049. 4@3+(n+p+f)/4@length
  3050. 4@CARD32@replies-hint
  3051. f@XFONTINFO@font info
  3052. n@STRING8@name
  3053. p@@unused, p=pad(n)
  3054. @@@
  3055. .T&
  3056. l s s
  3057. lw(.25i) lw(2i) l.
  3058. =>(last in series)
  3059. 1@0@type reply
  3060. 1@0@last-reply indicator
  3061. 2@CARD16@sequence-number
  3062. 4@2@reply length
  3063. .TE
  3064. .sp 12p
  3065. .TS
  3066. tab (@) ;
  3067. lfB s s
  3068. lw(.25i) lw(2i) l.
  3069. OpenBitmapFont
  3070. .sp 6p
  3071. 1@15@major-opcode
  3072. 1@@unused
  3073. 2@4+(n+p)/4@length
  3074. 4@FONTID@fontid
  3075. 4@BITMAPFORMATMASK@format-mask
  3076. 4@BITMAPFORMAT@format
  3077. n@STRNAME@pattern
  3078. p@@unused, p=pad(n)
  3079. =>
  3080. 1@0@type reply
  3081. 1@BOOL@otherid-valid
  3082. 2@CARD16@sequence-number
  3083. 4@4@length
  3084. 4@FONTID@otherid
  3085. 1@BOOL@cachable
  3086. 3@@unused
  3087. .TE
  3088. .sp 12p
  3089. .TS
  3090. tab (@) ;
  3091. lfB s s
  3092. lw(.25i) lw(2i) l.
  3093. QueryXInfo
  3094. .sp 6p
  3095. 1@16@major-opcode
  3096. 1@@unused
  3097. 2@2@length
  3098. 4@FONTID@fontid
  3099. =>
  3100. 1@0@type reply
  3101. 1@@unused
  3102. 2@CARD16@sequence-number
  3103. 4@2+f/4@length
  3104. f@XFONTINFO@font info
  3105. .TE
  3106. .sp 12p
  3107. .TS
  3108. tab (@) ;
  3109. lfB s s
  3110. lw(.25i) lw(2i) l.
  3111. QueryXExtents8
  3112. .sp 6p
  3113. 1@17@major-opcode
  3114. 1@BOOL@range
  3115. 2@3+(n+p)/4@length
  3116. 4@FONTID@fontid
  3117. 4@n@number chars entries
  3118. n@STRING8@chars
  3119. p@@unused, p=pad(n)
  3120. =>
  3121. 1@0@type reply
  3122. 1@@unused
  3123. 2@CARD16@sequence-number
  3124. 4@3+3*n@length
  3125. 4@n@number of extents
  3126. 12*n@LISTofXCHARINFO@extents
  3127. .TE
  3128. .sp 12p
  3129. .TS
  3130. tab (@) ;
  3131. lfB s s
  3132. lw(.25i) lw(2i) l.
  3133. QueryXExtents16
  3134. .sp 6p
  3135. 1@18@major-opcode
  3136. 1@BOOL@range
  3137. 2@3+(2*n+p)/4@length
  3138. 4@FONTID@fontid
  3139. 4@n@number chars entries
  3140. 2*n@LISTofCHAR2B@chars
  3141. p@@unused, p=pad(2*n)
  3142. =>
  3143. 1@0@type reply
  3144. 1@@unused
  3145. 2@CARD16@sequence-number
  3146. 4@3+3*n@length
  3147. 4@n@number of extents
  3148. 12*n@LISTofXCHARINFO@extents
  3149. .TE
  3150. .sp 12p
  3151. .TS
  3152. tab (@) ;
  3153. lfB s s
  3154. lw(.25i) lw(2i) l.
  3155. QueryXBitmaps8
  3156. .sp 6p
  3157. 1@19@major-opcode
  3158. 1@BOOL@range
  3159. 2@4+(n+p)/4@length
  3160. 4@FONTID@fontid
  3161. 4@BITMAPFORMAT@format
  3162. 4@n@number of chars entries
  3163. n@STRING8@chars
  3164. p@@unused, p=pad(n)
  3165. =>+
  3166. 1@0@type reply
  3167. 1@@unused
  3168. 2@CARD16@sequence-number
  3169. 4@5+2*n+(m+p)/4@length
  3170. 4@CARD32@replies-following-hint
  3171. 4@n@number of offsets
  3172. 4@m@number of bytes of glyph images
  3173. 8*n@LISTofOFFSET32@offsets
  3174. m@LISTofBYTE@glyph images
  3175. p@@unused, p=pad(m)
  3176. .TE
  3177. .sp 12p
  3178. .TS
  3179. tab (@) ;
  3180. lfB s s
  3181. lw(.25i) lw(2i) l.
  3182. QueryXBitmaps16
  3183. .sp 6p
  3184. 1@20@major-opcode
  3185. 1@BOOL@range
  3186. 2@4+(2*n+p)/4@length
  3187. 4@FONTID@fontid
  3188. 4@BITMAPFORMAT@format
  3189. 4@n@number of chars entries
  3190. 2*n@LISTofCHAR2B@chars
  3191. p@@unused, p=pad(2*n)
  3192. =>
  3193. 1@0@type reply
  3194. 1@@unused
  3195. 2@CARD16@sequence-number
  3196. 4@5+2*n+(m+p)/4@length
  3197. 4@CARD32@replies-following-hint
  3198. 4@n@number of offsets
  3199. 4@m@number of bytes of glyph images
  3200. 8*n@LISTofOFFSET32@offsets
  3201. m@LISTofBYTE@glyph images
  3202. p@@unused, p=pad(m)
  3203. .TE
  3204. .sp 12p
  3205. .TS
  3206. tab (@) ;
  3207. lfB s s
  3208. lw(.25i) lw(2i) l.
  3209. CloseFont
  3210. .sp 6p
  3211. 1@21@major-opcode
  3212. 1@@unused
  3213. 2@2@length
  3214. 4@FONTID@fontid
  3215. .TE
  3216. .NH 2
  3217. Errors
  3218. .XS
  3219. \*(SN Errors
  3220. .XE
  3221. .LP
  3222. .TS
  3223. tab (@) ;
  3224. lfB s s
  3225. n lw(2i) l.
  3226. Request
  3227. .sp 6p
  3228. 1@1@type error
  3229. 1@0@Request
  3230. 2@CARD16@sequence-number
  3231. 4@4@length
  3232. 4@TIMESTAMP@timestamp
  3233. 1@CARD8@major-opcode
  3234. 1@CARD8@minor-opcode
  3235. 2@@unused
  3236. .TE
  3237. .sp 12p
  3238. .TS
  3239. tab (@) ;
  3240. lfB s s
  3241. n lw(2i) l.
  3242. Format
  3243. .sp 6p
  3244. 1@1@type error
  3245. 1@1@Format
  3246. 2@CARD16@sequence-number
  3247. 4@5@length
  3248. 4@TIMESTAMP@timestamp
  3249. 1@CARD8@major-opcode
  3250. 1@CARD8@minor-opcode
  3251. 2@@unused
  3252. 4@BITMAPFORMAT@bad-format
  3253. .TE
  3254. .sp 12p
  3255. .TS
  3256. tab (@) ;
  3257. lfB s s
  3258. n lw(2i) l.
  3259. Font
  3260. .sp 6p
  3261. 1@1@type error
  3262. 1@2@Font
  3263. 2@CARD16@sequence-number
  3264. 4@5@length
  3265. 4@TIMESTAMP@timestamp
  3266. 1@CARD8@major-opcode
  3267. 1@CARD8@minor-opcode
  3268. 2@@unused
  3269. 4@FONTID@bad-fontid
  3270. .TE
  3271. .sp 12p
  3272. .TS
  3273. tab (@) ;
  3274. lfB s s
  3275. n lw(2i) l.
  3276. Range
  3277. .sp 6p
  3278. 1@1@type error
  3279. 1@3@Range
  3280. 2@CARD16@sequence-number
  3281. 4@5@length
  3282. 4@TIMESTAMP@timestamp
  3283. 1@CARD8@major-opcode
  3284. 1@CARD8@minor-opcode
  3285. 2@@unused
  3286. 4@RANGE@bad-range
  3287. .TE
  3288. .sp 12p
  3289. .TS
  3290. tab (@) ;
  3291. lfB s s
  3292. n lw(2i) l.
  3293. EventMask
  3294. .sp 6p
  3295. 1@1@type error
  3296. 1@4@EventMask
  3297. 2@CARD16@sequence-number
  3298. 4@5@length
  3299. 4@TIMESTAMP@timestamp
  3300. 1@CARD8@major-opcode
  3301. 1@CARD8@minor-opcode
  3302. 2@@unused
  3303. 4@EVENTMASK@event-mask
  3304. .TE
  3305. .sp 12p
  3306. .TS
  3307. tab (@) ;
  3308. lfB s s
  3309. n lw(2i) l.
  3310. AccessContext
  3311. .sp 6p
  3312. 1@1@type error
  3313. 1@5@AccessContext
  3314. 2@CARD16@sequence-number
  3315. 4@5@length
  3316. 4@TIMESTAMP@timestamp
  3317. 1@CARD8@major-opcode
  3318. 1@CARD8@minor-opcode
  3319. 2@@unused
  3320. 4@ACCESSCONTEXT@access context
  3321. .TE
  3322. .sp 12p
  3323. .TS
  3324. tab (@) ;
  3325. lfB s s
  3326. n lw(2i) l.
  3327. IDChoice
  3328. .sp 6p
  3329. 1@1@type error
  3330. 1@6@IDChoice
  3331. 2@CARD16@sequence-number
  3332. 4@5@length
  3333. 4@TIMESTAMP@timestamp
  3334. 1@CARD8@major-opcode
  3335. 1@CARD8@minor-opcode
  3336. 2@@unused
  3337. 4@FONTID@bad-fontid
  3338. .TE
  3339. .sp 12p
  3340. .TS
  3341. tab (@) ;
  3342. lfB s s
  3343. n lw(2i) l.
  3344. Name
  3345. .sp 6p
  3346. 1@1@type error
  3347. 1@7@Name
  3348. 2@CARD16@sequence-number
  3349. 4@4@length
  3350. 4@TIMESTAMP@timestamp
  3351. 1@CARD8@major-opcode
  3352. 1@CARD8@minor-opcode
  3353. 2@@unused
  3354. .TE
  3355. .sp 12p
  3356. .TS
  3357. tab (@) ;
  3358. lfB s s
  3359. n lw(2i) l.
  3360. Resolution
  3361. .sp 6p
  3362. 1@1@type error
  3363. 1@8@Resolution
  3364. 2@CARD16@sequence-number
  3365. 4@5@length
  3366. 4@TIMESTAMP@timestamp
  3367. 1@CARD8@major-opcode
  3368. 1@CARD8@minor-opcode
  3369. 6@RESOLUTION@resolution
  3370. .TE
  3371. .sp 12p
  3372. .TS
  3373. tab (@) ;
  3374. lfB s s
  3375. n lw(2i) l.
  3376. Alloc
  3377. .sp 6p
  3378. 1@1@type error
  3379. 1@9@Alloc
  3380. 2@CARD16@sequence-number
  3381. 4@4@length
  3382. 4@TIMESTAMP@timestamp
  3383. 1@CARD8@major-opcode
  3384. 1@CARD8@minor-opcode
  3385. 2@@unused
  3386. .TE
  3387. .sp 12p
  3388. .TS
  3389. tab (@) ;
  3390. lfB s s
  3391. n lw(2i) l.
  3392. Length
  3393. .sp 6p
  3394. 1@1@type error
  3395. 1@10@Length
  3396. 2@CARD16@sequence-number
  3397. 4@5@length
  3398. 4@TIMESTAMP@timestamp
  3399. 1@CARD8@major-opcode
  3400. 1@CARD8@minor-opcode
  3401. 2@@unused
  3402. 4@CARD32@bad-length
  3403. .TE
  3404. .sp 12p
  3405. .TS
  3406. tab (@) ;
  3407. lfB s s
  3408. n lw(2i) l.
  3409. Implementation
  3410. .sp 6p
  3411. 1@1@type error
  3412. 1@11@Implementation
  3413. 2@CARD16@sequence-number
  3414. 4@4@length
  3415. 4@TIMESTAMP@timestamp
  3416. 1@CARD8@major-opcode
  3417. 1@CARD8@minor-opcode
  3418. 2@@unused
  3419. .TE
  3420. .NH 2
  3421. Events
  3422. .XS
  3423. \*(SN Events
  3424. .XE
  3425. .LP
  3426. .TS
  3427. tab (@) ;
  3428. lfB s s
  3429. n lw(2i) l.
  3430. KeepAlive
  3431. .sp 6p
  3432. 1@2@type event
  3433. 1@0@event KeepAlive
  3434. 2@CARD16@sequence-number
  3435. 4@3@length
  3436. 4@TIMESTAMP@timestamp
  3437. .TE
  3438. .sp 12p
  3439. .TS
  3440. tab (@) ;
  3441. lfB s s
  3442. n lw(2i) l.
  3443. CatalogueListNotify
  3444. .sp 6p
  3445. 1@2@type event
  3446. 1@1@event CatalogueListNotify
  3447. 2@CARD16@sequence-number
  3448. 4@4@length
  3449. 4@TIMESTAMP@timestamp
  3450. 1@BOOL@added
  3451. 1@BOOL@deleted
  3452. 2@@unused
  3453. .TE
  3454. .sp 12p
  3455. .TS
  3456. tab (@) ;
  3457. lfB s s
  3458. n lw(2i) l.
  3459. FontListNotify
  3460. .sp 6p
  3461. 1@2@type event
  3462. 1@2@event FontListNotify
  3463. 2@CARD16@sequence-number
  3464. 4@4@length
  3465. 4@TIMESTAMP@timestamp
  3466. 1@BOOL@added
  3467. 1@BOOL@deleted
  3468. 2@@unused
  3469. .TE
  3470. .NH 1
  3471. Acknowledgements
  3472. .XS
  3473. \*(SN Acknowledgements
  3474. .XE
  3475. .LP
  3476. This document represents the culmination of several years of debate and
  3477. experiments done under the auspices of the MIT X Consortium font working group.
  3478. Although this was a group effort, the author remains responsible for any errors
  3479. or omissions.  The protocol presented here was primarily designed by Jim
  3480. Fulton, Keith Packard, and Bob Scheifler.  Special thanks goes to Ned
  3481. Batchelder, Jim Flowers, and Axel Deininger for their invigorating comments
  3482. which never failed to make this a better document.
  3483. Stephen Gildea edited version 2 of this document.
  3484. Finally, David Lemke 
  3485. deserves great credit for designing and coding the sample implementation.
  3486. .NH 1
  3487. References
  3488. .XS
  3489. \*(SN References
  3490. .XE
  3491. .LP
  3492. All of the following documents are X Consortium standards available from MIT:
  3493. .LP
  3494. [1]  Scheifler, Robert W.  ``X Window System Protocol Version 11''
  3495. .LP
  3496. [2]  Adobe Systems.  ``Bitmap Distribution Format 2.1''
  3497. .LP
  3498. [3]  MIT X Consortium.  ``X Logical Font Description Conventions, Version 1.4''
  3499. .bp
  3500. .XS
  3501. Appendix A \- Suggested Licensing Policies
  3502. .XE
  3503. .ce 10
  3504. .sp 5
  3505. \s+2\fBAppendix A\fP\s-2
  3506. .sp 
  3507. \s+1\fBSuggested Licensing Policies\fP\s-1
  3508. .ce 0
  3509. .sp
  3510. .LP
  3511. The authorization data passed by the client in the initial connection
  3512. setup information may be used by the font server to implement restrictions
  3513. on which fonts may be accessed.  Furthermore, the font server is free to
  3514. refuse new connections at any time.
  3515. .LP
  3516. Configuration or management of the license restrictions is outside the scope of
  3517. the font service protocol and is done in a server-dependent manner.  Possible
  3518. policies might include, but are not limited to, combinations of the following:
  3519. .IP "a."
  3520. No restrictions - anyone may access any fonts.  The server neither
  3521. refuses any connections nor generates AccessContext errors on any 
  3522. fonts.  For environments without specially-licensed fonts, this is
  3523. sufficient.
  3524. .IP "b."
  3525. Per-machine - only those clients connecting from a known set of
  3526. machines are permitted access.  The server could get the address 
  3527. of the connection and look in a list of    allowed machines. 
  3528. .IP "c."
  3529. Per-user - only a known set of users may access the fonts.  The
  3530. server can use the authorization data (such as a Kerberos ticket
  3531. or a Secure RPC credential) to verify the identity of the user
  3532. and then look in a list of allowed users.
  3533. .IP "d."
  3534. Simultaneous Use - only a certain number of clients may use a given
  3535. font at any one time.  Additional clients would receive AccessContext
  3536. errors if they attempt to open the font.  This is only effective if
  3537. the initial clients keep the font open for the entire time that it
  3538. is being used (even if all of the data has been transmitted and is
  3539. being cached).
  3540. .IP "e."
  3541. Postage Meter - a particular font may only be accessed a limited
  3542. number of times before its license must be renewed.  Each time
  3543. the font is opened, the server decrements a counter.  When the
  3544. counter reaches zero, all further attempts to open the font
  3545. return an AccessContext error.
  3546. .LP
  3547. It should be noted that chaining of font servers (obtaining font data from
  3548. other font servers) may conflict with certain license policies.
  3549. .bp
  3550. .XS
  3551. Appendix B \- Implementation Suggestions
  3552. .XE
  3553. .sp 5
  3554. .ce 10
  3555. \s+2\fBAppendix B\fP\s-2
  3556. .sp 
  3557. \s+1\fBImplementation Suggestions\s-1\fP
  3558. .ce 0
  3559. .sp
  3560. .LP
  3561. Font server implementations will probably wish to use techniques such as the
  3562. following to avoid limits on the number of simultaneous connections:
  3563. .IP "a."
  3564. The initial connection information returned by the font
  3565. server contains the names of other font servers that 
  3566. may be used as substitutes.  A font server may refuse to
  3567. accept a connection, indicating that the client should
  3568. try one of the alternatives instead.
  3569. .IP "b."
  3570. On operating systems that support processing forking, font
  3571. servers might choose to fork so that the child can continue
  3572. processing the existing connections and the parent can accept
  3573. new connections.  Such implementations are encouraged to use
  3574. shared memory so that in-memory font databases can be shared.
  3575. .IP "c."
  3576. On operating systems that support passing stream file descriptors
  3577. between processes, cooperating font servers could collect
  3578. connections in a single process when there are few connections
  3579. and spread them among several processes as the load increases.
  3580. .IP "d."
  3581. If a font client is unable to connect to a server (as opposed
  3582. to having the connection terminated), it should retry for an
  3583. implementation-dependent length of time (see Xlib's 
  3584. handling of ECONNREFUSED in XConnDis.c).
  3585. .\"
  3586. .\" print Table of Contents page
  3587. .EH ''''
  3588. .OH ''''
  3589. .bp
  3590. .EF ''''
  3591. .OF ''''
  3592. .PX
  3593.