X Record Extension Library

X Consortium Standard

Martha Zimet

Network Computing Devices, Inc.

Edited by

Stephen Gildea

X Consortium

X Version 11, Release 7.7

Version 1.13

Copyright © 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.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents

1. Record Extension Overview

    Synchronous Playback
    Design Approach
    Record Clients

2. Common Arguments

    Datum Flags
    Selecting Clients
    Protocol Ranges

3. Library Extension Requests

    Query Extension Version
    Create and Modify Context

        Additions
        Deletions

    Query Context State
    Data Transfer

        Enable Context
        Enable Context Asynchronously
        Disable Context

    ID Base Mask
    Free Context

Chapter 1. Record Extension Overview

Table of Contents

Synchronous Playback
Design Approach
Record Clients

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

  • XRecordQueryVersion

    query the extension protocol version.

  • XRecordCreateContext

    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.

  • XRecordEnableContext

    begin the recording and reporting of protocol data.

  • XRecordDisableContext

    end the recording and reporting of protocol data.

  • XRecordFreeContext

    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.

Chapter 2. Common Arguments

Table of Contents

Datum Flags
Selecting Clients
Protocol Ranges

The Record extension functions XRecordCreateContext and XRecordRegisterClients
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 Protocol Ranges

The Record extension functions XRecordCreateContext and XRecordRegisterClients
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 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.

Protocol Ranges

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:


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

Chapter 3. Library Extension Requests

Table of Contents

Query Extension Version
Create and Modify Context

    Additions
    Deletions

Query Context State
Data Transfer

    Enable Context
    Enable Context Asynchronously
    Disable Context

ID Base Mask
Free Context

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 XRecordQueryVersion 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 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.

Create and Modify Context

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.

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 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
( 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 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


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 XRecordRegisterClients 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 Datum
Flags ). 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 Selecting Clients are performed.

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

XRecordRegisterClients 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 XRecordGetContext 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 XRecordGetContext 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.

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

void XRecordFreeState(XRecordState *state);

state Specifies the structure that is to be freed.

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.

Data Transfer

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.

Enable Context

To direct the X server to record and report protocol, a program uses
XRecordEnableContext 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 XRecordFreeData 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.

XRecordEnableContext 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.

XRecordEnableContext 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 XRecordEnableContext does not return until XRecordDisableContext is
executed on the control connection, a nonblocking interface in addition to
XRecordEnableContext 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.

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

XRecordEnableContextAsync 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 XRecordProcessReplies
function.

void XRecordProcessReplies(Display *display);

display Specifies the connection to the X server.

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

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

void XRecordFreeData(XRecordInterceptData *data);

data Specifies the structure that is to be freed.

XRecordFreeData frees the data pointed to by data. If the argument does not
match an XRecordInterceptData pointer earlier passed to an XRecordInterceptProc
callback or if XRecordFreeData 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 XRecordDisableContext 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 XRecordDisableContext 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.

XRecordDisableContext 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
XRecordIdBaseMask

XID XRecordIdBaseMask(Display *display);

display Specifies the connection to the X server.

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

