Edit File: resproto.txt
DRAFT FOR REVIEW The X Resource Extension Version 1.2 Rami Ylimäki rami.ylimaki@vincit.fi ❧❧❧❧❧❧❧❧❧❧❧ 1. Introduction The protocol description of X Resource Extension version 1.1 has been either lost or has never been written. This specification documents version 1.0 based on reverse engineered library and server code. Version 1.1 has been accidentally released from the version control and while it doesn't have differences to version 1.0, this version is labeled 1.2 in order to remove the risk of confusion. In addition to the 1.0 description, this document introduces a new 1.2 version of the extension. Version 1.2 is a minor release and therefore the changes are compatible with the previous version. Main enhancements over version 1.0 are: - Client identification is now possible. For example, servers supporting version 1.2 may report PID of local clients. - Size of any resource can be queried from the server. Servers may not necessarily support size calculation for every resource. However, clients have now at least the chance to let the server do resource size estimation for them. ❧❧❧❧❧❧❧❧❧❧❧ 2. Notations used in this document Notation for data types and requests follows the guidelines set in sections 2-4 of X Window System Protocol standard. ❧❧❧❧❧❧❧❧❧❧❧ 3. Interoperability between version 1.1 and 1.2 Version 1.2 only introduces two new requests. However, these requests could be seen as generalized versions of existing requests. Even though we aren't deprecating any old requests, libraries could implement some old requests using the new ones. The new XResQueryClientIds request could be used instead of XResQueryClients. The new XResQueryResourceBytes request could be used instead of XResQueryClientPixmapBytes. Using the old requests is still acceptable because we don't want to change the semantics of existing requests between version 1.1 and 1.2. ❧❧❧❧❧❧❧❧❧❧❧ 4. Data types 4.1 Types in version 1.0 CLIENTXIDRANGE [ resource_base: CARD32 resource_mask: CARD32 ] This type is used for reply of XResQueryClients in version 1.1. It represents the range of resource allocated for a client and can be also used for client identification. resource_base First resource ID reserved for a client. Used also to identify the clients themselves. resource_mask Mask that can be used to identify a client from some resource ID. Just zero the bits indicated by this mask from any resource ID to identify the client that owns the resource. CLIENTXID [ client: XID ] This type identifies a single client by a resource owned by that client or by the first resource ID allocated for the client (resource_base of CLIENTXIDRANGE). Whenever a resource ID is used, it is masked by resource_mask of CLIENTXIDRANGE to find out the client that owns the resource. CLIENTRESOURCETYPECOUNT [ resource_type: ATOM count: CARD32 ] This type is used for reply of XResQueryClientResources in version 1.1. It represents the number of certain type of resources that are owned by some client. resource_type Atom specifying the type of a resource. count Number of resources of the given type owned by a client. 4.2 Types in version 1.2 4.2.1 Types used by XResQueryClientIds CLIENTIDMASK { ClientXid = 0x1, LocalClientPid = 0x2 } A bitmask specifying a client identification method. Currently only the PID of local clients is supported in the form of LocalClientPid. ClientXid is provided for backward compatibility with version 1.0 so that the new 1.2 requests (XResQueryClientIds) can be used in place of the older ones (XResQueryClients). CLIENTIDSPEC [ client: CLIENTXID or None mask: SETofCLIENTIDMASK or None ] A data structure for selecting client IDs. client ID of a resource allocated for some client. Only the part identifying a client is actually used. The resource_base of CLIENTXIDRANGE can be used if the client doesn't own any resources. However, any resource ID is accepted because that makes identifying the owners of existing resources easy. The null resource None can be used to select all clients. mask Collection of identification methods that should be applied on the client. The special value None can be used to apply all supported identification methods. CLIENTIDVALUE [ spec: CLIENTIDSPEC length: CARD32 value: LISTofCARD32 ] A data structure specifying a single client ID. spec A unique identifier for a specific ID of some client. Wildcards such as None and bitmask unions aren't allowed. The data structure must always identify a single client and single ID type. However, the client doesn't have to be specified as the resource_base of CLIENTXIDRANGE and can be any resource owned by the client. length Specifies the length of an ID in units of CARD32. The length depends on the ID type. In version 1.2 the lengths are 0 for ClientXid and 4 for LocalClientPid. The length of ClientXid is 0 because that is already stored in the spec field. value Actual ID data. In version 1.2 this is missing for ClientXid and consists of a single CARD32 for LocalClientPid. 4.2.2 Types used by XResQueryResourceBytes To better understand how resources are related to each other, it's useful to introduce the concepts of main resource and cross reference. By main resource we just mean a normal resource that has a valid XID. By cross reference we mean a resource that is used by some other resource. The same resource may have both of these roles depending on the context. For example, there could be an ordinary pixmap resource. When we talk about this resource in isolation the term main resource is used. We call the exact same resource a cross reference when we are concentrating on some higher level resource, such as window or graphics context, that is using the lower level resource. Cross references may also be internal server resources that don't have a valid XID. RESOURCEIDSPEC [ resource: XID or None type: ATOM or None/AnyPropertyType ] A data structure for selecting or identifying resources. The interpretation of fields changes depending on the context. The differences in interpretation are described below. resource An XID of a resource. The null resource None can be used to select all resources matching some type if the data structure is used in XResQueryResourceBytes request. The null resource None can be used to mark private server resources if the data structure is used in a cross reference of XResQueryResourceBytes reply. type An atom identifying the resource type. The null atom None/AnyPropertyType can be used to select all resource types matching some resource ID if the data structure is used in XResQueryResourceBytes request. RESOURCESIZESPEC [ spec: RESOURCEIDSPEC bytes: CARD32 ref_count: CARD32 use_count: CARD32 ] A data structure specifying the size of a single resource. spec Uniquely identifies a single resource. Wildcards such as None and AnyPropertyType aren't allowed for main resources. In cross references, None is used to mark internal server resources. bytes Number of bytes allocated for the resource. The size of a resource is never divided by a reference count. This is the number of bytes released in server when there are no more references left to the resource. ref_count Number of total users of the resource. Typically the reference count is 1 but for pixmaps and other resources used from different contexts the count may be larger. use_count Number of times the resource is used by some other resource. For main resources this is typically 1, because a resource doesn't usually use itself recursively. For cross references this is the number of times the resource is used and is also 1 usually. RESOURCESIZEVALUE [ size: RESOURCESIZESPEC num_cross_references: CARD32 cross_references: LISTofRESOURCESIZESPEC ] A data structure specifying sizes of cross references to other resources in addition to the main resource size. size Size of a main resource. num_cross_references Number of cross references to other resources from the main resource. Currently resources can only have pixmaps as cross references but this can be extended to other types in the future. For simple resources this field is therefore 0 and the cross_references list is missing. cross_references: Size specifications for cross references. Note that cross references may contain resources that don't have a valid XID. For example, a DRI2 drawable might have a cross reference to a private pixmap that is used internally in the server only. These private cross references are contained in this list also. This makes it possible to emulate XResGetClientPixmapBytes with XResGetResourceBytes. ❧❧❧❧❧❧❧❧❧❧❧ 5. Requests 5.1 Requests in version 1.0 ┌─── XResQueryVersion client_major: CARD8 client_minor: CARD8 ▶ server_major: CARD16 server_minor: CARD16 └─── The client sends the highest supported version to the server and the server sends the highest version it supports, but no higher than the requested version. Major version changes can introduce incompatibilities in existing functionality, minor version changes introduce only backward compatible changes. It is the client's responsibility to ensure that the server supports a version which is compatible with its expectations. client_major Major X Resource Extension version supported by client. client_minor Minor X Resource Extension version supported by client. server_major Highest version supported by server that is compatible with client. server_minor Highest version supported by server that is compatible with client. ┌─── XResQueryClients ▶ num_clients: CARD32 clients: LISTofCLIENTXIDRANGE └─── The request asks X server to return the list of all currently connected clients. num_clients Number of currently connected clients. clients List of XID ranges allocated for the connected clients. ┌─── XResQueryClientResources client: CLIENTXID ▶ num_types: CARD32 types: LISTofCLIENTRESOURCETYPECOUNT Errors: Value └─── This request can be used to ask the number of resources owned by a client. The server will return the counts of each type of resource. client An XID in the resource range of a client. This identifies the client and not some specific resource. num_types Number of different resource types owned by the client. types A list of counts for each resource type. A value error is generated if invalid resource or client XID is given in the request. ┌─── XResQueryClientPixmapBytes client: CLIENTXID ▶ bytes: CARD32 bytes_overflow: CARD32 Errors: Value └─── This request is used to get the pixmap usage of some client. The returned number is a sum of memory usage of each pixmap that can be attributed to the given client. Ideally the server goes through all pixmaps and divides each pixmap size by the pixmap reference count to get a pixmap reference size. The reference size is then added to the returned sum if the client happens to be referencing that pixmap. In practice some pixmap references may be missed, because it would be too difficult to keep track of all pixmap references. However, the server will check the most important client resources that are using pixmaps and tries to estimate the pixmap usage as well as is possible. In other words, the server need only make a best-effort attempt to calculate resource source, so actual resource size may differ from that reported in practice. client Identifies a client by an ID in its resource ID range. bytes: Number of bytes attributed to pixmap references from the client resources. bytes_overflow: Higher order word for the bytes field in case the sum of pixmap reference sizes doesn't fit in CARD32. A value error is generated if invalid resource or client XID is given in the request. 5.2 Requests in version 1.2 ┌─── XResQueryClientIds num_specs: CARD32 client_specs: LISTofCLIENTIDSPEC ▶ num_ids: CARD32 client_ids: LISTofCLIENTIDVALUE Errors: Value └─── XResQueryClientIds can be used to identify a given set of clients with some identification method. The request sends a list of specifiers that select clients and identification methods to server. The server then tries to identify the chosen clients using the identification methods specified for each client. The server returns IDs for those clients that were successfully identified. It's not an error condition if some identification method couldn't be applied to a client. If the server is unable to identify some clients, they simply aren't included in the returned list. The request supports wildcards in the client specifications so that in the most general case all IDs of all clients can be queried with a single CLIENTIDSPEC. The CLIENTIDSPEC of request and CLIENTIDSPEC of CLIENTIDVALUE in reply usually match each other. For example, if a request selected a client by a resource ID owned by the client, then the client is identified by the same resource ID in the reply. This has been done so that it would be easy to identify an owner of some resource. However, the CLIENTIDSPEC of returned CLIENTIDVALUE never contains any wildcards. If the request used a wildcard to specify all clients in a single CLIENTIDSPEC, then the reply has expanded the wildcard and returns separate CLIENTIDVALUE records for each client. In this case wildcarded clients are identified by resource_base of CLIENTXIDRANGE. The LocalClientPid type of IDs are included in the reply list only if the client executing the request asked for it and was also a local client itself. It doesn't make sense for remote clients to ask PIDs of local clients. num_specs Number of client ID specifications. client_specs A list specifying identification methods for clients. Supports multiple identification methods and clients in a single specification. See CLIENTIDSPEC for details. num_ids Number of IDs that were successfully determined. Can be different from num_specs or even zero if the server didn't support any identification methods for the given clients. client_ids A list specifying ID information for successfully identified clients. If wildcards were used in a single CLIENTIDSPEC of client_specs, then multiple CLIENTIDVALUE records may be returned for that CLIENTIDSPEC. See CLIENTIDVALUE for details. A Value error is returned if the request specifies an invalid client XID or invalid identification method type. ┌─── XResQueryResourceBytes client: CLIENTXID or None num_specs: CARD32 resource_specs: LISTofRESOURCEIDSPEC ▶ num_sizes: CARD32 sizes: LISTofRESOURCESIZEVALUE Errors: Atom, Value └─── XResQueryResourceBytes can be used to ask the sizes of resources from X server. The request sends a list of specifiers that selects resources for size calculation. The server tries to calculate the sizes of chosen resources and returns an estimate for a resource only if the size could be determined. It's not an error condition if a size couldn't be calculated. In that case the resources simply aren't included in the returned list. The request supports wildcards so that in the most general case sizes of all resources of all clients can be queried with a single RESOURCEIDSPEC. However, the reply has all wildcards expanded and reports a size of a single resource in each RESOURCESIZEVALUE. client An ID of a client can be given to limit the query to resources of that client. Just like in CLIENTIDSPEC, any resource ID can be given to identify a client and None can be used if the query shouldn't be limited to a specific client. Note that in some cases this field is redundant because resource_specs already fully determines which resources are selected. If the client ID doesn't match the owner of any resource in resource_specs, no sizes are returned and no error is generated. num_specs Number of resource specifications. resource_specs A list of resource specifications. Each specification can either uniquely identify a single resource or multiple resources if wildcarding is used. See RESOURCEIDSPEC for details. num_sizes Number of resources whose size could be determined. Can be different from num_specs or even zero if the server didn't support size calculation for the given resources. sizes A list of resource sizes. Each resource size is linked to a unique resource. Wildcards are never used in the returned size records. For example, it's not possible to receive a single RESOURCESIZEVALUE that would specify the size of all pixmaps if the sizes of pixmap type resources were asked. Instead, a single RESOURCESIZEVALUE would be returned for each pixmap in that case. An Atom error is returned if the request specifies an invalid resource type. A Value error is returned if the request specifies an invalid XID for a client or a resource. ❧❧❧❧❧❧❧❧❧❧❧