[RFC][PATCH resourceproto] Protocol description of X Resource Extension version 1.2.
Rami Ylimäki
rami.ylimaki at vincit.fi
Wed Nov 10 06:34:58 PST 2010
Signed-off-by: Rami Ylimäki <rami.ylimaki at 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.ylimaki at 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
More information about the xorg-devel
mailing list