# X Record Extension Library

X Consortium Standard

X Version 11, Release &fullrelvers;
Version 1.13
Martha Zimet
Network Computing Devices, Inc.
Stephen Gildea
X Consortium
1994 Network Computing Devices, Inc.

Permission to use, copy, modify, distribute, and sell this documentation for any purpose is hereby granted without fee, provided that the above copyright notice and this permission notice appear in all copies. Network Computing Devices, Inc. makes no representations about the suitability for any purpose of the information in this document. This documentation is provided "as is" without express or implied warranty.

Copyright © 1995 X Consortium

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.

X Window System is a trademark of The Open Group.

## Record Extension Overview

The purpose of this extension is to support the recording and reporting of all core X protocol and arbitrary X extension protocol. This first section gives an overview of the Record extension. The following sections describe how to use the Record extension library.

### Synchronous Playback

Environment information is generally provided to an X-based playback mechanism, which might use the XTest extension to synthesize input events. This synchronization information defines the X state prior to event synthesis (for example, location of the cursor, window locations and sizes, installed colormap, window manager running, and so on) and the consequences that occur after the playback mechanism synthesizes the event. If the user moves the mouse into the icon window and presses and releases a mouse button, the device events `MotionNotify`, `ButtonPress`, and `ButtonRelease` are generated by the X server. Because X follows an event-driven model, there are consequences that follow from the user actions, or device events, that are in the form of X protocol. As a result of the previous user actions, the client could generate requests such as `ImageText8` and `PolyLine` to the X server, or the X server could send non-device events such as `Expose` and `MapNotify` to the client window. Both the requests and non-device events that result from user actions are known as consequences, which can be used as a synchronization, or control point, during playback. That is, the playback mechanism does not generate a specific synthesized event until its matching synchronization condition occurs (for example, the window is mapped or unmapped, the cursor changes, a text string displays, and so on)

Because it cannot be predicted what synchronization information is required during playback, the Record extension makes no assumptions about the intended use of the recorded data. Facilities exist to record any core X protocol or X extension protocol. Therefore, Record does not enforce a specific synchronization methodology.

### Design Approach

The design approach of the extension is to record core X protocol and arbitrary X extension protocol entirely within the X server itself. When the extension has been requested to record specific protocol by one or more recording clients, the protocol data is formatted and returned to the recording clients. The extension provides a mechanism for capturing all events, including input device events that do not go to any clients.

### Record Clients

The recommended communication model for a Record application is to open two connections to the server—one connection for recording control and one connection for reading recorded protocol data.

Information about recording (for example, what clients to record, what protocol to record for each client, and so on) is stored in resources called record contexts (type `XRecordContext`). Most Record extension functions take a record context as an argument. Although in theory it is possible to share record contexts between applications, it is expected that applications will use their own context when performing recording operations.

A client that wishes to record X protocol does so through the library functions defined in A typical sequence of requests that a client would make is as follows:

- query the extension protocol version.

- request that the server create a record context for access by this client, and express interest in clients and protocol to be recorded. This request returns an `XRecord-Context`, which is an XID that is used by most other extension requests to identify the specified context.

- begin the recording and reporting of protocol data.

- end the recording and reporting of protocol data.

- free the record context.

The header for this library is <`X11/extensions/record.h`>. All identifiers defined in the interface are supplied by this header and are prefixed with "XRecord". The `Xtst` library contains the `XRecord` functions.

## Common Arguments

The Record extension functions and allow applications to specify the following:

- Individual clients or sets of clients to record

- Ranges of core X protocol and X extension protocol to record for each client

Protocol in the ranges specified by the recording client will be recorded by the server. The device_events protocol type can be specified by a recording client although it may not be sent to a recorded client. The device_events type differs from delivered_events, which also can be specified by a recording client; delivered_events are actually delivered to one or more clients. These event types are discussed in

The Record extension functions and have the common arguments datum_ﬂags, clients, and ranges, which specify whether server time and/or client sequence number should precede protocol elements, the clients or client set to record, and the protocol ranges to record, respectively. These are discussed in the following sections.

### Datum Flags

The datum_ﬂags argument is a set of ﬂags OR’ed together to specify options for the record context. Specify zero to disable all the options.

The `XRecordFromServerTime` ﬂag specifies that `XRecordInterceptData` structures with a category of `XRecordFromServer` will have a server_time field specific to each protocol element.

The `XRecordFromClientTime` ﬂag specifies that `XRecordInterceptData` structures with a category of `XRecordFromClient` will have a server_time field specific to each protocol element.

The `XRecordFromClientSequence` ﬂag specifies that `XRecordInterceptData` structures with a category of `XRecordFromClient` or `XRecordClientDied` will have a valid client_seq field.

### Selecting Clients

The clients argument is a pointer to an array of `XRecordClientSpec`. `XRecordClientSpec` is an integral type that holds a resource ID, a client resource ID base, or one of the client set constants defined below.

Duplicate elements in the array are ignored by the functions, and if any element in the array is not valid, a `BadMatch` error results. A resource ID references the client that created that resource. The client set may be one of the following constants: `XRecordCurrentClients`, `XRecordFutureClients`, or `XRecordAllClients`.

If the element in the array identifies a particular client, protocol specified by the ranges argument will be recorded by the server. The recorded protocol data will not be returned to the recording client until the record context has been enabled. This is described in

If the element is `XRecordCurrentClients`, the protocol ranges specified by the ranges argument, except for device_events, are associated with each current client connection. If the element is `XRecordFutureClients`, the protocol ranges specified by the ranges argument are associated with each new client connection. If the element is `XRecordAllClients`, the protocol ranges specified by the ranges argument are associated with each current client connection and with each new client connection. When the context is enabled, the data connection is unregistered if it was registered. If the context is enabled, `XRecordCurrentClients` and `XRecordAllClients` silently exclude the recording data connection. It is an error to explicitly register the data connection.

### Protocol Ranges

The functions and have another common argument, ranges, which is an array of pointers to `XRecordRange` structures. Each structure contains ranges of numeric values for each of the protocol types that can be specified and recorded individually by the Record extension. An `XRecordRange` structure must be allocated by the Record library using the `XRecordAllocRange` function.

The `XRecordRange` typedef is a structure with the following members:

    XRecordRange:
         XRecordRange8 core_requests     /* core X requests */
         XRecordRange8 core_replies      /* core X replies */
         XRecordExtRange ext_requests    /* extension requests */
         XRecordExtRange ext_replies     /* extension replies */
         XRecordRange8 delivered_events  /* delivered core and ext events */
         XRecordRange8 device_events     /* all core and ext device events */
         XRecordRange8 errors            /* core X and X ext errors */
         Bool client_started             /* connection setup reply from server */
         Bool client_died                /* notification of client disconnect */

The types used in `XRecordRange` members are defined as follows. The `XRecordRange8` typedef is a structure with the following members:

    XRecordRange8:
         unsigned char first
         unsigned char last

The `XRecordRange16` typedef is a structure with the following members:

    XRecordRange16:
         unsigned short first
         unsigned short last

The `XRecordExtRange` typedef is a structure with the following members:

    XRecordExtRange:
         XRecordRange8  ext_major
         XRecordRange16 ext_minor

If any of the values specified in `XRecordRange` is invalid, a `BadValue` error results.

The core_requests member specifies the range of core X protocol requests to record. Core X protocol requests with a major opcode that is between first and last, inclusive, will be recorded. A `BadValue` error results if the value of first is greater than the value of last. If the values of both first and last are zero, no core X protocol requests will be recorded.

The core_replies member specifies the range of replies resulting from core X protocol requests to record. Replies that result from core X protocol requests with a major opcode between first and last, inclusive, will be recorded. A `BadValue` error results if the value of first is greater than the value of last. If the values of both first and last are zero, no core X protocol replies will be recorded.

The ext_requests member specifies the range of X extension requests to record. X extension requests with a major opcode between ext_major.first and ext_major.last, and with a minor opcode between ext_minor.first and ext_minor.last, inclusive, will be recorded. A `BadValue` error results if the value of ext_major.first is greater than the value of ext_major.last or if the value of ext_minor.first is greater than the value of ext_minor.last. If the values of both ext_major.first and ext_major.last are zero, no X extension requests will be recorded.

The ext_replies member specifies the range of replies resulting from X extension requests to record. Replies that result from an X extension request with a major opcode between ext_major.first and ext_major.last, and a minor opcode that is between ext_minor.first and ext_minor.last will be recorded. A `BadValue` error results if the value of ext_major.first is greater than the value of ext_major.last or if the value of ext_minor.first is greater than the value of ext_minor.last. If the values of both ext_major.first and ext_major.last are zero, no X extension replies will be recorded.

The delivered_events member specifies the range of both core X events and X extension events to record. These events are delivered to at least one client. Core X events and X extension events with a code value between first and last inclusive will be recorded. A `BadValue` error results if the value of first is greater than the value of last. If the values of first and last are zero, no events will be recorded.

The device_events member specifies the range of both core X device events and X extension device events to record. These events may or may not be delivered to a client. Core X device events and X extension device events with a code value between first and last inclusive that are not delivered to any clients will be recorded. A `BadValue` error results if the value of first is greater than the value of last. A `BadValue` error results if first is less than two or last is less than two, except that if first and last are zero, no events will be recorded.

The errors member specifies the range of both core X errors and X extension errors to record. Core X errors and X extension errors with a code value between first and last inclusive will be recorded. A `BadValue` error results if the value of first is greater than the value of last. If the values of first and last are zero, no errors will be recorded.

A value of `True` for the client_started member specifies the connection setup reply from the server to new clients. If `False` the connection setup reply is not specified by this `XRecordRange`

A value of `True` for the client_died member specifies notification when a client disconnects. If `False` notification when a client disconnects is not specified by this `XRecordRange`

## Library Extension Requests

Recording operations are accessed by programs through the use of new protocol requests. The following functions are provided as extensions to Xlib. An Xlib error results if an extension request is made to an X server that does not support the Record extension. Note that any of the extension protocol requests may generate `BadAlloc` or `BadLength` errors.

### Query Extension Version

An application uses the function to determine the version of the Record extension protocol supported by an X server.

Status `XRecordQueryVersion` Display *display int cmajor_return int cminor_return

display

  Returns the connection to the X server.

cmajor_return

  Returns the extension protocol major version in use.

cminor_return

  Returns the extension protocol minor version in use.

The function returns the major and minor protocol version numbers supported by the server. returns nonzero (success) only if the returned version numbers are common to both the library and the server; otherwise, it returns zero.

### Create and Modify Context

An application uses the function to create a record context. At the time the record context is created by the recording client, the clients to be recorded and the protocol to record for each client may be specified.

XRecordContext `XRecordCreateContext` Display *display int datum_flags XRecordClientSpec *clients int nclients XRecordRange *ranges int nranges

display

  Returns the connection to the X server.

datum_flags

  Specifies whether detailed time or sequence info should be sent.

clients

  Specifies the clients to record.

nclients

  Specifies the number of clients.

ranges

  Specifies the protocol ranges to record.

nranges

  Specifies the number of protocol ranges.

The function creates a record context and returns an `XRecordContext` which is then used in the other Record library calls. This request is typically executed by the recording client over its control connection to the X server. The datum_flags specifies whether server time and/or client sequence number should precede protocol elements recorded by context ( ). When a clients element identifies a particular client, the client is added to the context and the protocol to record for that client is set to the union of all ranges. When a clients element is `XRecordCurrentClients` `XRecordFutureClients` or `XRecordAllClients` the actions described in are performed.

returns zero if the request failed. can generate `BadIDChoice` `BadMatch` and `BadValue` errors.

The ranges argument is an `XRecordRange` array, that is, an array of pointers. The structures the elements point to shall be allocated by calling `XRecordAllocRange`

    XRecordRange *
    XRecordAllocRange(void)

The `XRecordAllocRange` function allocates and returns an `XRecordRange` structure. The structure is initialized to specify no protocol. The function returns NULL if the structure allocation fails. The application can free the structure by calling `XFree`

#### Additions

An application uses the function to modify a previously created record context, by adding clients or modifying the recorded protocol, typically over its control connection to the X server.

Status `XRecordRegisterClients` Display *display XRecordContext context int datum_flags XRecordClientSpec *clients int nclients XRecordRange *ranges int nranges

display

  Returns the connection to the X server.

context

  Specifies the record context to modify.

datum_flags

  Specifies whether detailed time or sequence info should be sent.

clients

  Specifies the clients to record.

nclients

  Specifies the number of clients.

ranges

  Specifies the protocol ranges to record.

nranges

  Specifies the number of protocol ranges.

The datum_flags specifies whether server time and/or client sequence number should precede protocol elements for all clients recorded by context (See ). When a clients element identifies a particular client and the client is not yet targeted for recording in the given context, the client is added to the set of clients to record, and the protocol to record for that client is set to the union of all ranges. When the client is already targeted for recording, the protocol to record for that client is set to the union of all ranges. When the element is `XRecordCurrentClients` `XRecordFutureClients` or `XRecordAllClients` the actions described in are performed.

returns zero if the request failed; otherwise, it returns nonzero.

can generate `XRecordBadContext` `BadMatch` and `BadValue` errors.

#### Deletions

An application uses the `XRecordUnregisterClients` function to delete clients from a previously created record context, typically over its control connection to the X server.

Status `XRecordUnRegisterClients` Display *display XRecordContext context XRecordClientSpec *clients int nclients

display

  Returns the connection to the X server.

context

  Specifies the record context to modify.

clients

  Specifies the clients to stop recording.

nclients

  Specifies the number of clients.

When an element in clients identifies a particular client, and the specified client is already targeted for recording in the given context, the client and the set of protocol to record for that client are deleted from the context. If the specified client is not targeted for recording, then no action is performed.

When the element is `XRecordCurrentClients` all clients currently targeted for recording in context and their corresponding sets of protocol to record are deleted from context.

When the item is `XRecordFutureClients` any future client connections will not automatically be targeted for recording in context.

When the element is `XRecordAllClients` all clients currently targeted for recording in context and their corresponding sets of protocol to record are deleted from context. Any future client connections will not automatically be targeted for recording in context.

`XRecordUnregisterClients` returns zero if the request failed; otherwise, it returns nonzero.

`XRecordUnregisterClients` can generate `XRecordBadContext` `BadMatch` and `BadValue` errors.

### Query Context State

An application uses the function to query the current state of a record context, typically over its control connection to the X server.

Status `XRecordGetContext` Display *display XRecordContext context XRecordState **state_return

display

  Specifies the connection to the X server.

context

  Specifies the record context to query.

state_return

  Specifies the address of a variable into which the function stores a pointer to the current state of the record context.

The `XRecordState` typedef returned by is a structure with the following members:

    XRecordState:
         Bool              enabled
         int               datum_flags
         unsigned long     nclients
         XRecordClientInfo **client_info

The enabled member is set to the state of data transfer and is `True` when the recording client has asked that recorded data be sent; otherwise it is `False` The datum_flags member is set to the value of these flags for this context. The nclients member is set to the number of `XRecordClientInfo` structures returned. The client_info member is an array of pointers to `XRecordClientInfo` structures that contain the protocol to record for each targeted client. The `XRecordClientInfo` typedef is a structure with the following members:

    XRecordClientInfo:
         XRecordClientSpec client
         unsigned long nranges
         XRecordRange **ranges

The client member either identifies a client targeted for recording or is set to `XRecordFutureClients` to describe how future clients will be automatically targeted for recording. The nranges member is set to the number of protocol ranges to be recorded for the specified client. The ranges member is an array of pointers to `XRecordRange` structures, which specify the protocol ranges to record.

returns zero if the request failed; otherwise, it returns nonzero. The context argument must specify a valid `XRecordContext` or a `XRecordBadContext` error results.

Recording clients should use the function to free the state data returned by

void `XRecordFreeState` XRecordState *state

state

  Specifies the structure that is to be freed.

frees the data pointed to by state. If the argument does not match an `XRecordState` pointer returned from a successful call to or if has already been called with it, the behavior is undefined.

### Data Transfer

An application uses the and functions to change the state of data transfer between the X server and the recording client. These functions allow the application to start recording and reporting of protocol data and to stop recording and reporting of protocol data, respectively.

#### Enable Context

To direct the X server to record and report protocol, a program uses typically over its data connection to the X server. The reporting of recorded protocol back to the recording client is handled by the following data structures and procedure definitions. Each recorded protocol element is reported to the recording client through an `XRecordInterceptData` typedef, a structure with the following members:

    XRecordInterceptData:
         XID              id_base
         Time             server_time
         unsigned long    client_seq
         int              category
         Bool             client_swapped
         unsigned char    *data
         unsigned long    data_len

The id_base member is set to the resource identifier base sent to the client in the connection setup reply and therefore identifies the client being recorded, except when the recorded protocol data is a device event that may have not been delivered to a client. In this case, id_base is set to zero. The server_time member is set to the time of the server when the protocol was recorded. It is the time that was attached to this protocol element in the reply, if so specified by datum_flags, or else the time from the header of the reply that contained this protocol element. The client_seq member is the sequence number of the recorded client's most recent request processed by the server at the time this protocol element was recorded, if this information were included in the recorded data; otherwise client_seq is 0. The category member is set to one of the following values: `XRecordStartOfData` `XRecordFromServer` `XRecordFromClient` `XRecordClientStarted` `XRecordClientDied` or `XRecordEndOfData` `XRecordStartOfData` is immediately sent as the first reply to confirm that the context is enabled. `XRecordFromClient` indicates the protocol data is from the recorded client to the server (requests). `XRecordFromServer` indicates the protocol data is from the server to the recorded client (replies, errors, events, or device events). `XRecordClientStarted` indicates that the protocol data is the connection setup reply from the server. `XRecordClientDied` indicates that the recorded client has closed its connection to the X server; there is no protocol data. `XRecordEndOfData` indicates that the context has been disabled and that this is the last datum. It does not correspond to any protocol or state change in a recorded client. There is no protocol data.

The client_swapped member is set to `True` if the byte order of the client being recorded is swapped relative to the recording client; otherwise, it is set to `False` All recorded protocol data is returned in the byte order of the recorded client. Therefore, recording clients are responsible for all byte swapping, if required. Device events are in the byte order of the recording client. For replies of category `XRecordStartOfData` and `XRecordEndOfData` client_swapped is set according to the byte order of the server relative to the recording client.

The data member contains the actual recorded protocol data. When category is set to `XRecordStartOfData` `XRecordClientDied` or `XRecordEndOfData` no protocol data are contained in data.

For the core X events `KeyPress` `KeyRelease` `ButtonPress` and `ButtonRelease`, the fields of a device event that contain valid information are time and detail. For the core X event `MotionNotify` the fields of a device event that contain valid information are time, root, root-x and root-y. The time field refers to the time the event was generated by the device.

For the extension input device events `DeviceKeyPress` `DeviceKeyRelease` `DeviceButtonPress` and `DeviceButtonRelease` the fields of a device event that contain valid information are device, time, and detail. For `DeviceMotionNotify` the valid device event fields are device and time. For the extension input device events `ProximityIn` and `ProximityOut` the fields of a device event that contain valid information are device and time. For the extension input device event `DeviceValuator` the fields of a device event that contain valid information are device, num_valuators, first_valuator, and valuators. The time field refers to the time the event was generated by the device.

The data_len member is set to the length of the actual recorded protocol data in 4-byte units.

When the context has been enabled, protocol data the recording client has previously expressed interest in is recorded and returned to the recording client via multiple replies. Because the X server batches the recorded data, more than one protocol element may be contained in the same reply packet. When a reply is received, a procedure of type `XRecordInterceptProc` is called for each protocol element in the reply.

typedef void `(*XRecordInterceptProc)` XPointer closure XRecordInterceptData *recorded_data

closure

  Pointer that was passed in when the context was enabled.

recorded_data

  A protocol element recorded by the server extension.

This callback may use the control display connection (or any display connection other than the data connection).

Recording clients should use the function to free the `XRecordInterceptData` structure.

Status `XRecordEnableContext` Display *display XRecordContext context XRecordInterceptProc callback XPointer closure

display

  Specifies the connection to the X server.

context

  Specifies the record context to enable.

callback

  Specifies the function to be called for each protocol element received.

closure

  Specifies data passed to callback.

enables data transfer between the recording client and the X server. All core and extension protocol received from or sent to targeted clients that the recording client has expressed interest in will be recorded and reported to the recording client.

returns zero if the request failed; otherwise, it returns nonzero. The context argument must specify a valid `XRecordContext` or a `XRecordBadContext` error results. The error `BadMatch` results when data transfer is already enabled on the given context.

#### Enable Context Asynchronously

Because does not return until is executed on the control connection, a nonblocking interface in addition to is provided. This interface also enables data transfer; however, it does not block.

This interface is defined as follows:

Status `XRecordEnableContextAsync` Display *display XRecordContext context XRecordInterceptProc callback XPointer closure

display

  Specifies the connection to the X server.

context

  Specifies the record context to enable.

callback

  Specifies the function to be called for each protocol element received.

closure

  Specifies data passed to callback.

enables data transfer between the recording client and the X server just as does. Unlike it does not wait for the context to be disabled before returning; returns as soon as the `XRecordStartOfData` reply has been received and processed.

returns zero if it could not allocate the necessary memory and nonzero if it sent the request successfully to the server. The context argument must specify a valid `XRecordContext` or a `XRecordBadContext` error results. The error `BadMatch` results when data transfer is already enabled.

Each time it reads data from the server connection, Xlib will check for incoming replies and call callback as necessary. The application may direct Xlib explicitly to check for Record data with the function.

void `XRecordProcessReplies` Display *display

display

  Specifies the connection to the X server.

will check for any replies that have not yet been processed by the application. The asynchronous callback will be called as appropriate. returns when all immediately available replies have been processed. It does not block.

To free the data passed to the `XRecordInterceptProc` callback, use

void `XRecordFreeData` XRecordInterceptData *data

data

  Specifies the structure that is to be freed.

frees the data pointed to by data. If the argument does not match an `XRecordInterceptData` pointer earlier passed to an `XRecordInterceptProc` callback or if has already been called with it, the behavior is undefined.

#### Disable Context

To direct the X server to halt the reporting of recorded protocol, the program executes typically over its control connection to the X server.

Status `XRecordDisableContext` Display *display XRecordContext context

display

  Specifies the connection to the X server.

context

  Specifies the record context to disable.

The function disables context, stopping all recording over its data connection. Any complete protocol elements for context that were buffered in the server will be sent to the recording client rather than being discarded. If a program attempts to disable an `XRecordContext` that has not been enabled, no action will take place.

returns zero if the request failed; otherwise, it returns nonzero. The context argument must specify a valid `XRecordContext` or an `XRecordBadContext` error results.

### ID Base Mask

To determine the mask the server uses for the client ID base, use

XID `XRecordIdBaseMask` Display *display

display

  Specifies the connection to the X server.

The function returns the resource ID mask passed to the client by the server at connection setup.

### Free Context

Before terminating, the program should request that the server free the record context. This is done with the function, typically over the record client's control connection to the X server.

Status `XRecordFreeContext` Display *display XRecordContext context

display

  Specifies the connection to the X server.

context

  Specifies the record context to free.

The function frees the given context for the requesting client. Freeing a record context releases the clients targeted for recording and their respective protocol ranges to record. If protocol data is being reported to the recording client, generally over the data connection to the X server, the reporting ceases as if had been called on the given context. When a program terminates without freeing its record context, the X server will automatically free that context on behalf of the client.

returns zero if the request failed; otherwise,it returns nonzero. The context argument must specify a valid `XRecordContext` or a `XRecordBadContext` error results.