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