xc-misc.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<!-- lifted from troff+ms+XMan by doclifter --> 9<book id="xc-misc"> 10 11<bookinfo> 12 <title>XC-MISC Extension</title> 13 <subtitle>X Consortium Standard</subtitle> 14 <authorgroup> 15 <author> 16 <firstname>Bob</firstname><surname>Scheifler</surname> 17 <affiliation><orgname>X Consortium</orgname></affiliation> 18 </author> 19 <author> 20 <firstname>David</firstname><othername>P.</othername><surname>Wiggins</surname> 21 <affiliation><orgname>X Consortium</orgname></affiliation> 22 </author> 23 </authorgroup> 24 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 25 <releaseinfo>Version 1.1</releaseinfo> 26 <copyright><year>1994</year><holder>X Consortium</holder></copyright> 27 28<legalnotice> 29 30<para>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</para> 31 32<para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para> 33 34<para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para> 35 36<para>Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.</para> 37 38<para>X Window System is a trademark of The Open Group.</para> 39</legalnotice> 40 41</bookinfo> 42 43<chapter id='Overview'> 44<title>Overview</title> 45 46<para>When an X client connects to an X server, it receives a fixed range of 47resource IDs to use to identify the client's resources inside the X 48server. Xlib hands these out sequentially as needed. When it 49overruns the end of the range, an IDChoice protocol error results. 50Long running clients, or clients that use resource IDs at a rapid 51rate, may encounter this circumstance. When it happens, there are 52usually many resource IDs available, but Xlib doesn't know about them.</para> 53 54<para>One approach to solving this problem would be to have Xlib notice when 55a resource is freed and recycle its ID for future use. This strategy 56runs into difficulties because sometimes freeing one resource causes 57others to be freed (for example, when a window is destroyed, so are 58its children). To do a complete job, Xlib would have to maintain a 59large amount of state that currently resides only in the server (the 60entire window tree in the above example). Even if a less 61comprehensive strategy was adopted, such as recycling only those IDs 62that Xlib can identify without maintaining additional state, the 63additional bookkeeping at resource creation and destruction time 64would likely introduce unacceptable overhead.</para> 65 66<para>To avoid the problems listed above, the server's complete knowledge of 67all resource IDs in use by a client is leveraged. This extension 68provides two ways for Xlib to query the server for available resource 69IDs. Xlib can use these extension requests behind the scenes when it has 70exhausted its current pool of resource IDs.</para> 71</chapter> 72 73<chapter id='Requests'> 74<title>Requests</title> 75 76<para> 77<function>XCMiscGetVersion</function></para> 78 79<itemizedlist> 80 <listitem><para><parameter>client_major_version</parameter>: CARD16</para></listitem> 81 <listitem><para><parameter>client_minor_version</parameter>: CARD16</para></listitem> 82</itemizedlist> 83<para> =></para> 84<itemizedlist> 85 <listitem><para><parameter>client_major_version</parameter>: CARD16</para></listitem> 86 <listitem><para><parameter>client_minor_version</parameter>: CARD16</para></listitem> 87</itemizedlist> 88 89<para>If supplied, the <parameter>client_major_version</parameter> and 90<parameter>client_minor_version</parameter> indicate what version of 91the protocol the client wants the server to implement. The server version 92numbers returned indicate the protocol this extension actually supports. This 93might not equal the version sent by the client. An implementation can 94(but need not) support more than one version simultaneously. The 95<parameter>server_major_version</parameter> and the <parameter>server_minor_version</parameter> are a 96mechanism to support future revisions of the XC-MISC protocol 97which may be necessary. In general, the major version would increment 98for incompatible changes, and the minor version would increment for 99small, upward-compatible changes. Servers that support the protocol 100defined in this document will return a 101<parameter>server_major_version</parameter> of one (1), and a 102<parameter>server_minor_version</parameter> of one (1).</para> 103 104<para><function>XCMiscGetXIDRange</function></para> 105 106<para> =></para> 107<itemizedlist> 108 <listitem><para><parameter>start_id</parameter>: XID</para></listitem> 109 <listitem><para><parameter>count</parameter>: CARD32</para></listitem> 110</itemizedlist> 111 112<para>This request returns a range of available resource IDs for the client 113issuing the request. <parameter>start_id</parameter> is the first 114ID in the range. <parameter>count</parameter> is the number of IDs 115in the range. The returned range may or may not be the largest possible 116range.</para> 117 118<para><function>XCMiscGetXIDList</function></para> 119 120<itemizedlist> 121 <listitem><para><parameter>count</parameter>: CARD32</para></listitem> 122</itemizedlist> 123<para> =></para> 124<itemizedlist> 125 <listitem><para><parameter>ids</parameter>: LISTofXID</para></listitem> 126</itemizedlist> 127 128<para>This request returns the a list of individual resource IDs in 129<parameter>ids</parameter>. 130<parameter>count</parameter> is the number of resource IDs requested. 131The number returned may be smaller than the number requested.</para> 132</chapter> 133 134<chapter id='Events_and_Errors'> 135<title>Events and Errors</title> 136 137<para>No new events or errors are defined by this extension.</para> 138</chapter> 139 140<chapter id='Encoding'> 141<title>Encoding</title> 142 143<para>Please refer to the X11 Protocol Encoding document as this document uses 144conventions established there.</para> 145 146<para>The name of this extension is “XC-MISC”.</para> 147 148<synopsis> 149<function>XCMiscGetVersion</function> 150 1 CARD8 opcode 151 1 0 XC-MISC opcode 152 2 2 request length 153 2 CARD16 client_major_version 154 2 CARD16 client_minor_version 155 156 => 157 1 1 Reply 158 1 unused 159 2 CARD16 sequence number 160 4 0 length 161 2 CARD16 server_major_version 162 2 CARD16 server_minor_version 163 20 unused 164</synopsis> 165 166<synopsis> 167<function>XCMiscGetXIDRange</function> 168 1 CARD8 opcode 169 1 1 XC-MISC opcode 170 2 1 request length 171 172 => 173 1 1 Reply 174 1 unused 175 2 CARD16 sequence number 176 4 0 length 177 4 XID start_id 178 4 CARD32 count 179 16 unused 180</synopsis> 181 182 183<synopsis> 184<function>XCMiscGetXIDList</function> 185 1 CARD8 opcode 186 1 2 XC-MISC opcode 187 2 2 request length 188 4 CARD32 count 189 190 => 191 1 1 Reply 192 1 unused 193 2 CARD16 sequence number 194 4 CARD32 length 195 4 CARD32 number of XIDs in ids 196 20 unused 197 4n LISTofXID ids 198</synopsis> 199</chapter> 200</book> 201 202