Signed-off-by: Rami Ylimäki <rami.ylim...@vincit.fi> --- RESproto.txt | 268 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 268 insertions(+), 0 deletions(-) create mode 100644 RESproto.txt
diff --git a/RESproto.txt b/RESproto.txt new file mode 100644 index 0000000..74193bb --- /dev/null +++ b/RESproto.txt @@ -0,0 +1,268 @@ + DRAFT FOR REVIEW + The X Resource Extension + Version 1.2 + Rami Ylimäki + rami.ylim...@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 +only the changes from version 1.1 to version 1.2. The X Resource +Extension is quite simple and therefore the description of version 1.1 +could be reverse engineered into this document later if the need +arises. + +Version 1.2 is a minor release and therefore the changes are +compatible with the previous version. Main enhacements over version +1.1 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 extended 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 though because we don't +want to change the existing requests between version 1.1 and 1.2. + + ❧❧❧❧❧❧❧❧❧❧❧ + +4. Data types + +4.1 Types in version 1.1 + +CLIENTXIDRANGE [ resource_base: CARD32 + resource_mask: CARD32 ] + This type is used for reply of XResQueryClients in version 1.1. +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. + +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.1 so that the new 1.2 requests (XResQueryClientIds) + can be used in place of the older ones (XResQueryClients). + +CLIENTIDSPEC [ client: XID 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 + +RESOURCEIDSPEC [ resource: XID or None + type: ATOM or None/AnyPropertyType ] + A data structure for selecting resources. +resource + An XID of a resource. The null resource None can be used to select + all resources matching some type. +type + An atom identifying the resource type. The null atom + None/AnyPropertyType can be used to select all resource types + matching some resource ID. + +RESOURCESIZEVALUE [ spec: RESOURCEIDSPEC + bytes: CARD32 + references: 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. +bytes + Number of bytes allocated for the resource. The size is not + divided by a reference count. Note that this is different from + return value of XResQueryClientPixmapBytes, which holds the pixmap + size divided by its reference count. +references + Number of references to the resource. Typically the reference + count is 1 but for pixmaps the reference count may be larger. + + ❧❧❧❧❧❧❧❧❧❧❧ + +5. Requests + +5.1 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 aren't simply included +in the returned list. + +The request supports wildcards in the client specifications so that in +the most general case all identification methods of all clients can be +queried with a single CLIENTIDSPEC. + +The CLIENTIDSPEC of request and CLIENTIDSPEC of CLIENTIDVALUE in reply +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: XID 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. +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. + + ❧❧❧❧❧❧❧❧❧❧❧ -- 1.6.3.3 _______________________________________________ xorg-devel@lists.x.org: X.Org development Archives: http://lists.x.org/archives/xorg-devel Info: http://lists.x.org/mailman/listinfo/xorg-devel