X Record Extension Library

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.

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.

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 Chapter 3, Library Extension Requests A typical sequence of requests that a client would make is as follows:

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.

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

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

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

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

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 the section called “Data Transfer”

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.

The functions XRecordCreateContext and XRecordRegisterClients 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:

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

The XRecordRange16 typedef is a structure with the following members:

The XRecordExtRange typedef is a structure with the following members:

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

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

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

An application uses the XRecordCreateContext 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.

The XRecordCreateContext 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 ( the section called “Datum Flags” ). 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 the section called “Selecting Clients” are performed.

XRecordCreateContext returns zero if the request failed. XRecordCreateContext 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

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

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

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

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:

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.

XRecordGetContext 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 XRecordFreeState function to free the state data returned by XRecordGetContext

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

An application uses the XRecordEnableContext and XRecordDisableContext 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.

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

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

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

The XRecordFreeContext 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 XRecordDisableContext 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.

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