fsproto.xml revision ea1d6981
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> 27Permission to use, copy, modify, distribute, and sell this 28documentation for any purpose is hereby granted without fee, 29provided that the above copyright notice and this permission 30notice appear in all copies. Network Computing Devices, Inc. 31makes no representations about the suitability for any purpose 32of the information in this document. This documentation is 33provided “as is” without express or implied warranty. 34</para> 35</legalnotice> 36 37<legalnotice> 38<para role="multiLicensing">Copyright © 1994 X Consortium</para> 39<para> 40Permission is hereby granted, free of charge, to any person obtaining a copy 41of this software and associated documentation files (the “Software”), to deal 42in the Software without restriction, including without limitation the rights 43to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 44copies of the Software, and to permit persons to whom the Software is 45furnished to do so, subject to the following conditions: 46</para> 47<para> 48The above copyright notice and this permission notice shall be included in 49all copies or substantial portions of the Software. 50</para> 51<para> 52THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 53IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 54FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 55X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN 56AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 57CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 58</para> 59<para> 60Except as contained in this notice, the name of the X Consortium shall not be 61used in advertising or otherwise to promote the sale, use or other dealings 62in 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> 70The management of fonts in large, heterogeneous environments is one of the 71hardest aspects of using the X Window System 72<footnote id='footnote1'><para> 73<firstterm><trademark>X Window System</trademark></firstterm> 74is a trademark of The Open Group. 75</para></footnote> 76. Multiple formats and the lack of 77a consistent mechanism for exporting font data to all displays on a network 78prevent the transparent use of applications across different display platforms. 79The X Font Service protocol is designed to address this and other issues, with 80specific emphasis on the needs of the core X protocol. Upward-compatible 81changes (typically in the form of new requests) are expected as consensus is 82reached on new features (particularly outline font support). 83</para> 84<para> 85Currently, most X displays use network file protocols such as 86<acronym>NFS</acronym> and <acronym>TFTP</acronym> to 87obtain raw font data which they parse directly. Since a common binary format 88for this data doesn't exist, displays must be able to interpret a variety of 89formats if they are to be used with different application hosts. This leads to 90wasted code and data space and a loss of interoperability as displays are used 91in unforeseen environments. 92</para> 93<para> 94By moving the interpretation of font data out of the X server into a separate 95service on the network, these problems can be greatly reduced. In addition, 96new technologies, such as dynamically generating bitmaps from scaled or outline 97fonts, can be provided to all displays transparently. For horizontal text, 98caching techniques and increased processor power can potentially make 99rasterization more efficient on large, centralized hosts than on individual 100displays. 101</para> 102<para> 103Each font server provides sets of fonts that may be listed and queried for 104header, property, glyph extents, and bitmap information. This data is 105transmitted over the network using a binary format (with variations to support 106different bit- and byte-orders) designed to minimize the amount of processing 107required by the display. Since the font server, rather than the display, is 108responsible for parsing the raw font data, new formats can be used by all 109displays by modifying a single font server. 110</para> 111<para> 112From the user's point of view, font servers are simply a new type of name in 113the X font path. Network name services allow descriptive names (such as 114DEPARTMENT-FONTS or APPLICATION-FONTS) to be translated into proper network 115addresses. X displays send requests to and read replies from the font server 116rather than reading directly from files. Since the X Font Service protocol is 117designed to allow subsets of the font data to be requested, displays may easily 118implement 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> 128In this document, the words <firstterm>client</firstterm> and 129<firstterm>server</firstterm> refer to the consumer and 130provider of a font, respectively, unless otherwise indicated. It is important 131to note that in this context, the X server is also a font client. 132</para> 133<para> 134The X Font Service protocol does not require any changes to the core X protocol 135or to any applications. To the user, font servers are simply additional types 136of font path elements. As such, X servers may connect to multiple font 137servers, as shown in Figure 2.1. Although the font protocol is geared towards 138the X Window System, it may be also used by other consumers of font data (such 139as 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> 162Clients communicate with the font server using the request/reply/event model 163over 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 167of Digital Equipment Corporation. 168</para></footnote> 169etc.). Font servers are responsible for providing data in the bit and byte 170orders requested by the client. The set of requests and events provided in the 171first version of the X Font Service protocol is limited to supporting the needs 172of the bitmap-oriented core X Window System protocol. Extensions are expected 173as new needs evolve. 174</para> 175<para> 176A font server reads raw font data from a variety of sources (possibly 177including other font servers) and converts it into a common format that is 178transmitted to the client using the protocol described in 179<link linkend='Protocol'>Section 4</link>. New font 180formats are handled by adding new converters to a font server, as shown in 181Figure 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> 211The server may choose to provide named sets of fonts called 212<firstterm>catalogues</firstterm>. 213Clients may specify which of the sets should be used in listing or opening a 214font. 215</para> 216 217<para> 218An event mechanism similar to that used in the X protocol is provided for 219asynchronous notification of clients by the server. 220</para> 221 222<para> 223Clients 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 225granted to particular fonts. This is particularly useful for clients whose 226authorization changes over time (such as an X server that can verify the 227identity of the user). 228</para> 229<para> 230Implementations that wish to provide additional requests or events may use the 231extension mechanism. Adding to the core font service protocol (with the 232accompanying change in the major or minor version numbers) is reserved to the X 233Consortium. 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> 243Font clients that expose font server names to the user are encouraged to 244provide ways of naming font servers symbolically (e.g. DEPARTMENT-FONTS). 245However, for environments that lack appropriate name services 246transport-specific names are necessary. Since these names do occur in the 247protocol, clients and servers should support at least the applicable formats 248described below. Formats for additional transports may be registered with the 249X 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> 258The 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 264where <replaceable>hostname</replaceable> is either symbolic (such as 265<systemitem class="systemname">expo.lcs.mit.edu</systemitem>) or numeric 266decimal (such as <systemitem class="ipaddress">18.30.0.212</systemitem>). 267The <replaceable>ipportnumber</replaceable> is the port on which the 268font server is listening for connections. 269The <replaceable>cataloguelist</replaceable> string at 270the end is optional and specifies a plus-separated list of catalogues 271that 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> 285The 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 291where <replaceable>nodename</replaceable> is either symbolic (such as 292<systemitem class="systemname">SRVNOD</systemitem>) or the 293numeric decimal form of the DECnet address (such as 294<systemitem class="ipaddress">44.70</systemitem>). 295The <replaceable>objname</replaceable> is normal, case-insensitive DECnet 296object name. The <replaceable>cataloguelist</replaceable> string 297at the end is 298optional and specifies a plus-separated list of catalogues that may be 299requested. 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> 315The protocol described below uses the request/reply/error model and is 316specified using the same conventions outlined in 317<olink targetdoc='x11protocol' targetptr='Syntactic_Conventions'>Section 2 318of the core X Window System protocol</olink> 319<xref linkend="References:x11proto"/>: 320</para> 321<itemizedlist> 322 <listitem> 323 <para> 324<!-- .IP \(bu 5 --> 325Data type names are spelled in upper case with no word separators, 326as in: <link linkend="Data_Types:FONTID"><type>FONTID</type></link> 327 </para> 328 </listitem> 329 <listitem> 330 <para> 331<!-- .IP \(bu 5 --> 332Alternate values are capitalized with no word separators, 333as in: <constant>MaxWidth</constant> 334 </para> 335 </listitem> 336 <listitem> 337 <para> 338<!-- .IP \(bu 5 --> 339Structure element declarations are in lower case with hyphens 340as word separators, as in: <structfield>byte-order-msb</structfield> 341 </para> 342 <note> 343 <para> 344Structure element names are referred to in 345upper case (e.g. <structfield>BYTE-ORDER-MSB</structfield>) when used in 346descriptions to set them off from the surrounding 347text. When this document is typeset they will be 348printed in lower case in a distinct font. 349 </para> 350 </note> 351 </listitem> 352 <listitem> 353 <para> 354Type declarations have the form <quote><type>name</type>: type</quote>, 355as in: <type>CARD8</type>: 8-bit byte 356 </para> 357 </listitem> 358 <listitem> 359 <para> 360Comma-separated lists of alternate values are enclosed in 361braces, as in: { <constant>Min</constant>, <constant>MaxWidth</constant>, 362<constant>Max</constant> } 363 </para> 364 </listitem> 365 <listitem> 366 <para> 367Comma-separated lists of structure elements are enclosed in 368brackets, as in: [ <structfield>byte1</structfield>: <type>CARD8</type>, 369<structfield>byte2</structfield>: <type>CARD8</type> ] 370 </para> 371 </listitem> 372</itemizedlist> 373 374<para> 375A type with a prefix <quote>LISTof</quote> represents a counted list of 376elements 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> 385The 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> 403This value is specified in the CreateAC request as the identifier 404to be used when referring to a particular AccessContext resource 405within the server. These resources are used by the server to 406store client-specified authorization information. This 407information may be used by the server to determine whether or not 408the client should be granted access to particular font data. 409</para> 410<para> 411In order to preserve the integrity of font licensing being performed by 412the font server, care must be taken by a client to properly represent the 413identity of the true user of the font. Some font clients will in fact 414be servers (for example, X servers) requesting fonts for their own clients. 415Other font clients may be doing work on behalf of a number of different 416users over time (for example, print spoolers). 417</para> 418<para> 419<type>AccessContext</type>s 420must be created (with 421<link linkend="Requests:CreateAC"><function>CreateAC</function></link>) 422and switched among (with 423<link linkend="Requests:SetAuthorization"><function>SetAuthorization</function></link>) 424to 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> <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> 446This structure specifies the <structfield>NAME</structfield>, 447encoded in <acronym>ISO</acronym> 8859-1 according 448to <link linkend='Font_Server_Naming'>Section 3</link>, 449of another font server that may be useful as a 450substitute for this font server. 451The <structfield>SUBSET</structfield> field indicates 452whether or not the alternate server is likely to only contain a 453subset of the fonts available from this font server. This 454information is returned during the initial connection setup and 455may be used by the client to find a backup server in case of 456failure. 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> <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> 477This structure specifies the name of an authorization protocol and 478initial data for that protocol. It is used in the authorization 479negotiation in the initial connection setup and in the CreateAC 480request. 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> <structfield>byte-order-msb</structfield>:</entry><entry> 1 bit,</entry></row> 512 <row><entry> <structfield>bit-order-msb</structfield>:</entry><entry> 1 bit,</entry></row> 513 <row><entry> <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> <structfield>zero-pad</structfield>:</entry><entry> 4 bits,</entry></row> 517 <row><entry> <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> <structfield>zero-pad</structfield>:</entry><entry> 2 bits,</entry></row> 522 <row><entry> <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> <structfield>zero-pad</structfield>:</entry><entry> 2 bits,</entry></row> 527 <row><entry> <structfield>zero-pad</structfield>:</entry><entry> 16 bits,</entry></row> 528 <row><entry>]</entry></row> 529 </tbody> 530 </tgroup> 531 </informaltable> 532 533<para> 534This structure specifies how glyph images are transmitted in 535response to 536<link linkend="Requests:QueryXBitmaps8"><function>QueryXBitmaps8</function></link> 537and 538<link linkend="Requests:QueryXBitmaps16"><function>QueryXBitmaps16</function></link> 539requests. 540</para> 541<para> 542If the <structfield>BYTE-ORDER-MSB</structfield> bit 543<literal>(1 << 0)</literal> is set, the Most Significant 544Byte of each scanline unit is returned first. Otherwise, the 545Least Significant Byte is returned first. 546</para> 547<para> 548If the <structfield>BIT-ORDER-MSB</structfield> bit 549<literal>(1 << 1)</literal> is set, the left-most bit in 550each glyph scanline unit is stored in the Most Significant Bit of 551each transmitted scanline unit. Otherwise, the left-most bit is 552stored in the Least Significant Bit. 553</para> 554<para> 555The <structfield>IMAGE-RECT</structfield> field specifies a rectangle of 556pixels within the 557glyph 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 << 2)</literal></entry></row> 566 <row><entry><constant>ImageRectMaxWidth</constant></entry><entry><literal>(1 << 2)</literal></entry></row> 567 <row><entry><constant>ImageRectMax</constant></entry><entry><literal>(2 << 2)</literal></entry></row> 568 </tbody> 569 </tgroup> 570 </informaltable> 571</para> 572<para> 573For a glyph with extents <link linkend="Data_Types:XCHARINFO"><type>XCHARINFO</type></link> in a font with header 574information <link linkend="Data_Types:XFONTINFO"><type>XFONTINFO</type></link>, the <structfield>IMAGE-RECT</structfield> 575values 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> 582This refers to the minimal bounding rectangle 583surrounding the inked pixels in the glyph. This is the 584most compact representation. The edges of the rectangle 585are: 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> 600This refers to the scanlines between the 601glyph's ascent and descent, padded on the left to the minimum 602left-bearing (or 0, whichever is less) and on the right to 603the maximum right-bearing (or logical-width, whichever is 604greater). All glyph images share a common horizontal 605origin. This is a combination of <constant>ImageRectMax</constant> in the 606horizontal direction and <constant>ImageRectMin</constant> in the vertical 607direction. The edges of the rectangle are: 608 609<literallayout class="monospaced"> 610left: min (<structfield>XFONTINFO.MIN-BOUNDS.LBEARING</structfield>, 0) 611right: max (<structfield>XFONTINFO.MAX-BOUNDS.RBEARING</structfield>, 612 <structfield>XFONTINFO.MAX-BOUNDS.WIDTH</structfield>) 613top: <structfield>XCHARINFO.ASCENT</structfield> 614bottom: <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> 624This refers to all scanlines, from the maximum 625ascent (or the font ascent, whichever is greater) to the 626maximum descent (or the font descent, whichever is greater), 627padded to the same horizontal extents as <constant>MaxWidth</constant>. 628All glyph images have the same sized bitmap and share a 629common origin. This is the least compact representation, 630but may be the easiest or most efficient (particularly for 631character cell fonts) for some clients to use. The edges of 632the rectangle are: 633 634<literallayout class="monospaced"> 635left: min (<structfield>XFONTINFO.MIN-BOUNDS.LBEARING</structfield>, 0) 636right: max (<structfield>XFONTINFO.MAX-BOUNDS.RBEARING</structfield>, 637 <structfield>XFONTINFO.MAX-BOUNDS.WIDTH</structfield>) 638top: max (<structfield>XFONTINFO.FONT-ASCENT</structfield>, 639 <structfield>XFONTINFO.MAX-BOUNDS.ASCENT</structfield>) 640bottom: 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> 649The <structfield>SCANLINE-PAD</structfield> field specifies the number of 650bits (8, 16, 32, 651or 64) to which each glyph scanline is padded before transmitting. 652It 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 << 8)</literal></entry></row> 660 <row><entry><constant>ScanlinePad16</constant></entry><entry><literal>(1 << 8)</literal></entry></row> 661 <row><entry><constant>ScanlinePad32</constant></entry><entry><literal>(2 << 8)</literal></entry></row> 662 <row><entry><constant>ScanlinePad64</constant></entry><entry><literal>(3 << 8)</literal></entry></row> 663 </tbody> 664 </tgroup> 665 </informaltable> 666</para> 667<para> 668The <structfield>SCANLINE-UNIT</structfield> field specifies the number of 669bits (8, 16, 32, or 64) that should be treated as a unit for swapping. 670This 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 672alternate 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 << 12)</literal></entry></row> 681 <row><entry><constant>ScanlineUnit16</constant></entry><entry><literal>(1 << 12)</literal></entry></row> 682 <row><entry><constant>ScanlineUnit32</constant></entry><entry><literal>(2 << 12)</literal></entry></row> 683 <row><entry><constant>ScanlineUnit64</constant></entry><entry><literal>(3 << 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. 690All unspecified bits must be zero. 691</para> 692<para> 693Use 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> 713This 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 << 0)</literal></entry></row> 721 <row><entry><constant>BitOrderMask</constant></entry><entry><literal>(1 << 1)</literal></entry></row> 722 <row><entry><constant>ImageRectMask</constant></entry><entry><literal>(1 << 2)</literal></entry></row> 723 <row><entry><constant>ScanlinePadMask</constant></entry><entry><literal>(1 << 3)</literal></entry></row> 724 <row><entry><constant>ScanlineUnitMask</constant></entry><entry><literal>(1 << 4)</literal></entry></row> 725 </tbody> 726 </tgroup> 727 </informaltable> 728</para> 729<para> 730Unspecified 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> 750This is a boolean value containing one of the following alternate 751values: 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> 782This is an unsigned byte of data whose encoding 783is 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> 808These are unsigned numbers. The latter two are byte-swapped when 809the 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> 829This structure specifies an individual character code within 830either a 2-dimensional matrix (using <structfield>BYTE1</structfield> 831and <structfield>BYTE2</structfield> as the row and column indices, 832respectively) or a vector (using <structfield>BYTE1</structfield> and 833<structfield>BYTE2</structfield> as most- and least-significant bytes, 834respectively). This data type is treated as a pair of 8-bit values and 835is 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> 857This is a mask of bits indicating which of an extension's (or the 858core's) maskable events the client would like to receive. Each 859bit indicates one or more events, and a bit value of one indicates 860interest in a corresponding set of events. The following bits are 861defined 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> 864and 865<link linkend="Requests:GetEventMask"><function>GetEventMask</function></link> 866requests): 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 << 0)</literal></entry></row> 875 <row><entry><constant>FontListChangeMask</constant></entry><entry><literal>(1 << 1)</literal></entry></row> 876 </tbody> 877 </tgroup> 878 </informaltable> 879</para> 880 881<para> 882If 883<constant>CatalogueListChangeMask</constant> 884is set, client is interested in 885receiving 886<link linkend="Events:CatalogueListNotify"><function>CatalogueListNotify</function></link> 887events. If 888<constant>FontListChangeMask</constant> 889is set, the client is interested in 890receiving 891<link linkend="Events:FontListNotify"><function>FontListNotify</function></link> 892events. 893</para> 894<para> 895Extensions that provide additional events may define their own 896event masks. These event masks have their own scope and may use 897the same bit values as the core or other extensions. 898 </para> 899 <para> 900All unused bits must be set to zero. In 901<link linkend="Requests:SetEventMask"><function>SetEventMask</function></link> 902requests, if 903any bits are set that are not defined for the extension (or core) 904for 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> 907request), an 908<link linkend="Errors:EventMask"><errorname>EventMask</errorname></link> 909error is generated. 910 </para> 911 <para> 912This 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> 933This is specified by the client in the request 934<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 935as the identifier to be used when referring to a particular open 936font. 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> 957This is a 32-bit value in which the top 3 bits must be clear, and 958at least 1 other bit must be set (yielding a range of 1 through 9592<superscript>29</superscript>-1). 960It is specified by the client to represent objects in 961the server. Identifiers are scoped according to their type are 962private to the client; thus, the same identifier may be used for 963both a <link linkend="Data_Types:FONTID"><type>FONTID</type></link> and an <link linkend="Data_Types:ACCESSCONTEXT"><type>ACCESSCONTEXT</type></link> 964as well as by multiple clients. 965</para> 966<para> 967An <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> 991These are signed numbers. The latter two are byte-swapped when 992the 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> <structfield>length</structfield>:</entry><entry><type>CARD32</type> ]</entry></row> 1009 </tbody> 1010 </tgroup> 1011 </informaltable> 1012 <para> 1013This structure indicates a position and length within a block of 1014data. 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> <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> 1036This structure describes the list of properties provided by a 1037font. Strings for all of the properties names and values are 1038stored within the data block and are located using a table of 1039offsets and lengths. 1040 </para> 1041 <para> 1042This 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> <structfield>value</structfield>:</entry><entry><link linkend="Data_Types:OFFSET32"><type>OFFSET32</type></link>,</entry></row> 1060 <row><entry> <structfield>type</structfield>:</entry><entry><type>CARD8</type>,</entry></row> 1061 <row><entry> <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> 1067This structure specifies the position, length, and type of 1068of data for a property. 1069 </para> 1070 <para> 1071The <structfield>NAME</structfield> field specifies the position and length 1072(which must be 1073greater than zero) of the property name relative to the beginning 1074of the <structfield>PROPINFO.DATA</structfield> block for this font. 1075The interpretation of 1076the position and length of the <structfield>VALUE</structfield> field is 1077determined by the <structfield>TYPE</structfield> field, which contains 1078one 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> 1092which 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> 1099This property contains a counted string of bytes. The 1100data is stored in the <structfield>PROPINFO.DATA</structfield> 1101block beginning at 1102relative byte VALUE.POSITION (beginning with zero), extending 1103for 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> 1112This property contains a unsigned, 32-bit number stored 1113as 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> 1122This property contains a signed, 32-bit number stored as 1123an <type>INT32</type> in VALUE.POSITION (VALUE.LENGTH is zero). 1124 </para> 1125 </listitem> 1126 </varlistentry> 1127</variablelist> 1128This 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> 1150This structure specifies a range of character codes. A single 1151character 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 1158font's <structfield>XFONTINFO.CHAR-RANGE.MAX-CHAR</structfield>, 1159the 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> <structfield>y-resolution</structfield>:</entry><entry><type>CARD16</type>,</entry></row> 1177 <row><entry> <structfield>decipoint-size</structfield>:</entry><entry><type>CARD16</type> ]</entry></row> 1178 </tbody> 1179 </tgroup> 1180 </informaltable> 1181 1182 <para> 1183This structure specifies resolution and point size to be used in 1184resolving partially-specified scaled font names. The 1185<structfield>X-RESOLUTION</structfield> and 1186<structfield>Y-RESOLUTION</structfield> are measured in 1187pixels-per-inch and must be greater than zero. 1188The <structfield>DECIPOINT-SIZE</structfield> is the preferred font 1189size, 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> 1210This is a counted list of 1-byte character codes, typically 1211encoded 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> 1214is 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> 1236This is the number of milliseconds that have passed since a 1237server-dependent origin. It is provided in errors and events and is 1238permitted 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> <structfield>width</structfield>:</entry><entry><type>INT16</type>,</entry></row> 1255 <row><entry> <structfield>ascent</structfield>, <structfield>descent</structfield>:</entry><entry><type>INT16</type>,</entry></row> 1256 <row><entry> <structfield>attributes</structfield>:</entry><entry><type>CARD16</type> ]</entry></row> 1257 </tbody> 1258 </tgroup> 1259 </informaltable> 1260 1261 <para> 1262This structure specifies the ink extents and horizontal escapement 1263(also known as the set- or logical width) of an individual 1264character. The first five values represent directed distances in 1265a coordinate system whose origin is aligned with the lower-left 1266edge of the left-most pixel of the glyph baseline (i.e. the 1267baseline 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> 1272The <structfield>LBEARING</structfield> field specifies the 1273directed distance measured to the 1274right from the origin to the left edge of the left-most inked 1275pixel in the glyph. 1276 </para> 1277 <para> 1278The <structfield>RBEARING</structfield> field specifies the 1279directed distance (measured to 1280the right) from the origin to the right edge of the right-most 1281inked pixel in the glyph. 1282 </para> 1283 <para> 1284The <structfield>WIDTH</structfield> field specifies the 1285directed distance (measured to the 1286right) from the origin to the position where the next character 1287should appear (called the <firstterm>escapement point</firstterm>). This 1288distance includes any whitespace used for intercharacter padding and is 1289also 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> 1294The <structfield>ASCENT</structfield> field specifies the 1295directed distance (measured up) 1296from the baseline to the top edge of the top-most inked pixel 1297in the glyph. 1298 </para> 1299 <para> 1300The <structfield>DESCENT</structfield> field specifies the 1301directed distance (measured 1302down) from the baseline to the bottom edge of the bottom-most 1303inked pixel. 1304 </para> 1305 <para> 1306The <structfield>ATTRIBUTES</structfield> field specifies 1307glyph-specific information that 1308is passed through the application. If this value is not being 1309used, it should be zero. 1310 </para> 1311 <para> 1312The ink bounding box of a glyph is defined to be the smallest 1313rectangle that encloses all of the inked pixels. This box has 1314a width of 1315<structfield>RBEARING</structfield> − <structfield>LBEARING</structfield> 1316pixels 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> <structfield>drawing-direction</structfield>:</entry><entry>{ <constant>LeftToRight</constant>, <constant>RightToLeft</constant> }</entry></row> 1334 <row><entry> <structfield>char-range</structfield>:</entry><entry><link linkend="Data_Types:RANGE"><type>RANGE</type></link>,</entry></row> 1335 <row><entry> <structfield>default-char</structfield>:</entry><entry><link linkend="Data_Types:CHAR2B"><type>CHAR2B</type></link>,</entry></row> 1336 <row><entry> <structfield>min-bounds</structfield>:</entry><entry><link linkend="Data_Types:XCHARINFO"><type>XCHARINFO</type></link>,</entry></row> 1337 <row><entry> <structfield>max-bounds</structfield>:</entry><entry><link linkend="Data_Types:XCHARINFO"><type>XCHARINFO</type></link>,</entry></row> 1338 <row><entry> <structfield>font-ascent</structfield>:</entry><entry><type>INT16</type>,</entry></row> 1339 <row><entry> <structfield>font-descent</structfield>:</entry><entry><type>INT16</type>,</entry></row> 1340 <row><entry> <structfield>properties</structfield>:</entry><entry><link linkend="Data_Types:PROPINFO"><type>PROPINFO</type></link> ]</entry></row> 1341 </tbody> 1342 </tgroup> 1343 </informaltable> 1344 <para> 1345This structure specifies attributes related to the font as a 1346whole. 1347 </para> 1348 <para> 1349The <structfield>FLAGS</structfield> field is a bit mask containing zero 1350or 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 << 0)</literal></entry></row> 1359 <row><entry><constant>InkInside</constant></entry><entry><literal>(1 << 1)</literal></entry></row> 1360 <row><entry><constant>HorizontalOverlap</constant></entry><entry><literal>(1 << 2)</literal></entry></row> 1361 </tbody> 1362 </tgroup> 1363 </informaltable> 1364 1365which 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> 1372If this bit is set, all of the characters in the range given by 1373<structfield>CHAR-RANGE</structfield> have glyphs encoded in 1374the font. If this bit is clear, some of the characters 1375may 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> 1384If this bit is set, the inked pixels of each glyph 1385fall within the rectangle described by the font's ascent, 1386descent, origin, and the glyph's escapement point. If 1387this bit is clear, there may be glyphs whose ink extends 1388outside 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> 1397If this bit is set, the two ink bounding 1398boxes (smallest rectangle enclosing the inked pixels) of 1399some pairs of glyphs in the font may overlap when displayed 1400side-by-side (i.e. the second character is imaged at the 1401escapement point of the first) on a common baseline. If 1402this bit is clear, there are no pairs of glyphs whose ink 1403bounding 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> 1412The <structfield>DRAWING-DIRECTION</structfield> field contains a hint 1413indicating whether most of the character metrics have a positive (or 1414<quote><constant>LeftToRight</constant></quote>) logical width or a 1415negative (<quote><constant>RightToLeft</constant></quote>) logical width. It 1416contains 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> 1430The <structfield>CHAR-RANGE.MIN-CHAR</structfield> 1431and <structfield>CHAR-RANGE.MAX-CHAR</structfield> fields specify the 1432first and last character codes that have glyphs encoded in this font. 1433All fonts must have at least one encoded glyph (in which case the 1434<structfield>MIN-CHAR</structfield> and <structfield>MAX-CHAR</structfield> 1435are equal), but are not required to have glyphs 1436encoded at all positions between the first and last characters. 1437</para> 1438<para> 1439The <structfield>DEFAULT-CHAR</structfield> field specifies 1440the character code of the glyph 1441that the client should substitute for unencoded characters. Requests 1442for extents or bitmaps for an unencoded character generate zero-filled 1443metrics and a zero-length glyph bitmap, respectively. 1444</para> 1445<para> 1446The <structfield>MIN-BOUNDS</structfield> and 1447<structfield>MAX-BOUNDS</structfield> fields contain the minimum and maximum 1448values of each of the extents field of all encoded characters in the 1449font (i.e. non-existent characters are ignored). 1450</para> 1451<para> 1452The <structfield>FONT-ASCENT</structfield> and 1453<structfield>FONT-DESCENT</structfield> fields specify the font designer's 1454logical height of the font, above and below the baseline, 1455respectively. The sum of the two values is often used as the 1456vertical line spacing of the font. Individual glyphs are permitted 1457to have ascents and descents that are greater than these values. 1458</para> 1459<para> 1460The <structfield>PROPERTIES</structfield> field contains the 1461property data associated with this font. 1462</para> 1463<para> 1464This 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> 1475This section describes the requests that may be sent by the client and the 1476replies or errors that are generated in response. Versions of the protocol 1477with the same major version are required to be upward-compatible. 1478</para> 1479<para> 1480Every request on a given connection is implicitly assigned a sequence number, 1481starting with 1, that is used in replies, error, and events. Servers are 1482required to generate replies and errors in the order in which the corresponding 1483requests are received. Servers are permitted to add or remove fonts to the 1484list visible to the client between any two requests, but requests must be 1485processed atomically. Each request packet is at least 4 bytes long and 1486contains 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 1503The <parameter>MAJOR-OPCODE</parameter> specifies which core request or 1504extension 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. 1507Otherwise, the <parameter>MINOR-OPCODE</parameter> specifies which extension 1508request this packet represents. The <parameter>LENGTH</parameter> field 1509specifies the number of 4-byte units contained within the packet 1510and must be at least one. If this field contains a value greater than one it 1511is followed by (<parameter>LENGTH</parameter> - 1) * 4 bytes 1512of request-specific data. Unless 1513otherwise specified, unused bytes are not required to be zero. 1514</para> 1515<para> 1516If a request packet contains too little or too much data, the server returns 1517a <link linkend="Errors:Length"><errorname>Length</errorname></link> error. 1518If the server runs out of internal 1519resources (such as memory) while processing a request, it returns an 1520<link linkend="Errors:Alloc"><errorname>Alloc</errorname></link> error. 1521If a server is deficient (and therefore non-compliant) and is unable to 1522process a request, it may return an 1523<link linkend="Errors:Implementation"><errorname>Implementation</errorname></link> error. 1524If a client uses an extension request without previously having issued a 1525<link linkend="Requests:QueryExtension"><function>QueryExtension</function></link> 1526request for that extension, the server responds with a 1527<link linkend="Errors:Request"><errorname>Request</errorname></link> 1528error. If the server encounters a request with an unknown 1529<parameter>MAJOR-OPCODE</parameter> or <parameter>MINOR-OPCODE</parameter>, 1530it responds with a 1531<link linkend="Errors:Request"><errorname>Request</errorname></link> 1532error. 1533At most one error is generated per request. If more than one error condition 1534is encountered in processing a requests, the choice of which error is returned 1535is server-dependent. 1536</para> 1537<para> 1538Core requests have <parameter>MAJOR-OPCODE</parameter> values between 0 and 1539127, inclusive. Extension requests have <parameter>MAJOR-OPCODE</parameter> 1540values between 128 and 255, inclusive, that are assigned by by the server. 1541All <parameter>MINOR-OPCODE</parameter> values in extension requests are 1542between 0 and 255, inclusive. 1543</para> 1544<para> 1545Each 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> 1562The <parameter>TYPE</parameter> field has a value of zero. 1563The <parameter>DATA-OR-UNUSED</parameter> field may be used to 1564encode one byte of reply-specific data (see 1565<link linkend="Encoding::Requests">Section 5.2 on request encoding</link>). 1566The least-significant 16 bits of the sequence number of the request that 1567generated the reply are stored in the <parameter>SEQUENCE-NUMBER</parameter> 1568field. The <parameter>LENGTH</parameter> field specifies the number of 15694-byte units in this reply packet, including the fields described above, 1570and must be at least two. If <parameter>LENGTH</parameter> is greater 1571than two, the fields described above are followed by 1572(<parameter>LENGTH</parameter> - 2) * 4 bytes of additional data. 1573</para> 1574<para> 1575Requests 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> 1601If a request does not generate a reply, the ▶ and result lines are 1602omitted. If a request may generate multiple replies, the ▶ is replaced by 1603a ▶+. In the authorization data exchanges in the initial connection setup 1604and the CreateAC request, ◀ indicates data sent by the client in response 1605to data sent by the server. 1606</para> 1607<para> 1608The protocol begins with the establishment of a connection over a 1609mutually-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> 1629The initial byte of the connection specifies the 1630<parameter>BYTE-ORDER</parameter> in 1631which subsequent 16-bit and 32-bit numeric values are to be 1632transmitted. The octal value <literal>102</literal> 1633(<acronym>ASCII</acronym> uppercase <quote><literal>B</literal></quote>) 1634indicates that the most-significant byte is to be transmitted 1635first; the octal value <literal>154</literal> 1636(<acronym>ASCII</acronym> lowercase <quote><literal>l</literal></quote>) 1637indicates that the least-significant byte is to be transmitted first. 1638If any other value is encountered the server closes the 1639connection without any response. 1640</para> 1641 <para> 1642The <parameter>CLIENT-MAJOR-PROTOCOL-VERSION</parameter> and 1643<parameter>CLIENT-MINOR-PROTOCOL-VERSION</parameter> specify 1644which version of the 1645font service protocol the client would like to use. If the 1646client can support multiple versions, the highest version 1647should be given. This version of the protocol has a 1648major version of 2 and a minor version of 0. 1649 </para> 1650 <para> 1651The <parameter>AUTHORIZATION-PROTOCOLS</parameter> 1652contains a list of protocol names and 1653optional initial data for which the client can provide 1654information. The server may use this to determine which 1655protocol to use or as part of the initial exchange of 1656authorization 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> 1676The <parameter>SERVER-MAJOR-PROTOCOL-VERSION</parameter> and 1677<parameter>SERVER-MINOR-PROTOCOL-VERSION</parameter> specify 1678the version of the font 1679service protocol that the server expects from the client. If 1680the server supports the version specified by the client, this 1681version number should be returned. If the client has 1682requested a higher version than is supported by the server, 1683the server's highest version should be returned. Otherwise, 1684if the client has requested a lower version than is supported 1685by the server, the server's lowest version should be returned. 1686It is the client's responsibility to decide whether or not it 1687can match this version of the protocol. 1688 </para> 1689 <para> 1690The <parameter>ALTERNATE-SERVERS-HINT</parameter> 1691is a list of other font servers 1692that may have related sets of fonts (determined by means 1693outside this protocol, typically by the system administrator). 1694Clients may choose to contact these font servers if the 1695connection is rejected or lost. 1696 </para> 1697 <para> 1698The <parameter>STATUS</parameter> field indicates whether the server accepted, 1699rejected, or would like more information about the connection. 1700It 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> 1716If <parameter>STATUS</parameter> is <constant>Denied</constant>, 1717the server has rejected the client's authorization information. 1718If <parameter>STATUS</parameter> is <constant>Busy</constant>, the server has 1719simply decided that it cannot provide fonts to this client at 1720this time (it may be able to at a later time). In both cases, 1721<parameter>AUTHORIZATION-INDEX</parameter> is set to zero, 1722no authorization-data is 1723returned, and the server closes the connection after sending 1724the data described so far. 1725 </para> 1726 <para> 1727Otherwise the <parameter>AUTHORIZATION-INDEX</parameter> is set to the index 1728(beginning with 1) into the <parameter>AUTHORIZATION-PROTOCOLS</parameter> 1729list of the protocol that the server will use for this connection. If 1730the server does not want to use any of the given protocols, 1731this value is set to zero. The <parameter>AUTHORIZATION-DATA</parameter> 1732field is used to send back authorization protocol-dependent data to the 1733client (such as a challenge, authentication of the server, 1734etc.). 1735 </para> 1736<para> 1737If <parameter>STATUS</parameter> is <constant>Success</constant>, 1738the following section of protocol is omitted. Otherwise, if 1739<parameter>STATUS</parameter> is <constant>Continue</constant>, 1740the server expects 1741more authorization data from the client (i.e. the connection 1742setup 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> 1759The values in <parameter>STATUS</parameter> have the same meanings as described 1760above. This section of protocol is repeated until the server 1761either accepts (sets <parameter>STATUS</parameter> to 1762<constant>Success</constant>) or rejects (sets <parameter>STATUS</parameter> 1763to <constant>Denied</constant> or <constant>Busy</constant>) the connection. 1764</para> 1765<para> 1766Once the connection has been accepted and <parameter>STATUS</parameter> 1767is <constant>Success</constant>, 1768an implicit AccessContext is created for the authorization 1769data and the protocol continues with the following data sent 1770from 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> 1787The <parameter>REMAINING-LENGTH</parameter> specifies the length in 4-byte 1788units of the remaining data to be transmitted to the client. The 1789<parameter>MAXIMUM-REQUEST-LENGTH</parameter> specifies the largest request 1790size in 4-byte units that is accepted by the server and must have a 1791value of at least 4096. Requests with a length field larger 1792than this value are ignored and a 1793<link linkend="Errors:Length"><errorname>Length</errorname></link> 1794error is returned. 1795The <parameter>VENDOR</parameter> string specifies the name of the 1796manufacturer of the font server. The 1797<parameter>RELEASE-NUMBER</parameter> specifies the particular 1798release of the server in a manufacturer-dependent manner. 1799</para> 1800</section> 1801<section><title /> 1802<para> 1803After the connection is established and the setup information has been 1804exchanged, 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> 1821This request does nothing. It is typically used in response 1822to a 1823<link linkend="Events:KeepAlive"><function>KeepAlive</function></link> 1824event. 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> 1845This request returns the names of the extension packages 1846that are supported by the server. Extension names are 1847case-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> 1877This request determines whether or not the extension package specified by 1878<parameter>NAME</parameter> (encoded in <acronym>ISO</acronym> 8859-1) is 1879supported by the server and that there is sufficient number of major opcode, 1880event, and error codes available. If so, then <parameter>PRESENT</parameter> 1881is set to <constant>True</constant>, <parameter>MAJOR-VERSION</parameter> 1882and <parameter>MINOR-VERSION</parameter> are set to the 1883respective major and minor version numbers of the protocol 1884that the server would prefer; <parameter>MAJOR-OPCODE</parameter> is set to 1885the value to use in extension requests; <parameter>FIRST-EVENT</parameter> 1886is set to the value of the first extension-specific event code or zero if the 1887extension does not have any events; <parameter>NUMBER-EVENTS</parameter> is 1888set to the number of new events that the event defines; 1889<parameter>FIRST-ERROR</parameter> 1890is set to the value of the first extension-specific error code 1891or zero if the extension does not define any new errors; and 1892<parameter>NUMBER-ERRORS</parameter> is set to the number of 1893new errors the extension defines. 1894 </para> 1895 <para> 1896Otherwise, <parameter>PRESENT</parameter> is set to 1897<constant>False</constant> and the remaining fields are 1898set to zero. 1899 </para> 1900 <para> 1901The server is free to return different values to different 1902clients. Therefore, clients must use this request before 1903issuing any of the requests in the named extension package or 1904using the 1905<link linkend="Requests:SetEventMask"><function>SetEventMask</function></link> request to express interest in any of 1906this extension's events. Otherwise, a 1907<link linkend="Errors:Request"><errorname>Request</errorname></link> 1908error 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> 1932This request returns a list of at most <parameter>MAX-NAMES</parameter> names 1933of collections (called catalogues) of fonts that match 1934the specified <parameter>PATTERN</parameter>. In the pattern (which is encoded 1935in <acronym>ISO</acronym> 8859-1), the 1936<quote><literal>?</literal></quote> character (octal <literal>77</literal>) 1937matches any single character; the 1938<quote><literal>*</literal></quote> character (octal <literal>52</literal>) 1939matches any series of zero or more characters; and alphabetic 1940characters match either upper- or lowercase. The 1941returned <parameter>NAMES</parameter> are encoded in 1942<acronym>ISO</acronym> 8859-1 and may contain 1943mixed character cases. 1944 </para> 1945 <para> 1946If <parameter>PATTERN</parameter> is of zero length or 1947<parameter>MAX-NAMES</parameter> is equal to zero, 1948one reply containing a zero-length list of names is returned. 1949This may be used to synchronize the client with the server. 1950 </para> 1951 <para> 1952Servers are free to add or remove catalogues to the set returned by 1953<function>ListCatalogues</function> 1954between any two requests. This request is not 1955cumulative; repeated uses are processed in isolation and do 1956result in an iteration through the list. 1957 </para> 1958 <para> 1959To reduce the amount of buffering needed by the server, the 1960list of names may be split across several reply packets, so 1961long as the names arrive in the same order that they would 1962have appeared had they been in a single packet. The 1963<parameter>REPLIES-FOLLOWING-HINT</parameter> field in all but the last reply 1964contains a positive value that specifies the number of 1965replies that are likely, but not required, to follow. In the 1966last reply, which may contain zero or more names, this field 1967is 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> 1987This request sets the list of catalogues whose fonts should be 1988visible to the client. The union of the fonts provided by 1989each of the named catalogues forms the set of fonts whose 1990names match patterns in 1991<link linkend="Requests:ListFonts"><function>ListFonts</function></link>, 1992<link linkend="Requests:ListFontsWithXInfo"><function>ListFontsWithXInfo</function></link>, 1993and 1994<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 1995requests. The catalogue names are 1996case-insensitive and are encoded in <acronym>ISO</acronym> 8859-1. A zero-length 1997list resets the client's catalogue list to the 1998server-dependent default. 1999 </para> 2000 <para> 2001If any of the catalogue names are invalid, a 2002<link linkend="Errors:Name"><errorname>Name</errorname></link> 2003error 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> 2023This request returns the current list of catalogue names 2024(encoded in <acronym>ISO</acronym> 8859-1) associated with the client. These 2025catalogues determine the set of fonts that are visible 2026to 2027<link linkend="Requests:ListFonts"><function>ListFonts</function></link>, 2028<link linkend="Requests:ListFontsWithXInfo"><function>ListFontsWithXInfo</function></link>, 2029and 2030<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link>. 2031A zero-length list indicates the server's default set of 2032fonts. Catalogue names are case-insensitive and may be 2033returned 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> 2054This request specifies the set of maskable events that the 2055extension indicated by <parameter>EXTENSION-OPCODE</parameter> 2056(or zero for the core) 2057should generate for the client. Event masks are limited in 2058scope to the extension (or core) for which they are defined, 2059so expressing interest in events from one or more extensions 2060requires multiple uses of this request. 2061 </para> 2062 <para> 2063The default event mask if 2064<function>SetEventMask</function> 2065has not been called 2066is zero, indicating no interest in any maskable events. 2067Some events are not maskable and cannot be blocked. 2068 </para> 2069 <para> 2070If <parameter>EXTENSION-OPCODE</parameter> is not a valid extension 2071opcode previously returned by 2072<link linkend="Requests:QueryExtension"><function>QueryExtension</function></link> 2073or zero, a 2074<link linkend="Errors:Request"><errorname>Request</errorname></link> 2075error is 2076returned. If <parameter>EVENT-MASK</parameter> contains any bits that do not 2077correspond to valid events for the specified extension (or 2078core), an 2079<link linkend="Errors:EventMask"><errorname>EventMask</errorname></link> 2080error is returned and the request is 2081ignored. 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> 2102This request returns the set of maskable core events the 2103extension indicated by <parameter>EXTENSION-OPCODE</parameter> 2104(or the core if zero) 2105should generate for the client. Non-maskable events are 2106always sent to the client. 2107 </para> 2108 <para> 2109If <parameter>EXTENSION-OPCODE</parameter> is not a valid extension opcode 2110previously returned by 2111<link linkend="Requests:QueryExtension"><function>QueryExtension</function></link> 2112or zero, a 2113<link linkend="Errors:Request"><errorname>Request</errorname></link> 2114error 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> 2138This request creates a new 2139<type>AccessContext</type> 2140object within the 2141server containing the specified authorization data. When 2142this 2143<type>AccessContext</type> 2144is selected by the client using the 2145<link linkend="Requests:SetAuthorization"><function>SetAuthorization</function></link> 2146request, the data may be used by the server 2147to determine whether or not the client should be granted 2148access to particular font information. 2149 </para> 2150 <para> 2151If <parameter>STATUS</parameter> is <constant>Denied</constant>, the server 2152rejects the client's authorization information and does not associate 2153<parameter>AC</parameter> with any valid <type>AccessContext</type>. 2154In this case, <parameter>AUTHORIZATION-INDEX</parameter> is set 2155to zero, and zero bytes of <parameter>AUTHORIZATION-DATA</parameter> 2156is returned. 2157 </para> 2158 <para> 2159Otherwise, <parameter>AUTHORIZATION-INDEX</parameter> is set to the index 2160(beginning with 1) into the <parameter>AUTHORIZATION-PROTOCOLS</parameter> 2161list of the protocol 2162that the server will use for this connection. If the server 2163does not want to use any of the given protocols, this value is 2164set to zero. The <parameter>AUTHORIZATION-DATA</parameter> field is used 2165to send back authorization protocol-dependent data to the client (such 2166as a challenge, authentication of the server, etc.). 2167 </para> 2168 <para> 2169If <parameter>STATUS</parameter> is <constant>Continue</constant>, 2170the client is expected to continue 2171the request by sending the following protocol and receiving 2172the indicated response from the server. This continues 2173until <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> 2191Once the connection has been accepted and <parameter>STATUS</parameter> 2192is <constant>Success</constant>, the request is complete. 2193 </para> 2194 <para> 2195If <parameter>AC</parameter> is not in the range 2196[1..2<superscript>29</superscript>-1] or is already associated 2197with 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> 2217This request indicates that the specified <parameter>AC</parameter> should 2218no longer be associated with a valid access context. 2219If <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> 2223request), an implicit 2224<link linkend="Requests:SetAuthorization"><function>SetAuthorization</function></link> 2225of <constant>None</constant> is done to 2226restore the 2227<type>AccessContext</type> 2228established for the initial 2229connection setup. Operations on fonts that were opened under 2230<parameter>AC</parameter> are not affected. The client may reuse the 2231value of <parameter>AC</parameter> in a subsequent 2232<link linkend="Requests:CreateAC"><function>CreateAC</function></link> 2233request. 2234 </para> 2235 <para> 2236If <parameter>AC</parameter> isn't associated with any valid authorization 2237previously created by 2238<link linkend="Requests:CreateAC"><function>CreateAC</function></link>, an 2239<link linkend="Errors:AccessContext"><errorname>AccessContext</errorname></link> 2240error 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> 2259This request sets the 2260<type>AccessContext</type> 2261to be used for subsequent 2262requests (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> 2268and 2269<link linkend="Requests:CloseFont"><function>CloseFont</function></link> 2270which are done under the 2271<type>AccessContext</type> 2272of the 2273corresponding 2274<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 2275). 2276An <parameter>AC</parameter> of <constant>None</constant> restores the 2277<type>AccessContext</type> 2278established for the initial connection setup. 2279 </para> 2280 <para> 2281If <parameter>AC</parameter> is neither <constant>None</constant> 2282nor a value associated with a valid <type>AccessContext</type> 2283previously created by 2284<link linkend="Requests:CreateAC"><function>CreateAC</function></link>, 2285an 2286<link linkend="Errors:AccessContext"><errorname>AccessContext</errorname></link> 2287error 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> 2307This request provides a hint as to the resolution and 2308preferred point size of the drawing surfaces for which the 2309client will be requesting fonts. The server may use this 2310information to set the RESOLUTION_X and RESOLUTION_Y fields 2311of scalable <acronym>XLFD</acronym> font names, to order sets of names based on 2312their resolutions, and to choose the server-dependent 2313instance that is used when a partially-specified scalable 2314fontname is opened. 2315 </para> 2316 <para> 2317If a zero-length list of <link linkend="Data_Types:RESOLUTION"><type>RESOLUTION</type></link>s is given, the 2318server-dependent default value is restored. Otherwise, if 2319elements of all of the specified <link linkend="Data_Types:RESOLUTION"><type>RESOLUTION</type></link>s are non-zero, the 2320default resolutions for this client are changed. 2321 </para> 2322 <para> 2323If a <link linkend="Data_Types:RESOLUTION"><type>RESOLUTION</type></link> entry contains a zero, 2324a <link linkend="Errors:Resolution"><errorname>Resolution</errorname></link> error is 2325returned 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> 2345This request returns the current list of default resolutions. 2346If a client has not performed a 2347<link linkend="Requests:SetResolution"><function>SetResolution</function></link>, 2348a 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> 2371This request returns a list of at most <parameter>MAX-NAMES</parameter> 2372font names that match the specified <parameter>PATTERN</parameter>, 2373according to matching rules 2374of the <olink targetdoc='xlfd' targetptr='xlfd'><citetitle>X Logical 2375Font Description Conventions</citetitle></olink> 2376<xref linkend="References:xlfd-spec"/>. 2377In the pattern (which is encoded in <acronym>ISO</acronym> 8859-1) the 2378<quote><literal>?</literal></quote> character (octal <literal>77</literal>) 2379matches any single character; the 2380<quote><literal>*</literal></quote> character (octal <literal>52</literal>) 2381matches any series of zero or more characters; and 2382alphabetic characters match either upper- or lowercase. The 2383returned <parameter>NAMES</parameter> are encoded in 2384<acronym>ISO</acronym> 8859-1 and may contain mixed 2385character cases. Font names are not required to be in <acronym>XLFD</acronym> 2386format. 2387 </para> 2388 <para> 2389If <parameter>PATTERN</parameter> is of zero length or 2390<parameter>MAX-NAMES</parameter> is equal to zero, 2391one reply containing a zero-length list of names is returned. 2392This may be used to synchronize the client with the server. 2393 </para> 2394 <para> 2395Servers are free to add or remove fonts to the set returned by 2396<function>ListFonts</function> 2397between any two requests. This request is not 2398cumulative; repeated uses are processed in isolation and do 2399result in an iteration through the list. 2400 </para> 2401 <para> 2402To reduce the amount of buffering needed by the server, the 2403list of names may be split across several reply packets, so 2404long as the names arrive in the same order that they would 2405have appeared had they been in a single packet. The 2406<parameter>REPLIES-FOLLOWING-HINT</parameter> field in all but the last reply 2407contains a positive value that specifies the number of 2408replies that are likely, but not required, to follow. In the 2409last reply, which may contain zero or more names, this field 2410is 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> 2436This request is similar to 2437<link linkend="Requests:ListFonts"><function>ListFonts</function></link> 2438except that a separate 2439reply containing the name, header, and property data is 2440generated for each matching font name. Following these 2441replies, if any, a final reply containing a zero-length 2442<parameter>NAME</parameter> and no <parameter>INFO</parameter> is sent. 2443 </para> 2444 <para> 2445The <parameter>REPLIES-FOLLOWING-HINT</parameter> field in all but the 2446last reply contains a positive value that specifies the number of replies 2447that are likely, but not required, to follow. In the last 2448reply, this field is set to zero. 2449 </para> 2450 <para> 2451If <parameter>PATTERN</parameter> is of zero length or if 2452<parameter>MAX-NAMES</parameter> is equal to zero, only the final reply 2453containing a zero-length <parameter>NAME</parameter> and no 2454<parameter>INFO</parameter> is returned. This may be used to synchronize the 2455client 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> 2486This request looks for a server-dependent choice of the 2487font names that match the specified <parameter>PATTERN</parameter> 2488according to the rules described for 2489<link linkend="Requests:ListFonts"><function>ListFonts</function></link>. 2490If no matches are found, a 2491<link linkend="Errors:Name"><errorname>Name</errorname></link> 2492error is returned. Otherwise, the server attempts to 2493open the font associated with the chosen name. 2494 </para> 2495 <para> 2496Permission to access the font is determined by the server 2497according the licensing policy used for this font. The server 2498may use the client's current 2499<type>AccessContext</type> 2500(as set by the most 2501recent 2502<link linkend="Requests:SetAuthorization"><function>SetAuthorization</function></link> 2503request or the original connection 2504setup) to determine any client-specific sets of permissions. 2505After the font has been opened, the client is allowed to 2506specify a new 2507<type>AccessContext</type> 2508with 2509<link linkend="Requests:SetAuthorization"><function>SetAuthorization</function></link> 2510or release 2511the 2512<type>AccessContext</type> 2513using 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> 2521and 2522<link linkend="Requests:CloseFont"><function>CloseFont</function></link> 2523requests on this <link linkend="Data_Types:FONTID"><type>FONTID</type></link> are 2524performed according to permissions granted at the time of the 2525<function>OpenBitmapFont</function> 2526request. 2527 </para> 2528 <para> 2529If the server is willing and able to detect that the client 2530has already opened the font successfully (possibly under a 2531different name), the <parameter>OTHERID</parameter> field 2532may be set to one of the 2533identifiers 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: 2536if 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 2541open but has not been reused by a subsequent 2542<function>OpenBitmapFont</function> 2543request. 2544 </para> 2545 <para> 2546If <parameter>OTHERID</parameter> is set to <constant>None</constant>, 2547then <parameter>OTHERID-VALID</parameter> should be set 2548to <constant>False</constant>. 2549 </para> 2550 <para> 2551The <parameter>FORMAT-MASK</parameter> indicates which fields in 2552<parameter>FORMAT-HINT</parameter> 2553the client is likely to use in subsequent 2554<function>GetXBitmaps8</function> 2555and 2556<function>GetXBitmaps16</function> 2557requests. Servers may wish to use 2558this information to precompute certain values. 2559 </para> 2560 <para> 2561If <parameter>CACHABLE</parameter> is set to <constant>True</constant>, 2562the client may cache the font 2563(so that redundant opens of the same font may be avoided) 2564and use it with all 2565<type>AccessContext</type>s 2566during the life of the 2567client without violating the font's licensing policy. This 2568flag is typically set whenever a font is unlicensed or is 2569licensed on a per-display basis. If <parameter>CACHABLE</parameter> 2570is <constant>False</constant>, the 2571client should reopen the font for each 2572<type>AccessContext</type>. 2573 </para> 2574 <para> 2575The server is permitted to add to or remove from the set of 2576fonts returned by 2577<link linkend="Requests:ListFonts"><function>ListFonts</function></link> 2578between any two requests, though 2579mechanisms outside the protocol. Therefore, it is possible 2580for this request (which is atomic) to return a different font 2581than would result from separate a 2582<link linkend="Requests:ListFonts"><function>ListFonts</function></link> 2583followed by an 2584<function>OpenBitmapFont</function> 2585with a non-wildcarded font name. 2586 </para> 2587 <para> 2588If <parameter>FONTID</parameter> is not in the range 2589[1..2<superscript>29</superscript>-1] or if it is already 2590associated with an open font, an 2591<link linkend="Errors:IDChoice"><errorname>IDChoice</errorname></link> 2592error is returned. 2593If no font is available that matches the specified 2594<parameter>PATTERN</parameter>, a 2595<link linkend="Errors:Name"><errorname>Name</errorname></link> 2596error is returned. If the font is present but the client 2597is not permitted access, an 2598<link linkend="Errors:AccessContext"><errorname>AccessContext</errorname></link> 2599error is returned. 2600If <parameter>FORMAT-MASK</parameter> has any unspecified bits set or if any 2601of 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> 2604error 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> 2626This request returns the font header and property information 2627for the open font associated with <parameter>FONTID</parameter>. 2628 </para> 2629 <para> 2630If <parameter>FONTID</parameter> is not associated with any open fonts, a 2631<link linkend="Errors:Font"><errorname>Font</errorname></link> 2632error 2633is 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> 2658This request is equivalent to 2659<link linkend="Requests:QueryXExtents16"><function>QueryXExtents16</function></link> 2660except that it 2661uses 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> 2686This request returns a list of glyph extents from the open 2687font associated with FONTID for the series of characters 2688specified by <parameter>RANGE</parameter> and <parameter>CHARS</parameter>. 2689 </para> 2690 <para> 2691If <parameter>RANGE</parameter> is <constant>True</constant>, 2692each succeeding pair of elements in <parameter>CHARS</parameter> is 2693treated as a range of characters for which extents should be 2694returned. If <parameter>CHARS</parameter> contains an odd number of elements, 2695the font's <structfield>XFONTINFO.CHAR-RANGE.MAX-CHAR</structfield> 2696is implicitly appended to 2697the list. If <parameter>CHARS</parameter> contains no elements, the list is 2698implicitly replaced with the font's 2699<structfield>XFONTINFO.CHAR-RANGE.</structfield> If 2700any of the resulting character ranges are invalid, a 2701<link linkend="Errors:Range"><errorname>Range</errorname></link> 2702error is returned. Otherwise, the character ranges are 2703concatenated in the order given by <parameter>CHARS</parameter> to produce 2704a set of character codes for which extents are returned. 2705 </para> 2706 <para> 2707If <parameter>RANGE</parameter> is <constant>False</constant>, 2708then <parameter>CHARS</parameter> specifies the set of character 2709codes for which extents are returned. If <parameter>CHARS</parameter> is of 2710zero length, then a zero-length list of extents is returned. 2711 </para> 2712 <para> 2713The extents for each character code in the resulting set (which 2714may contain duplicates) are returned in the order in 2715which the character codes appear in the set. 2716At least one metric for each character shall be non-zero 2717unless the character is not encoded in the font, in which case 2718all-zero metrics are returned. 2719A blank, zero-width character can be encoded 2720with non-zero but equal left and right bearings. 2721 </para> 2722 <para> 2723If <parameter>FONTID</parameter> is not associated with any open fonts, a 2724<link linkend="Errors:Font"><errorname>Font</errorname></link> 2725error is 2726returned. If <parameter>RANGE</parameter> is <constant>True</constant> 2727and <parameter>CHARS</parameter> contains any invalid ranges, a 2728<link linkend="Errors:Range"><errorname>Range</errorname></link> 2729error 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> 2758This request is equivalent to 2759<link linkend="Requests:QueryXBitmaps16"><function>QueryXBitmaps16</function></link> 2760except that it 2761uses 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> 2790This request returns a list of glyph bitmaps from the open font associated 2791with <parameter>FONTID</parameter> for the series of characters 2792specified by <parameter>RANGE</parameter> and <parameter>CHARS</parameter>. 2793 </para> 2794 <para> 2795If <parameter>RANGE</parameter> is <constant>True</constant>, each succeeding 2796pair of elements in <parameter>CHARS</parameter> is 2797treated as a range of characters for which bitmaps should be 2798returned. If <parameter>CHARS</parameter> contains an odd number of elements, 2799the font's <structfield>XFONTINFO.CHAR-RANGE.MAX-CHAR</structfield> 2800is implicitly appended to 2801the list. If <parameter>CHARS</parameter> contains no elements, the list is 2802implicitly replaced with the font's 2803<structfield>XFONTINFO.CHAR-RANGE.</structfield> If 2804any of the resulting character ranges are invalid, a <link linkend="Errors:Range"><errorname>Range</errorname></link> 2805error is returned. Otherwise, the character ranges are 2806concatenated in the order given by <parameter>CHARS</parameter> to produce 2807a set of character codes for which bitmaps are returned. 2808 </para> 2809 <para> 2810If <parameter>RANGE</parameter> is <constant>False</constant>, 2811then <parameter>CHARS</parameter> specifies the set of character 2812codes for which bitmaps are returned. If <parameter>CHARS</parameter> 2813is of zero length, then a single reply containing a zero-length list of 2814offsets and bitmaps is returned. 2815 </para> 2816 <para> 2817If any of the resulting character ranges are invalid, a 2818<link linkend="Errors:Range"><errorname>Range</errorname></link> 2819error is returned. Otherwise, the resulting character ranges 2820are concatenated in the order given by <parameter>CHARS</parameter> 2821to produce a set of character codes for which bitmaps are returned. 2822 </para> 2823 <para> 2824The server is free to return the glyph bitmaps in multiple 2825replies to reduce the amount of buffering that is necessary. 2826In this situation, the set of characters obtained above is 2827partitioned into an implementation-dependent number of 2828ordered, non-overlapping subsets containing runs of one or 2829more consecutive characters. The global ordering of 2830characters must be maintained such that concatenating the 2831subsets in order that they were produced yields the original 2832set. A reply is generated for each subset, in the order that 2833it was produced. 2834 </para> 2835 <para> 2836For each character in a subset, an image of that character's 2837glyph is described by a rectangle of bits corresponding to the 2838pixels specified by FORMAT.IMAGE-RECT. Within the image, set 2839and clear bits represent inked and non-inked pixels, 2840respectively. 2841 </para> 2842 <para> 2843Each scanline of a glyph image, from top to bottom, is zero-padded 2844on the right to a multiple of the number of bits specified by 2845FORMAT.SCANLINE-PAD. The scanline is then divided from left 2846to right into a sequence of FORMAT.SCANLINE-UNIT bits. The 2847bits of each unit are then arranged such that the left-most 2848pixel is stored in the most- or least-significant bit, 2849according to FORMAT.BIT-ORDER-MSB. The bytes of each unit are 2850then arranged such that the most- or least-significant byte, 2851according to FORMAT.BYTE-ORDER-MSB, is transmitted first. 2852Finally, the units are arranged such that the left-most is 2853transmitted first and the right-most is transmitted last. 2854 </para> 2855 <para> 2856The individual images within a subset are then concatenated in 2857a server-dependent order to form the <parameter>BITMAPS</parameter> data 2858of the reply. If a glyph image is duplicated within a reply, the 2859server is free to return fewer (but at least one) copies of 2860the image. If a character is not encoded within the font, a 2861zero-length bitmap is substituted for this character. Each 2862glyph image must begin at a bit position that is a multiple of 2863the FORMAT.SCANLINE-UNIT. 2864 </para> 2865 <para> 2866The <parameter>OFFSETS</parameter> array in a reply contains one entry 2867for each character in the subset being returned, in the order that the 2868characters appear in the subset. Each entry specifies the 2869starting location in bytes and size in bytes of the 2870corresponding glyph image in the <parameter>BITMAPS</parameter> data of that 2871reply (i.e. an offset may not refer to data in another reply). 2872 </para> 2873 <para> 2874The <parameter>REPLIES-FOLLOWING-HINT</parameter> field in all but the 2875last reply contains a positive value that specifies the number of replies 2876that are likely, but not required, to follow. In the last 2877reply, which may contain data for zero or more characters, 2878this field is set to zero. 2879 </para> 2880 <para> 2881If <parameter>FONTID</parameter> is not associated with any open fonts, 2882a <link linkend="Errors:Font"><errorname>Font</errorname></link> 2883error is returned. If <parameter>RANGE</parameter> is 2884<constant>True</constant> and <parameter>CHARS</parameter> contains any 2885invalid ranges, a 2886<link linkend="Errors:Range"><errorname>Range</errorname></link> error 2887is returned. If <parameter>FORMAT</parameter> is invalid, a 2888<link linkend="Errors:Format"><errorname>Format</errorname></link> error 2889is 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> 2908This request indicates that the specified <parameter>FONTID</parameter> 2909should no longer be associated with an open font. The server is free to 2910release any client-specific storage or licenses allocated for 2911the font. The client may reuse the value of <parameter>FONTID</parameter> 2912in a subsequent 2913<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 2914request. 2915 </para> 2916 <para> 2917If <parameter>FONTID</parameter> is not associated with any open fonts, a 2918<link linkend="Errors:Font"><errorname>Font</errorname></link> 2919error 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> 2928When a connection is closed, a 2929<link linkend="Requests:CloseFont"><function>CloseFont</function></link> 2930is done on all fonts 2931that are open on the connection. In addition, the server is 2932free to release any storage or licenses allocated on behalf of 2933the 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> 2944All 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> 2965The TYPE field has a value of one. The ERROR-CODE field specifies which error 2966occurred. Core errors codes are in the range 0 through 127, extension error 2967codes are in the range 128 through 255. The SEQUENCE-NUMBER field contains the 2968least significant 16 bits of the sequence number of the request that caused the 2969error. The LENGTH field specifies the length of the error packet in 4-byte 2970units and must have a value of at least 4. The TIMESTAMP specifies the server 2971time when the error occurred. The MAJOR-OPCODE and MINOR-OPCODE (zero for core 2972requests) fields specify the type of request that generated the error. The 2973DATA-OR-UNUSED field may be used for 16 bits of error-specific information. If 2974LENGTH is greater than four, these fields are followed by (LENGTH - 4) * 4 2975bytes of extra data. 2976</para> 2977<para> 2978The 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> 2996This error is generated by any request that has an unknown 2997combination of major and minor request numbers, or by any 2998extension request that is issued before a 2999<link linkend="Requests:QueryExtension"><function>QueryExtension</function></link> 3000of 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> 3020This error is generated by the use of an invalid <link linkend="Data_Types:BITMAPFORMAT"><type>BITMAPFORMAT</type></link> 3021in 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> 3025requests. 3026The 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> 3046This 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> 3052and 3053<link linkend="Requests:CloseFont"><function>CloseFont</function></link> 3054requests. The value that caused 3055the 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> 3075This 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> 3079and 3080<link linkend="Requests:QueryXBitmaps16"><function>QueryXBitmaps16</function></link> 3081requests. The 3082value 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> 3102This 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> 3104request. The value that caused the error is 3105included 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> 3125This 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> 3127or 3128<link linkend="Requests:SetAuthorization"><function>SetAuthorization</function></link> 3129request or by an 3130<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 3131request performed without sufficient authorization. In the 3132first two cases, the <link linkend="Data_Types:ACCESSCONTEXT"><type>ACCESSCONTEXT</type></link> of the errant request is 3133returned 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> 3154This 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> 3157request or <link linkend="Data_Types:FONTID"><type>FONTID</type></link> identifier 3158in an 3159<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 3160request. The value that caused the error 3161is 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> 3180This error is generated by a font name pattern that matches 3181no fonts in an 3182<link linkend="Requests:OpenBitmapFont"><function>OpenBitmapFont</function></link> 3183request or no catalogue names in a 3184<link linkend="Requests:SetCatalogues"><function>SetCatalogues</function></link> 3185request. 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> 3206This error is generated in response to an invalid <link linkend="Data_Types:RESOLUTION"><type>RESOLUTION</type></link> 3207structure in a 3208<link linkend="Requests:SetResolution"><function>SetResolution</function></link> 3209request. The value that caused the 3210error 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> 3229This error is generated by any request for which the server 3230lacks 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> 3250This error is generated by any request that has a length field 3251greater than (MAXIMUM-REQUEST-LENGTH * 4) bytes. The value that 3252caused 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> 3271This error may be generated in response to any request that 3272the server is unable to process because it is deficient. Use 3273of this error is highly discouraged and indicates lack of 3274conformance to the protocol. 3275 </para> 3276</section> 3277<section id="Errors:Extensions"> 3278 <title>Extensions</title> 3279 <para> 3280Additional 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> 3291Events may be generated in response to requests or at the server's discretion 3292after the initial connection setup information has been exchanged. Each event 3293is 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> 3311The TYPE field contains the value 2. The EVENT-CODE field specifies the number 3312of the event and is in the range 0-127 for core events or the range 128-255 for 3313extensions. The SEQUENCE-NUMBER field specifies the least significant 16 bits 3314of the sequence number of the last request to have been processed by the 3315server. The LENGTH field specifies the number of 4-byte units in this event 3316packet and must always have a value of at least 3. The <link linkend="Data_Types:TIMESTAMP"><type>TIMESTAMP</type></link> field 3317specifies the server time when the event occurred. If LENGTH is greater than 3318three, these fields are followed by (LENGTH - 3) * 4 bytes of additional data. 3319</para> 3320<para> 3321Events 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> 3340If an event does not provide any extra arguments, the 3341<parameter>arg1</parameter>...<parameter>argN</parameter> 3342lines are omitted from the description. 3343</para> 3344<para> 3345The 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> 3352This unsolicited, nonmaskable event may be sent by the 3353server to verify that the connection has not been broken 3354(for transports that do not provide this information). 3355Clients should acknowledge receipt of this request 3356by 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> 3377This event is sent to clients that have included 3378<function><constant>CatalogueListChangeMask</constant></function> 3379in their core event mask 3380whenever the list of catalogues that are available has 3381changed. The ADDED field is <constant>True</constant> if new catalogues have 3382been added to the server, otherwise it is <constant>False</constant>. The 3383DELETED field is <constant>True</constant> if any existing catalogues have 3384been 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> 3403This event is sent to clients that have included 3404<function><constant>FontListChangeMask</constant></function> 3405in their event mask whenever the 3406list of fonts that are provided by the currently selected 3407catalogues has changed. The ADDED field is <constant>True</constant> if new 3408fonts have been added to any of the catalogues currently 3409used by the client, otherwise it is <constant>False</constant>. The DELETED 3410field is <constant>True</constant> if any existing fonts have been removed 3411from any of catalogues used by the client, otherwise it 3412is <constant>False</constant>. 3413 </para> 3414</section> 3415<section id="Events:Extensions"> 3416 <title>Extensions</title> 3417 <para> 3418Additional 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> 3430Numbers that are prefixed with <quote><literal>#x</literal></quote> 3431are in hexadecimal (base 16). All other 3432numbers are in decimal. Requests, replies, errors, events, and compound types 3433are 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> 3446where COUNT is the number of bytes in the data stream occupied by this 3447field, CONTENTS is the name of the type as given in 3448<link linkend='Data_Types'>Section 4</link> or the value if 3449this field contains a constant, and NAME is a description of this field. 3450</para> 3451<para> 3452Objects containing counted lists use a lowercase single-letter variable (whose 3453scope is limited to the request, reply, event, or error in which it is found) 3454to represent the number of objects in the list. These variables, and any 3455expressions in which they are used, should be treated as unsigned integers. 3456Multiple copies of an object are indicated by CONTENTS prefix 3457<quote>LISTof</quote>. 3458</para> 3459<para> 3460Unused bytes (whose value is undefined) will have a blank CONTENTS field and a 3461NAME field of <quote>unused</quote>. Zeroed bytes (whose value must be zero) 3462will have a blank CONTENTS field and a NAME field of <quote>zero</quote>. 3463The expression pad(e) refers to the number of bytes 3464needed to round a value <quote>e</quote> up to the closed 3465multiple 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> 34804 <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> 34921 <type>BOOL</type> subset 34931 n length of name 3494n <type>STRING8</type> name 3495p unused, p=pad(n+2) 3496 3497<link linkend="Data_Types:AUTH"><type>AUTH</type></link> 34982 n length of name 34992 d length of data 3500n <type>STRING8</type> name 3501p unused, p=pad(n) 3502d <type>STRING8</type> data 3503q unused, q=pad(d) 3504 3505 3506<link linkend="Data_Types:BITMAPFORMAT"><type>BITMAPFORMAT</type></link> 35074 <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> 35334 <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> 35461 <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> 35511 <type>BYTE</type> unsigned byte of data 3552 3553<type>CARD8</type> 35541 <type>CARD8</type> 8-bit unsigned integer 3555 3556<type>CARD16</type> 35572 <type>CARD16</type> 16-bit unsigned integer 3558 3559<type>CARD32</type> 35604 <type>CARD32</type> 32-bit unsigned integer 3561 3562<link linkend="Data_Types:CHAR2B"><type>CHAR2B</type></link> 35631 <type>CARD8</type> byte1 35641 <type>CARD8</type> byte2 3565 3566<link linkend="Data_Types:EVENTMASK"><type>EVENTMASK</type></link> 35674 <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> 35814 <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> 35921 <type>INT8</type> 8-bit signed integer 3593 3594<type>INT16</type> 35952 <type>INT16</type> 16-bit signed integer 3596 3597<type>INT32</type> 35984 <type>INT32</type> 32-bit signed integer 3599 3600<link linkend="Data_Types:OFFSET32"><type>OFFSET32</type></link> 36014 <type>CARD32</type> position (or integer value) 36024 <type>CARD32</type> length 3603 3604<link linkend="Data_Types:PROPINFO"><type>PROPINFO</type></link> 36054 n number of <type>PROPOFFSET</type> components 36064 m number of bytes of property data 360720*n <type>PROPOFFSET</type> property offsets into data block 3608m <type>LISTofBYTE</type> property data block 3609 3610<link linkend="Data_Types:PROPOFFSET"><type>PROPOFFSET</type></link> 36118 <type>OFFSET32</type> name in data block 36128 <type>OFFSET32</type> value in data block 36131 <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> 36202 <type>CHAR2B</type> minimum character code 36212 <type>CHAR2B</type> maximum character code 3622 3623<link linkend="Data_Types:RESOLUTION"><type>RESOLUTION</type></link> 36242 <type>CARD16</type> x resolution in pixels per inch 36252 <type>CARD16</type> y resolution in pixels per inch 36262 <type>CARD16</type> point size in decipoints 3627 3628STRNAME 36291 n length of name 3630n <type>STRING8</type> name 3631 3632<link linkend="Data_Types:STRING8"><type>STRING8</type></link> 3633n <type>LISTofBYTE</type> array of 8-bit character values 3634 3635<link linkend="Data_Types:TIMESTAMP"><type>TIMESTAMP</type></link> 36364 <type>CARD32</type> milliseconds since server time origin 3637 3638<link linkend="Data_Types:XCHARINFO"><type>XCHARINFO</type></link> 36392 <type>INT16</type> left bearing 36402 <type>INT16</type> right bearing 36412 <type>INT16</type> width 36422 <type>INT16</type> ascent 36432 <type>INT16</type> descent 36442 <type>CARD16</type> attributes 3645 3646<link linkend="Data_Types:XFONTINFO"><type>XFONTINFO</type></link> 36474 <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 36574 <type>RANGE</type> range of characters in font 36581 <type>CARD8</type> drawing direction 3659 0 <constant>LeftToRight</constant> 3660 1 <constant>RightToLeft</constant> 36611 unused 36622 <type>CHAR2B</type> default character 366312 <type>XCHARINFO</type> minimum bounds 366412 <type>XCHARINFO</type> maximum bounds 36652 <type>INT16</type> font ascent 36662 <type>INT16</type> font descent 3667n <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"> 36751 <type>BYTE</type> byteorder, one of the values: 3676 #x42 MostSignificant Byte first 3677 #x6c LeastSignificant Byte first 36781 <type>CARD8</type> numberof auth in auth-data 36792 2 client-major-protocol-version 36802 0 client-minor-protocol-version 36812 a/4 lengthof auth-data 3682a <type>LISTofAUTH</type> auth-data 3683▶ 36842 <type>CARD16</type> status 3685 0 <constant>Success</constant> 3686 1 <constant>Continue</constant> 3687 2 <constant>Busy</constant> 3688 3 <constant>Denied</constant> 36892 2 major version 36902 0 version 36911 <type>CARD8</type> numberof alternate-servers-hint 36921 <type>CARD8</type> authorization-index 36932 a/4 lengthof alternate-servers-hint 36942 (d+q)/4 lengthof authorization-data 3695a <type>LISTofALTERNATESERVER</type> alternate-servers-hint 3696d <type>LISTofBYTE</type> authorization-data 3697q unused, q=pad(d) 3698</literallayout> 3699 3700<para> 3701If STATUS is <constant>Busy</constant> or <constant>Denied</constant>, the protocol stops and the connection is 3702closed. If STATUS is <constant>Continue</constant>, the client is expected to respond with 3703additional data, to which the server responds with 3704a new status value and more data. This dialog continues until the status 3705is set to <constant>Success</constant>, or until the server sets STATUS to <constant>Busy</constant> or <constant>Denied</constant> 3706and closes the connection: 3707</para> 3708 3709<literallayout class="monospaced"> 3710◀ 37114 1+(d+q)/4 length 3712d <type>LISTofBYTE</type> more-authorization-data 3713q unused, q=pad(d) 3714▶ 37154 2+(d+q)/4 length 37162 <type>CARD16</type> status 3717 0 <constant>Success</constant> 3718 1 <constant>Continue</constant> 3719 2 <constant>Busy</constant> 3720 3 <constant>Denied</constant> 37212 unused 3722d <type>LISTofBYTE</type> more-authorization-data 3723q unused, q=pad(d) 3724</literallayout> 3725<para> 3726When STATUS is <constant>Success</constant>, the protocol resumes with the following 3727sent by the server: 3728</para> 3729 3730<literallayout class="monospaced"> 37314 3+(v+w)/4 length of rest of data 37322 <type>CARD16</type> maximum-request-length 37332 v length of vendor string 37344 <type>CARD32</type> release-number 3735v <type>STRING8</type> vendor-string 3736w unused, w=pad(v) 3737</literallayout> 3738<para> 3739Once the connection has been established, the client may send the 3740following requests: 3741</para> 3742 3743<literallayout class="monospaced"> 3744<link linkend="Requests:NoOp"><emphasis role="bold"><function>NoOp</function></emphasis></link> 37451 0 major-opcode 37461 unused 37472 1 length 3748 3749<link linkend="Requests:ListExtensions"><emphasis role="bold"><function>ListExtensions</function></emphasis></link> 37501 1 major-opcode 37511 unused 37522 1 length 3753▶ 37541 0 type reply 37551 <type>CARD8</type> numberof names 37562 <type>CARD16</type> sequence-number 37574 2+(n+p)/4 length 3758n LISTofSTRNAME names 3759p unused, p=pad(n) 3760 3761<link linkend="Requests:QueryExtension"><emphasis role="bold"><function>QueryExtension</function></emphasis></link> 37621 2 major-opcode 37631 n length of name 37642 1+(n+p)/4 length 3765n <type>STRING8</type> name 3766p unused, p=pad(n) 3767▶ 37681 0 type reply 37691 <type>BOOL</type> present 37702 <type>CARD16</type> sequence-number 37714 5 length 37722 <type>CARD16</type> major-version 37732 <type>CARD16</type> minor-version 37741 <type>CARD8</type> major-opcode 37751 <type>CARD8</type> first-event 37761 <type>CARD8</type> number-events 37771 <type>CARD8</type> first-error 37781 <type>CARD8</type> number-errors 37793 unused 3780 3781<link linkend="Requests:ListCatalogues"><emphasis role="bold"><function>ListCatalogues</function></emphasis></link> 37821 3 major-opcode 37831 unused 37842 3+(n+p)/4 length 37854 <type>CARD32</type> max-names 37862 n length of pattern 37872 unused 3788n <type>STRING8</type> pattern 3789p unused, p=pad(n) 3790▶+ 37911 0 type reply 37921 unused 37932 <type>CARD16</type> sequence-number 37944 4+(n+p)/4 length 37954 <type>CARD32</type> replies-following-hint 37964 <type>CARD32</type> numberof catalogue-names 3797n LISTofSTRNAME catalogue-names 3798p unused, p=pad(n) 3799 3800<link linkend="Requests:SetCatalogues"><emphasis role="bold"><function>SetCatalogues</function></emphasis></link> 38011 4 major-opcode 38021 <type>CARD8</type> numberof catalogue-names 38032 1+(n+p)/4 length 3804n LISTofSTRNAME catalogue-names 3805p unused, p=pad(n) 3806 3807<link linkend="Requests:GetCatalogues"><emphasis role="bold"><function>GetCatalogues</function></emphasis></link> 38081 5 major-opcode 38091 unused 38102 1 length 3811▶ 38121 0 type reply 38131 <type>CARD8</type> numberof catalogue-names 38142 <type>CARD16</type> sequence-number 38154 2+(n+p)/4 length 3816n LISTofSTRNAME catalogue-names 3817p unused, p=pad(n) 3818 3819<link linkend="Requests:SetEventMask"><emphasis role="bold"><function>SetEventMask</function></emphasis></link> 38201 6 major-opcode 38211 <type>CARD8</type> extension-opcode 38222 2 length 38234 <type>EVENTMASK</type> event-mask 3824 3825<link linkend="Requests:GetEventMask"><emphasis role="bold"><function>GetEventMask</function></emphasis></link> 38261 7 major-opcode 38271 <type>CARD8</type> extension-opcode 38282 1 length 3829▶ 38301 0 type reply 38311 unused 38322 <type>CARD16</type> sequence-number 38334 3 length 38344 <type>EVENTMASK</type> event-mask 3835 3836<link linkend="Requests:CreateAC"><emphasis role="bold"><function>CreateAC</function></emphasis></link> 38371 8 major-opcode 38381 <type>CARD8</type> numberof authorization-protocols 38392 2+a/4 length 38404 <type>ACCESSCONTEXT</type> ac 3841a <type>LISTofAUTH</type> authorization-protocols 3842▶ 38431 0 type reply 38441 <type>CARD8</type> authorization-index 38452 <type>CARD16</type> sequence-number 38464 3+(d+q)/4 length 38472 <type>CARD16</type> status 3848 0 <constant>Success</constant> 3849 1 <constant>Continue</constant> 3850 2 <constant>Busy</constant> 3851 3 <constant>Denied</constant> 38522 unused 3853d <type>LISTofBYTE</type> authorization-data 3854q unused, q=pad(d) 3855</literallayout> 3856 3857<para> 3858If STATUS is <constant>Continue</constant>, the client is expected to respond with additional 3859data, to which the server 3860responds with a new status value and more data. This dialog continues 3861until 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◀ 38674 1+(d+q)/4 length 3868d <type>LISTofBYTE</type> more-authorization-data 3869q unused, q=pad(d) 3870▶ 38714 2+(d+q)/4 length 38722 <type>CARD16</type> status 3873 0 <constant>Success</constant> 3874 1 <constant>Continue</constant> 3875 2 <constant>Busy</constant> 3876 3 <constant>Denied</constant> 38772 unused 3878d <type>LISTofBYTE</type> authorization-data 3879q unused, q=pad(d) 3880 3881<link linkend="Requests:FreeAC"><emphasis role="bold"><function>FreeAC</function></emphasis></link> 38821 9 major-opcode 38831 unused 38842 2 length 38854 <type>ACCESSCONTEXT</type> ac 3886 3887<link linkend="Requests:SetAuthorization"><emphasis role="bold"><function>SetAuthorization</function></emphasis></link> 38881 10 major-opcode 38891 unused 38902 2 length 38914 <type>ACCESSCONTEXT</type> ac 3892 3893<link linkend="Requests:SetResolution"><emphasis role="bold"><function>SetResolution</function></emphasis></link> 38941 11 major-opcode 38951 n number of resolutions 38962 1+(6*n+p)/4 length 38976*n <type>LISTofRESOLUTION</type> resolutions 3898p p=pad(6*n) 3899 3900<link linkend="Requests:GetResolution"><emphasis role="bold"><function>GetResolution</function></emphasis></link> 39011 12 major-opcode 39021 unused 39032 1 length 3904▶ 39051 0 type reply 39061 n number of resolutions 39072 <type>CARD16</type> sequence-number 39084 2+(6*n+p)/4 length 39096*n <type>LISTofRESOLUTION</type> resolutions 3910p p=pad(6*n) 3911 3912<link linkend="Requests:ListFonts"><emphasis role="bold"><function>ListFonts</function></emphasis></link> 39131 13 major-opcode 39141 unused 39152 3+(n+p)/4 length 39164 <type>CARD32</type> max-names 39172 n length of pattern 39182 unused 3919n <type>STRING8</type> pattern 3920p unused, p=pad(n) 3921▶+ 39221 0 type reply 39231 unused 39242 <type>CARD16</type> sequence-number 39254 4+(n+p)/4 length 39264 <type>CARD32</type> replies-following-hint 39274 <type>CARD32</type> numberof font-names 3928n LISTofSTRNAME font-names 3929p unused, p=pad(n) 3930 3931<link linkend="Requests:ListFontsWithXInfo"><emphasis role="bold"><function>ListFontsWithXInfo</function></emphasis></link> 39321 14 major-opcode 39331 unused 39342 3+(n+p)/4 length 39354 <type>CARD32</type> max-names 39362 n length of pattern 39372 unused 3938n <type>STRING8</type> pattern 3939p unused, p=pad(n) 3940▶+ (except for last in series) 39411 0 type reply 39421 n length of name 39432 <type>CARD16</type> sequence-number 39444 3+(n+p+f)/4 length 39454 <type>CARD32</type> replies-hint 3946f <type>XFONTINFO</type> fontinfo 3947n <type>STRING8</type> name 3948p unused, p=pad(n) 3949▶ (last in series) 39501 0 type reply 39511 0 last-reply indicator 39522 <type>CARD16</type> sequence-number 39534 2 reply length 3954 3955<link linkend="Requests:OpenBitmapFont"><emphasis role="bold"><function>OpenBitmapFont</function></emphasis></link> 39561 15 major-opcode 39571 unused 39582 4+(n+p)/4 length 39594 <type>FONTID</type> fontid 39604 <type>BITMAPFORMATMASK</type> format-mask 39614 <type>BITMAPFORMAT</type> format 3962n STRNAME pattern 3963p unused, p=pad(n) 3964▶ 39651 0 type reply 39661 <type>BOOL</type> otherid-valid 39672 <type>CARD16</type> sequence-number 39684 4 length 39694 <type>FONTID</type> otherid 39701 <type>BOOL</type> cachable 39713 unused 3972 3973<link linkend="Requests:QueryXInfo"><emphasis role="bold"><function>QueryXInfo</function></emphasis></link> 39741 16 major-opcode 39751 unused 39762 2 length 39774 <type>FONTID</type> fontid 3978▶ 39791 0 type reply 39801 unused 39812 <type>CARD16</type> sequence-number 39824 2+f/4 length 3983f <type>XFONTINFO</type> fontinfo 3984p unused, p=pad(f) 3985 3986<link linkend="Requests:QueryXExtents8"><emphasis role="bold"><function>QueryXExtents8</function></emphasis></link> 39871 17 major-opcode 39881 <type>BOOL</type> range 39892 3+(n+p)/4 length 39904 <type>FONTID</type> fontid 39914 n number chars entries 3992n <type>STRING8</type> chars 3993p unused, p=pad(n) 3994▶ 39951 0 type reply 39961 unused 39972 <type>CARD16</type> sequence-number 39984 3+3*n length 39994 n number of extents 400012*n <type>LISTofXCHARINFO</type> extents 4001 4002<link linkend="Requests:QueryXExtents16"><emphasis role="bold"><function>QueryXExtents16</function></emphasis></link> 40031 18 major-opcode 40041 <type>BOOL</type> range 40052 3+(2*n+p)/4 length 40064 <type>FONTID</type> fontid 40074 n number chars entries 40082*n <type>LISTofCHAR2B</type> chars 4009p unused, p=pad(2*n) 4010▶ 40111 0 type reply 40121 unused 40132 <type>CARD16</type> sequence-number 40144 3+3*n length 40154 n number of extents 401612*n <type>LISTofXCHARINFO</type> extents 4017 4018<link linkend="Requests:QueryXBitmaps8"><emphasis role="bold"><function>QueryXBitmaps8</function></emphasis></link> 40191 19 major-opcode 40201 <type>BOOL</type> range 40212 4+(n+p)/4 length 40224 <type>FONTID</type> fontid 40234 <type>BITMAPFORMAT</type> format 40244 n number of chars entries 4025n <type>STRING8</type> chars 4026p unused, p=pad(n) 4027▶+ 40281 0 type reply 40291 unused 40302 <type>CARD16</type> sequence-number 40314 5+2*n+(m+p)/4 length 40324 <type>CARD32</type> replies-following-hint 40334 n number of offsets 40344 m number of bytes of glyph images 40358*n <type>LISTofOFFSET32</type> offsets 4036m <type>LISTofBYTE</type> glyphimages 4037p unused, p=pad(m) 4038 4039<link linkend="Requests:QueryXBitmaps16"><emphasis role="bold"><function>QueryXBitmaps16</function></emphasis></link> 40401 20 major-opcode 40411 <type>BOOL</type> range 40422 4+(2*n+p)/4 length 40434 <type>FONTID</type> fontid 40444 <type>BITMAPFORMAT</type> format 40454 n number of chars entries 40462*n <type>LISTofCHAR2B</type> chars 4047p unused, p=pad(2*n) 4048▶ 40491 0 type reply 40501 unused 40512 <type>CARD16</type> sequence-number 40524 5+2*n+(m+p)/4 length 40534 <type>CARD32</type> replies-following-hint 40544 n number of offsets 40554 m number of bytes of glyph images 40568*n <type>LISTofOFFSET32</type> offsets 4057m <type>LISTofBYTE</type> glyphimages 4058p unused, p=pad(m) 4059 4060<link linkend="Requests:CloseFont"><emphasis role="bold"><function>CloseFont</function></emphasis></link> 40611 21 major-opcode 40621 unused 40632 2 length 40644 <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> 40731 1 type error 40741 0 <errorname>Request</errorname> 40752 <type>CARD16</type> sequence-number 40764 4 length 40774 <type>TIMESTAMP</type> timestamp 40781 <type>CARD8</type> major-opcode 40791 <type>CARD8</type> minor-opcode 40802 unused 4081 4082<link linkend="Errors:Format"><emphasis role="bold"><errorname>Format</errorname></emphasis></link> 40831 1 type error 40841 1 <errorname>Format</errorname> 40852 <type>CARD16</type> sequence-number 40864 5 length 40874 <type>TIMESTAMP</type> timestamp 40881 <type>CARD8</type> major-opcode 40891 <type>CARD8</type> minor-opcode 40902 unused 40914 <type>BITMAPFORMAT</type> bad-format 4092 4093<link linkend="Errors:Font"><emphasis role="bold"><errorname>Font</errorname></emphasis></link> 40941 1 type error 40951 2 <errorname>Font</errorname> 40962 <type>CARD16</type> sequence-number 40974 5 length 40984 <type>TIMESTAMP</type> timestamp 40991 <type>CARD8</type> major-opcode 41001 <type>CARD8</type> minor-opcode 41012 unused 41024 <type>FONTID</type> bad-fontid 4103 4104<link linkend="Errors:Range"><emphasis role="bold"><errorname>Range</errorname></emphasis></link> 41051 1 type error 41061 3 <errorname>Range</errorname> 41072 <type>CARD16</type> sequence-number 41084 5 length 41094 <type>TIMESTAMP</type> timestamp 41101 <type>CARD8</type> major-opcode 41111 <type>CARD8</type> minor-opcode 41122 unused 41134 <type>RANGE</type> bad-range 4114 4115<link linkend="Errors:EventMask"><emphasis role="bold"><errorname>EventMask</errorname></emphasis></link> 41161 1 type error 41171 4 <errorname>EventMask</errorname> 41182 <type>CARD16</type> sequence-number 41194 5 length 41204 <type>TIMESTAMP</type> timestamp 41211 <type>CARD8</type> major-opcode 41221 <type>CARD8</type> minor-opcode 41232 unused 41244 <type>EVENTMASK</type> event-mask 4125 4126<link linkend="Errors:AccessContext"><emphasis role="bold"><errorname>AccessContext</errorname></emphasis></link> 41271 1 type error 41281 5 <errorname>AccessContext</errorname> 41292 <type>CARD16</type> sequence-number 41304 5 length 41314 <type>TIMESTAMP</type> timestamp 41321 <type>CARD8</type> major-opcode 41331 <type>CARD8</type> minor-opcode 41342 unused 41354 <type>ACCESSCONTEXT</type> access context 4136 4137<link linkend="Errors:IDChoice"><emphasis role="bold"><errorname>IDChoice</errorname></emphasis></link> 41381 1 type error 41391 6 <errorname>IDChoice</errorname> 41402 <type>CARD16</type> sequence-number 41414 5 length 41424 <type>TIMESTAMP</type> timestamp 41431 <type>CARD8</type> major-opcode 41441 <type>CARD8</type> minor-opcode 41452 unused 41464 <type>FONTID</type> bad-fontid 4147 4148<link linkend="Errors:Name"><emphasis role="bold"><errorname>Name</errorname></emphasis></link> 41491 1 type error 41501 7 <errorname>Name</errorname> 41512 <type>CARD16</type> sequence-number 41524 4 length 41534 <type>TIMESTAMP</type> timestamp 41541 <type>CARD8</type> major-opcode 41551 <type>CARD8</type> minor-opcode 41562 unused 4157 4158<link linkend="Errors:Resolution"><emphasis role="bold"><errorname>Resolution</errorname></emphasis></link> 41591 1 type error 41601 8 <errorname>Resolution</errorname> 41612 <type>CARD16</type> sequence-number 41624 5 length 41634 <type>TIMESTAMP</type> timestamp 41641 <type>CARD8</type> major-opcode 41651 <type>CARD8</type> minor-opcode 41666 <type>RESOLUTION</type> resolution 4167 4168<link linkend="Errors:Alloc"><emphasis role="bold"><errorname>Alloc</errorname></emphasis></link> 41691 1 type error 41701 9 <errorname>Alloc</errorname> 41712 <type>CARD16</type> sequence-number 41724 4 length 41734 <type>TIMESTAMP</type> timestamp 41741 <type>CARD8</type> major-opcode 41751 <type>CARD8</type> minor-opcode 41762 unused 4177 4178<link linkend="Errors:Length"><emphasis role="bold"><errorname>Length</errorname></emphasis></link> 41791 1 type error 41801 10 <errorname>Length</errorname> 41812 <type>CARD16</type> sequence-number 41824 5 length 41834 <type>TIMESTAMP</type> timestamp 41841 <type>CARD8</type> major-opcode 41851 <type>CARD8</type> minor-opcode 41862 unused 41874 <type>CARD32</type> bad-length 4188 4189<link linkend="Errors:Implementation"><emphasis role="bold"><errorname>Implementation</errorname></emphasis></link> 41901 1 type error 41911 11 <errorname>Implementation</errorname> 41922 <type>CARD16</type> sequence-number 41934 4 length 41944 <type>TIMESTAMP</type> timestamp 41951 <type>CARD8</type> major-opcode 41961 <type>CARD8</type> minor-opcode 41972 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> 42061 2 type event 42071 0 event KeepAlive 42082 <type>CARD16</type> sequence-number 42094 3 length 42104 <type>TIMESTAMP</type> timestamp 4211 4212<link linkend="Events:CatalogueListNotify"><emphasis role="bold"><function>CatalogueListNotify</function></emphasis></link> 42131 2 type event 42141 1 event CatalogueListNotify 42152 <type>CARD16</type> sequence-number 42164 4 length 42174 <type>TIMESTAMP</type> timestamp 42181 <type>BOOL</type> added 42191 <type>BOOL</type> deleted 42202 unused 4221 4222<link linkend="Events:FontListNotify"><emphasis role="bold"><function>FontListNotify</function></emphasis></link> 42231 2 type event 42241 2 event FontListNotify 42252 <type>CARD16</type> sequence-number 42264 4 length 42274 <type>TIMESTAMP</type> timestamp 42281 <type>BOOL</type> added 42291 <type>BOOL</type> deleted 42302 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> 4242This document represents the culmination of several years of debate and 4243experiments done under the auspices of the 4244<orgname class="consortium">MIT X Consortium</orgname> font working group. 4245Although this was a group effort, the author remains responsible for any errors 4246or 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>, 4249and 4250<personname><firstname>Bob</firstname><surname>Scheifler</surname></personname>. 4251Special thanks goes to 4252<personname><firstname>Ned</firstname><surname>Batchelder</surname></personname>, 4253<personname><firstname>Jim</firstname><surname>Flowers</surname></personname>, 4254and 4255<personname><firstname>Axel</firstname><surname>Deininger</surname></personname> 4256for their invigorating comments 4257which never failed to make this a better document. 4258<personname><firstname>Stephen</firstname><surname>Gildea</surname></personname> 4259edited version 2 of this document. Finally, 4260<personname><firstname>David</firstname><surname>Lemke</surname></personname> 4261deserves great credit for designing and coding the sample implementation. 4262</para> 4263</chapter> 4264 4265<bibliography id='References'> 4266<title>References</title> 4267<para> 4268All of the following documents are X Consortium standards available from 4269the 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> 4295The authorization data passed by the client in the initial connection 4296setup information may be used by the font server to implement restrictions 4297on which fonts may be accessed. Furthermore, the font server is free to 4298refuse new connections at any time. 4299</para> 4300<para> 4301Configuration or management of the license restrictions is outside the scope of 4302the font service protocol and is done in a server-dependent manner. Possible 4303policies 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> 4311anyone may access any fonts. The server neither refuses any connections 4312nor generates <link linkend="Errors:AccessContext"><errorname>AccessContext</errorname></link> errors on any 4313fonts. For environments without specially-licensed fonts, this is 4314sufficient. 4315 </para> 4316 </listitem> 4317 </varlistentry> 4318 <varlistentry> 4319 <term>Per-machine</term> 4320 <listitem> 4321 <para> 4322only those clients connecting from a known set of 4323machines are permitted access. The server could get the address 4324of 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> 4332only a known set of users may access the fonts. The 4333server can use the authorization data (such as a Kerberos ticket 4334or a Secure RPC credential) to verify the identity of the user 4335and 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> 4343only a certain number of clients may use a given font at any one time. 4344Additional clients would receive <link linkend="Errors:AccessContext"><errorname>AccessContext</errorname></link> 4345errors if they attempt to open the font. This is only effective if 4346the initial clients keep the font open for the entire time that it 4347is being used (even if all of the data has been transmitted and is 4348being cached). 4349 </para> 4350 </listitem> 4351 </varlistentry> 4352 <varlistentry> 4353 <term>Postage Meter</term> 4354 <listitem> 4355 <para> 4356a particular font may only be accessed a limited 4357number of times before its license must be renewed. Each time 4358the font is opened, the server decrements a counter. When the 4359counter reaches zero, all further attempts to open the font 4360return an <link linkend="Errors:AccessContext"><errorname>AccessContext</errorname></link> error. 4361 </para> 4362 </listitem> 4363 </varlistentry> 4364</variablelist> 4365</para> 4366 4367<para> 4368It should be noted that chaining of font servers (obtaining font data from 4369other 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> 4376Font server implementations will probably wish to use techniques such as the 4377following to avoid limits on the number of simultaneous connections: 4378</para> 4379<itemizedlist> 4380 <listitem> 4381 <para> 4382The initial connection information returned by the font 4383server contains the names of other font servers that 4384may be used as substitutes. A font server may refuse to 4385accept a connection, indicating that the client should 4386try one of the alternatives instead. 4387 </para> 4388 </listitem> 4389 <listitem> 4390 <para> 4391On operating systems that support processing forking, font 4392servers might choose to fork so that the child can continue 4393processing the existing connections and the parent can accept 4394new connections. Such implementations are encouraged to use 4395shared memory so that in-memory font databases can be shared. 4396 </para> 4397 </listitem> 4398 <listitem> 4399 <para> 4400On operating systems that support passing stream file descriptors 4401between processes, cooperating font servers could collect 4402connections in a single process when there are few connections 4403and spread them among several processes as the load increases. 4404 </para> 4405 </listitem> 4406 <listitem> 4407 <para> 4408If a font client is unable to connect to a server (as opposed 4409to having the connection terminated), it should retry for an 4410implementation-dependent length of time (see Xlib's 4411handling of ECONNREFUSED in XConnDis.c). 4412 </para> 4413 </listitem> 4414</itemizedlist> 4415</appendix> 4416<index id="index" /> 4417</book> 4418