specs/fsproto.xml

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