resproto.txt

   1                            DRAFT FOR REVIEW
   2                        The X Resource Extension
   3                              Version 1.2
   4                              Rami Ylimäki
   5                         rami.ylimaki@vincit.fi
   6
   7                              ❧❧❧❧❧❧❧❧❧❧❧
   8
   9 1. Introduction
  10
  11 The protocol description of X Resource Extension version 1.1 has been
  12 either lost or has never been written. This specification documents
  13 version 1.0 based on reverse engineered library and server
  14 code. Version 1.1 has been accidentally released from the version
  15 control and while it doesn't have differences to version 1.0, this
  16 version is labeled 1.2 in order to remove the risk of confusion. In
  17 addition to the 1.0 description, this document introduces a new 1.2
  18 version of the extension.
  19
  20 Version 1.2 is a minor release and therefore the changes are
  21 compatible with the previous version. Main enhancements over version
  22 1.0 are:
  23
  24 - Client identification is now possible. For example, servers
  25   supporting version 1.2 may report PID of local clients.
  26
  27 - Size of any resource can be queried from the server. Servers may not
  28   necessarily support size calculation for every resource. However,
  29   clients have now at least the chance to let the server do resource
  30   size estimation for them.
  31
  32                              ❧❧❧❧❧❧❧❧❧❧❧
  33
  34 2. Notations used in this document
  35
  36 Notation for data types and requests follows the guidelines set in
  37 sections 2-4 of X Window System Protocol standard.
  38
  39                              ❧❧❧❧❧❧❧❧❧❧❧
  40
  41 3. Interoperability between version 1.1 and 1.2
  42
  43 Version 1.2 only introduces two new requests. However, these requests
  44 could be seen as generalized versions of existing requests. Even
  45 though we aren't deprecating any old requests, libraries could
  46 implement some old requests using the new ones.
  47
  48 The new XResQueryClientIds request could be used instead of
  49 XResQueryClients.
  50
  51 The new XResQueryResourceBytes request could be used instead of
  52 XResQueryClientPixmapBytes.
  53
  54 Using the old requests is still acceptable because we don't want to
  55 change the semantics of existing requests between version 1.1 and 1.2.
  56
  57                              ❧❧❧❧❧❧❧❧❧❧❧
  58
  59 4. Data types
  60
  61 4.1 Types in version 1.0
  62
  63 CLIENTXIDRANGE [ resource_base: CARD32
  64                  resource_mask: CARD32 ]
  65
  66 This type is used for reply of XResQueryClients in version 1.1. It
  67 represents the range of resource allocated for a client and can be
  68 also used for client identification.
  69
  70 resource_base
  71     First resource ID reserved for a client. Used also to identify the
  72     clients themselves.
  73 resource_mask
  74     Mask that can be used to identify a client from some resource
  75     ID. Just zero the bits indicated by this mask from any resource ID
  76     to identify the client that owns the resource.
  77
  78 CLIENTXID [ client: XID ]
  79
  80 This type identifies a single client by a resource owned by that
  81 client or by the first resource ID allocated for the client
  82 (resource_base of CLIENTXIDRANGE). Whenever a resource ID is used, it
  83 is masked by resource_mask of CLIENTXIDRANGE to find out the client
  84 that owns the resource.
  85
  86 CLIENTRESOURCETYPECOUNT [ resource_type: ATOM
  87                           count:         CARD32 ]
  88
  89 This type is used for reply of XResQueryClientResources in version
  90 1.1. It represents the number of certain type of resources that are
  91 owned by some client.
  92
  93 resource_type
  94     Atom specifying the type of a resource.
  95 count
  96     Number of resources of the given type owned by a client.
  97
  98 4.2 Types in version 1.2
  99
 100 4.2.1 Types used by XResQueryClientIds
 101
 102 CLIENTIDMASK { ClientXid = 0x1, LocalClientPid = 0x2 }
 103
 104 A bitmask specifying a client identification method. Currently only
 105 the PID of local clients is supported in the form of
 106 LocalClientPid. ClientXid is provided for backward compatibility with
 107 version 1.0 so that the new 1.2 requests (XResQueryClientIds) can be
 108 used in place of the older ones (XResQueryClients).
 109
 110 CLIENTIDSPEC [ client:  CLIENTXID or None
 111                mask:    SETofCLIENTIDMASK or None ]
 112
 113 A data structure for selecting client IDs.
 114
 115 client
 116     ID of a resource allocated for some client. Only the part
 117     identifying a client is actually used. The resource_base of
 118     CLIENTXIDRANGE can be used if the client doesn't own any
 119     resources. However, any resource ID is accepted because that makes
 120     identifying the owners of existing resources easy. The null
 121     resource None can be used to select all clients.
 122 mask
 123     Collection of identification methods that should be applied on the
 124     client. The special value None can be used to apply all supported
 125     identification methods.
 126
 127 CLIENTIDVALUE [ spec:   CLIENTIDSPEC
 128                 length: CARD32
 129                 value:  LISTofCARD32 ]
 130
 131 A data structure specifying a single client ID.
 132
 133 spec
 134     A unique identifier for a specific ID of some client. Wildcards
 135     such as None and bitmask unions aren't allowed. The data structure
 136     must always identify a single client and single ID type. However,
 137     the client doesn't have to be specified as the resource_base of
 138     CLIENTXIDRANGE and can be any resource owned by the client.
 139 length
 140     Specifies the length of an ID in units of CARD32. The length
 141     depends on the ID type. In version 1.2 the lengths are 0 for
 142     ClientXid and 4 for LocalClientPid. The length of ClientXid is 0
 143     because that is already stored in the spec field.
 144 value
 145     Actual ID data. In version 1.2 this is missing for ClientXid and
 146     consists of a single CARD32 for LocalClientPid.
 147
 148 4.2.2 Types used by XResQueryResourceBytes
 149
 150 To better understand how resources are related to each other, it's
 151 useful to introduce the concepts of main resource and cross
 152 reference. By main resource we just mean a normal resource that has a
 153 valid XID. By cross reference we mean a resource that is used by some
 154 other resource.
 155
 156 The same resource may have both of these roles depending on the
 157 context. For example, there could be an ordinary pixmap resource. When
 158 we talk about this resource in isolation the term main resource is
 159 used. We call the exact same resource a cross reference when we are
 160 concentrating on some higher level resource, such as window or
 161 graphics context, that is using the lower level resource. Cross
 162 references may also be internal server resources that don't have a
 163 valid XID.
 164
 165 RESOURCEIDSPEC [ resource: XID or None
 166                  type:     ATOM or None/AnyPropertyType ]
 167
 168 A data structure for selecting or identifying resources. The
 169 interpretation of fields changes depending on the context. The
 170 differences in interpretation are described below.
 171
 172 resource
 173     An XID of a resource. The null resource None can be used to select
 174     all resources matching some type if the data structure is used in
 175     XResQueryResourceBytes request. The null resource None can be used
 176     to mark private server resources if the data structure is used in
 177     a cross reference of XResQueryResourceBytes reply.
 178 type
 179     An atom identifying the resource type. The null atom
 180     None/AnyPropertyType can be used to select all resource types
 181     matching some resource ID if the data structure is used in
 182     XResQueryResourceBytes request.
 183
 184 RESOURCESIZESPEC [ spec:      RESOURCEIDSPEC
 185                    bytes:     CARD32
 186                    ref_count: CARD32
 187                    use_count: CARD32 ]
 188
 189 A data structure specifying the size of a single resource.
 190
 191 spec
 192     Uniquely identifies a single resource. Wildcards such as None and
 193     AnyPropertyType aren't allowed for main resources. In cross
 194     references, None is used to mark internal server resources.
 195 bytes
 196     Number of bytes allocated for the resource. The size of a resource
 197     is never divided by a reference count. This is the number of bytes
 198     released in server when there are no more references left to the
 199     resource.
 200 ref_count
 201     Number of total users of the resource. Typically the reference
 202     count is 1 but for pixmaps and other resources used from different
 203     contexts the count may be larger.
 204 use_count
 205     Number of times the resource is used by some other resource. For
 206     main resources this is typically 1, because a resource doesn't
 207     usually use itself recursively. For cross references this is the
 208     number of times the resource is used and is also 1 usually.
 209
 210 RESOURCESIZEVALUE [ size:                 RESOURCESIZESPEC
 211                     num_cross_references: CARD32
 212                     cross_references:     LISTofRESOURCESIZESPEC ]
 213
 214 A data structure specifying sizes of cross references to other
 215 resources in addition to the main resource size.
 216
 217 size
 218     Size of a main resource.
 219 num_cross_references
 220     Number of cross references to other resources from the main
 221     resource. Currently resources can only have pixmaps as cross
 222     references but this can be extended to other types in the
 223     future. For simple resources this field is therefore 0 and the
 224     cross_references list is missing.
 225 cross_references:
 226     Size specifications for cross references. Note that cross
 227     references may contain resources that don't have a valid XID. For
 228     example, a DRI2 drawable might have a cross reference to a private
 229     pixmap that is used internally in the server only. These private
 230     cross references are contained in this list also. This makes it
 231     possible to emulate XResGetClientPixmapBytes with
 232     XResGetResourceBytes.
 233
 234                              ❧❧❧❧❧❧❧❧❧❧❧
 235
 236 5. Requests
 237
 238 5.1 Requests in version 1.0
 239
 240 ┌───
 241     XResQueryVersion
 242     client_major: CARD8
 243     client_minor: CARD8
 244     ▶
 245     server_major: CARD16
 246     server_minor: CARD16
 247 └───
 248
 249 The client sends the highest supported version to the server and the
 250 server sends the highest version it supports, but no higher than the
 251 requested version. Major version changes can introduce
 252 incompatibilities in existing functionality, minor version changes
 253 introduce only backward compatible changes. It is the client's
 254 responsibility to ensure that the server supports a version which is
 255 compatible with its expectations.
 256
 257 client_major
 258     Major X Resource Extension version supported by client.
 259 client_minor
 260     Minor X Resource Extension version supported by client.
 261 server_major
 262     Highest version supported by server that is compatible with
 263     client.
 264 server_minor
 265     Highest version supported by server that is compatible with
 266     client.
 267
 268 ┌───
 269     XResQueryClients
 270     ▶
 271     num_clients: CARD32
 272     clients:     LISTofCLIENTXIDRANGE
 273 └───
 274
 275 The request asks X server to return the list of all currently
 276 connected clients.
 277
 278 num_clients
 279     Number of currently connected clients.
 280 clients
 281     List of XID ranges allocated for the connected clients.
 282
 283 ┌───
 284     XResQueryClientResources
 285     client:    CLIENTXID
 286     ▶
 287     num_types: CARD32
 288     types:     LISTofCLIENTRESOURCETYPECOUNT
 289
 290     Errors:    Value
 291 └───
 292
 293 This request can be used to ask the number of resources owned by a
 294 client. The server will return the counts of each type of resource.
 295
 296 client
 297     An XID in the resource range of a client. This identifies the
 298     client and not some specific resource.
 299 num_types
 300     Number of different resource types owned by the client.
 301 types
 302     A list of counts for each resource type.
 303
 304 A value error is generated if invalid resource or client XID is given
 305 in the request.
 306
 307 ┌───
 308     XResQueryClientPixmapBytes
 309     client:         CLIENTXID
 310     ▶
 311     bytes:          CARD32
 312     bytes_overflow: CARD32
 313
 314     Errors:         Value
 315 └───
 316
 317 This request is used to get the pixmap usage of some client. The
 318 returned number is a sum of memory usage of each pixmap that can be
 319 attributed to the given client. Ideally the server goes through all
 320 pixmaps and divides each pixmap size by the pixmap reference count to
 321 get a pixmap reference size. The reference size is then added to the
 322 returned sum if the client happens to be referencing that pixmap. In
 323 practice some pixmap references may be missed, because it would be too
 324 difficult to keep track of all pixmap references. However, the server
 325 will check the most important client resources that are using pixmaps
 326 and tries to estimate the pixmap usage as well as is possible. In
 327 other words, the server need only make a best-effort attempt to
 328 calculate resource source, so actual resource size may differ from
 329 that reported in practice.
 330
 331 client
 332     Identifies a client by an ID in its resource ID range.
 333 bytes:
 334     Number of bytes attributed to pixmap references from the client
 335     resources.
 336 bytes_overflow:
 337     Higher order word for the bytes field in case the sum of pixmap
 338     reference sizes doesn't fit in CARD32.
 339
 340 A value error is generated if invalid resource or client XID is given
 341 in the request.
 342
 343 5.2 Requests in version 1.2
 344
 345 ┌───
 346     XResQueryClientIds
 347     num_specs:    CARD32
 348     client_specs: LISTofCLIENTIDSPEC
 349     ▶
 350     num_ids:      CARD32
 351     client_ids:   LISTofCLIENTIDVALUE
 352
 353     Errors:       Value
 354 └───
 355
 356 XResQueryClientIds can be used to identify a given set of clients with
 357 some identification method. The request sends a list of specifiers
 358 that select clients and identification methods to server. The server
 359 then tries to identify the chosen clients using the identification
 360 methods specified for each client. The server returns IDs for those
 361 clients that were successfully identified. It's not an error condition
 362 if some identification method couldn't be applied to a client. If the
 363 server is unable to identify some clients, they simply aren't included
 364 in the returned list.
 365
 366 The request supports wildcards in the client specifications so that in
 367 the most general case all IDs of all clients can be queried with a
 368 single CLIENTIDSPEC.
 369
 370 The CLIENTIDSPEC of request and CLIENTIDSPEC of CLIENTIDVALUE in reply
 371 usually match each other. For example, if a request selected a client
 372 by a resource ID owned by the client, then the client is identified by
 373 the same resource ID in the reply. This has been done so that it would
 374 be easy to identify an owner of some resource.
 375
 376 However, the CLIENTIDSPEC of returned CLIENTIDVALUE never contains any
 377 wildcards. If the request used a wildcard to specify all clients in a
 378 single CLIENTIDSPEC, then the reply has expanded the wildcard and
 379 returns separate CLIENTIDVALUE records for each client. In this case
 380 wildcarded clients are identified by resource_base of CLIENTXIDRANGE.
 381
 382 The LocalClientPid type of IDs are included in the reply list only if
 383 the client executing the request asked for it and was also a local
 384 client itself. It doesn't make sense for remote clients to ask PIDs of
 385 local clients.
 386
 387 num_specs
 388     Number of client ID specifications.
 389 client_specs
 390     A list specifying identification methods for clients. Supports
 391     multiple identification methods and clients in a single
 392     specification. See CLIENTIDSPEC for details.
 393 num_ids
 394     Number of IDs that were successfully determined. Can be different
 395     from num_specs or even zero if the server didn't support any
 396     identification methods for the given clients.
 397 client_ids
 398     A list specifying ID information for successfully identified
 399     clients. If wildcards were used in a single CLIENTIDSPEC of
 400     client_specs, then multiple CLIENTIDVALUE records may be returned
 401     for that CLIENTIDSPEC. See CLIENTIDVALUE for details.
 402
 403 A Value error is returned if the request specifies an invalid client
 404 XID or invalid identification method type.
 405
 406 ┌───
 407     XResQueryResourceBytes
 408     client:         CLIENTXID or None
 409     num_specs:      CARD32
 410     resource_specs: LISTofRESOURCEIDSPEC
 411     ▶
 412     num_sizes:      CARD32
 413     sizes:          LISTofRESOURCESIZEVALUE
 414
 415     Errors:         Atom, Value
 416 └───
 417
 418 XResQueryResourceBytes can be used to ask the sizes of resources from
 419 X server. The request sends a list of specifiers that selects
 420 resources for size calculation. The server tries to calculate the
 421 sizes of chosen resources and returns an estimate for a resource only
 422 if the size could be determined. It's not an error condition if a size
 423 couldn't be calculated. In that case the resources simply aren't
 424 included in the returned list.
 425
 426 The request supports wildcards so that in the most general case sizes
 427 of all resources of all clients can be queried with a single
 428 RESOURCEIDSPEC. However, the reply has all wildcards expanded and
 429 reports a size of a single resource in each RESOURCESIZEVALUE.
 430
 431 client
 432     An ID of a client can be given to limit the query to resources of
 433     that client. Just like in CLIENTIDSPEC, any resource ID can be
 434     given to identify a client and None can be used if the query
 435     shouldn't be limited to a specific client. Note that in some cases
 436     this field is redundant because resource_specs already fully
 437     determines which resources are selected. If the client ID doesn't
 438     match the owner of any resource in resource_specs, no sizes are
 439     returned and no error is generated.
 440 num_specs
 441     Number of resource specifications.
 442 resource_specs
 443     A list of resource specifications. Each specification can either
 444     uniquely identify a single resource or multiple resources if
 445     wildcarding is used. See RESOURCEIDSPEC for details.
 446 num_sizes
 447     Number of resources whose size could be determined. Can be
 448     different from num_specs or even zero if the server didn't support
 449     size calculation for the given resources.
 450 sizes
 451     A list of resource sizes. Each resource size is linked to a unique
 452     resource. Wildcards are never used in the returned size
 453     records. For example, it's not possible to receive a single
 454     RESOURCESIZEVALUE that would specify the size of all pixmaps if
 455     the sizes of pixmap type resources were asked. Instead, a single
 456     RESOURCESIZEVALUE would be returned for each pixmap in that case.
 457
 458 An Atom error is returned if the request specifies an invalid resource
 459 type. A Value error is returned if the request specifies an invalid
 460 XID for a client or a resource.
 461
 462                              ❧❧❧❧❧❧❧❧❧❧❧