home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 45 / cda45.iso / Linux / XFree86-4.0 / doc / xc-misc.TXT < prev    next >
Encoding:
Text File  |  2000-03-09  |  5.7 KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.              XC-MISC Extension
  17.  
  18.  
  19.  
  20.             Version 1.1
  21.            X Consortium Standard
  22.          X Version 11, Release 6.4
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.                Bob Scheifler
  30.               David P. Wiggins
  31.              X Consortium, Inc.
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41. Copyright (C) 1994 X Consortium
  42.  
  43. Permission is hereby granted, free of charge, to any person
  44. obtaining a copy of this software and associated documenta-
  45. tion files (the ``Software''), to deal in the Software with-
  46. out restriction, including without limitation the rights to
  47. use, copy, modify, merge, publish, distribute, sublicense,
  48. and/or sell copies of the Software, and to permit persons to
  49. whom the Software is furnished to do so, subject to the fol-
  50. lowing conditions:
  51.  
  52. The above copyright notice and this permission notice shall
  53. be included in all copies or substantial portions of the
  54. Software.
  55.  
  56. THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
  57. KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  58. WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
  59. POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
  60. TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  74. FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
  75. OR OTHER DEALINGS IN THE SOFTWARE.
  76.  
  77. Except as contained in this notice, the name of the X Con-
  78. sortium shall not be used in advertising or otherwise to
  79. promote the sale, use or other dealings in this Software
  80. without prior written authorization from the X Consortium.
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. 1.  Overview
  140.  
  141. When an X client connects to an X server, it receives a
  142. fixed range of resource IDs to use to identify the client's
  143. resources inside the X server.    Xlib hands these out sequen-
  144. tially as needed.  When it overruns the end of the range, an
  145. IDChoice protocol error results.  Long running clients, or
  146. clients that use resource IDs at a rapid rate, may encounter
  147. this circumstance.  When it happens, there are usually many
  148. resource IDs available, but Xlib doesn't know about them.
  149.  
  150. One approach to solving this problem would be to have Xlib
  151. notice when a resource is freed and recycle its ID for
  152. future use.  This strategy runs into difficulties because
  153. sometimes freeing one resource causes others to be freed
  154. (for example, when a window is destroyed, so are its chil-
  155. dren).    To do a complete job, Xlib would have to maintain a
  156. large amount of state that currently resides only in the
  157. server (the entire window tree in the above example).  Even
  158. if a less comprehensive strategy was adopted, such as recy-
  159. cling only those IDs that Xlib can identify without main-
  160. taining additional state, the additional bookkeeping at
  161. resource creation and destruction time would likely intro-
  162. duce unacceptable overhead.
  163.  
  164. To avoid the problems listed above, the server's complete
  165. knowledge of all resource IDs in use by a client is lever-
  166. aged.  This extension provides two ways for Xlib to query
  167. the server for available resource IDs.    Xlib can use these
  168. extension requests behind the scenes when it has exhausted
  169. its current pool of resource IDs.
  170.  
  171. 2.  Requests
  172.  
  173. XCMiscGetVersion
  174.  
  175.      client_major_version: CARD16
  176.      client_minor_version: CARD16
  177.  
  178.    =>
  179.  
  180.      server_major_version: CARD16
  181.      server_minor_version: CARD16
  182.  
  183. If supplied, the client_major_version and client_minor_ver-
  184. sion indicate what version of the protocol the client wants
  185. the server to implement.  The server version numbers
  186. returned indicate the protocol this extension actually sup-
  187. ports.    This might not equal the version sent by the client.
  188. An implementation can (but need not) support more than one
  189. version simultaneously.  The server_major_version and the
  190. server_minor_version are a mechanism to support future revi-
  191. sions of the XC-MISC protocol which may be necessary.  In
  192. general, the major version would increment for incompatible
  193.  
  194.  
  195.  
  196.                   1
  197.  
  198.  
  199.  
  200.  
  201.  
  202.               XC-MISC Extension
  203.  
  204.  
  205. changes, and the minor version would increment for small,
  206. upward-compatible changes.  Servers that support the proto-
  207. col defined in this document will return a server_major_ver-
  208. sion of one (1), and a server_minor_version of one (1).
  209.  
  210. XCMiscGetXIDRange
  211.  
  212.    =>
  213.  
  214.      start_id: XID
  215.      count: CARD32
  216.  
  217. This request returns a range of available resource IDs for
  218. the client issuing the request.  start_id is the first ID in
  219. the range.  count is the number of IDs in the range.  The
  220. returned range may or may not be the largest possible range.
  221.  
  222. XCMiscGetXIDList
  223.  
  224.      count: CARD32
  225.  
  226.    =>
  227.  
  228.      ids: LISTofXID
  229.  
  230. This request returns the a list of individual resource IDs
  231. in ids.  count is the number of resource IDs requested.  The
  232. number returned may be smaller than the number requested.
  233.  
  234. 3.  Events and Errors
  235.  
  236. No new events or errors are defined by this extension.
  237.  
  238. 4.  Encoding
  239.  
  240. Please refer to the X11 Protocol Encoding document as this
  241. document uses conventions established there.
  242.  
  243. The name of this extension is ``XC-MISC''.
  244.  
  245.  
  246. XCMiscGetVersion
  247.   1  CARD8         opcode
  248.   1  0             XC-MISC opcode
  249.   2  2             request length
  250.   2  CARD16         client_major_version
  251.   2  CARD16         client_minor_version
  252.  
  253.  
  254.  =>
  255.   1  1             Reply
  256.   1             unused
  257.   2  CARD16         sequence number
  258.   4  0             length
  259.  
  260.  
  261.  
  262.                   2
  263.  
  264.  
  265.  
  266.  
  267.  
  268.               XC-MISC Extension
  269.  
  270.  
  271.   2  CARD16         server_major_version
  272.   2  CARD16         server_minor_version
  273.   20             unused
  274.  
  275.  
  276.  
  277. XCMiscGetXIDRange
  278.   1  CARD8         opcode
  279.   1  1             XC-MISC opcode
  280.   2  1             request length
  281.  
  282.  
  283.  =>
  284.   1  1             Reply
  285.   1             unused
  286.   2  CARD16         sequence number
  287.   4  0             length
  288.   4  XID         start_id
  289.   4  CARD32         count
  290.   16             unused
  291.  
  292.  
  293.  
  294. XCMiscGetXIDList
  295.   1  CARD8         opcode
  296.   1  2             XC-MISC opcode
  297.   2  2             request length
  298.   4  CARD32         count
  299.  
  300.  
  301.  =>
  302.   1  1             Reply
  303.   1             unused
  304.   2  CARD16         sequence number
  305.   4  CARD32         length
  306.   4  CARD32         number of XIDs in ids
  307.   20             unused
  308.   4n LISTofXID         ids
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                   3
  329.  
  330.  
  331.