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