specs/fsproto.xml

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