1mX Record Extension Library0m

			1mVersion 1.130m

		   1mX Consortium Standard0m

		 1mX Version 11, Release 6.40m






			Martha Zimet
	      Network Computing Devices, Inc.






			 edited by
		       Stephen Gildea
			X Consortium
















































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 documen-
tation is provided "as is" without express or implied war-
ranty.

Copyright © 1995  X Consortium

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documenta-
tion 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 above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.

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 PUR-
POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM 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 Con-
sortium and 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.









1mX11, Release 6.4	   X Record Extension Library, Version 1.130m


1m1.  Record Extension Overview0m

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

1m1.1.	Synchronous Playback0m

Environment information is generally provided to an X-based play-
back 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 cur-
sor, window locations and sizes, installed colormap, window man-
ager 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 4mMotionNotify24m, 4mButtonPress24m, and 4mButton-0m
4mRelease24m 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 proto-
col.  As a result of the previous user actions, the client could
generate requests such as 4mImageText824m and 4mPolyLine24m to the X
server, or the X server could send non-device events such as
4mExpose24m and 4mMapNotify24m to the client window.  Both the requests and
non-device events that result from user actions are known as 4mcon-0m
4msequences24m, 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 synchro-
nization 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.  Facili-
ties exist to record any core X protocol or X extension protocol.
Therefore, Record does not enforce a specific synchronization
methodology.

1m1.2.	Design Approach0m

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.

1m1.3.	Record Clients0m

The recommended communication model for a Record application is
to open two connections to the server--one connection for



				1m10m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m


recording control and one connection for reading recorded proto-
col 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 4mrecord24m 4mcontexts24m (type 4mXRecordContext24m).	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 section 3 "Library Extension
Requests".  A typical sequence of requests that a client would
make is as follows:

·    4mXRecordQueryVersion24m - query the extension protocol version.

·    4mXRecordCreateContext24m - request that the server create a
     record context for access by this client, and express inter-
     est in clients and protocol to be recorded.  This request
     returns an 4mXRecordContext24m, which is an XID that is used by
     most other extension requests to identify the specified con-
     text.

·    4mXRecordEnableContext24m - begin the recording and reporting of
     protocol data.

·    4mXRecordDisableContext24m - end the recording and reporting of
     protocol data.

·    4mXRecordFreeContext24m - free the record context.

The header for this library is <4mX11/extensions/record.h24m>.	All
identifiers defined in the interface are supplied by this header
and are prefixed with "XRecord".  The 4mXtst24m library contains the
4mXRecord24m functions.

1m2.  Common Arguments0m

The Record extension functions 4mXRecordCreateContext24m and 4mXRecord-0m
4mRegisterClients24m 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 deliv-
ered_events, which also can be specified by a recording client;
delivered_events are actually delivered to one or more clients.



				1m20m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m


These event types are discussed in section 2.3 "Protocol Ranges".

The Record extension functions 4mXRecordCreateContext24m and 4mXRecord-0m
4mRegisterClients24m have the common arguments datum_flags, 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, respec-
tively.	 These are discussed in the following sections.

1m2.1.	Datum Flags0m

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 4mXRecordFromServerTime24m flag specifies that 4mXRecordIntercept-0m
4mData24m structures with a category of 4mXRecordFromServer24m will have a
server_time field specific to each protocol element.

The 4mXRecordFromClientTime24m flag specifies that 4mXRecordIntercept-0m
4mData24m structures with a category of 4mXRecordFromClient24m will have a
server_time field specific to each protocol element.

The 4mXRecordFromClientSequence24m flag specifies that 4mXRecord-0m
4mInterceptData24m structures with a category of 4mXRecordFromClient24m or
4mXRecordClientDied24m will have a valid client_seq field.

1m2.2.	Selecting Clients0m

The clients argument is a pointer to an array of 4mXRecord-0m
4mClientSpec24m.  4mXRecordClientSpec24m is an integral type that holds a
resource ID, a client resource ID base, or one of the 4mclient24m 4mset0m
constants defined below.

Duplicate elements in the array are ignored by the functions, and
if any element in the array is not valid, a 4mBadMatch24m error
results.  A resource ID references the client that created that
resource.  The client set may be one of the following constants:
4mXRecordCurrentClients24m, 4mXRecordFutureClients24m, or 4mXRecordAll-0m
4mClients24m.

If the element in the array identifies a particular client, pro-
tocol 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 section 3.4 "Data Transfer".

If the element is 4mXRecordCurrentClients24m, the protocol ranges
specified by the ranges argument, except for device_events, are
associated with each current client connection.	 If the element
is 4mXRecordFutureClients24m, the protocol ranges specified by the
ranges argument are associated with each new client connection.
If the element is 4mXRecordAllClients24m, the protocol ranges speci-
fied by the ranges argument are associated with each current



				1m30m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m


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, 4mXRecordCurrent-0m
4mClients24m and 4mXRecordAllClients24m silently exclude the recording data
connection.  It is an error to explicitly register the data con-
nection.

1m2.3.	Protocol Ranges0m

The functions 4mXRecordCreateContext24m and 4mXRecordRegisterClients0m
have another common argument, ranges, which is an array of point-
ers to 4mXRecordRange24m 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
4mXRecordRange24m structure must be allocated by the Record library
using the 4mXRecordAllocRange24m function.

The 4mXRecordRange24m typedef is a structure with the following mem-
bers:

__
|
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 4mXRecordRange24m members are defined as follows.
The 4mXRecordRange824m typedef is a structure with the following mem-
bers:

__
|
XRecordRange8:
     unsigned char first
     unsigned char last

|__

The 4mXRecordRange1624m typedef is a structure with the following mem-
bers:







				1m40m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m

__
|
XRecordRange16:
     unsigned short first
     unsigned short last

|__

The 4mXRecordExtRange24m typedef is a structure with the following
members:

__
|
XRecordExtRange:
     XRecordRange8 ext_major
     XRecordRange16 ext_minor

|__

If any of the values specified in 4mXRecordRange24m is invalid, a 4mBad-0m
4mValue24m 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
4mBadValue24m 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 4mBadValue24m 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 4mBadValue24m 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 4mBadValue0m
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



				1m50m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m


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 deliv-
ered 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 4mBadValue24m 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 4mBadValue24m error results if the value of first
is greater than the value of last.  A 4mBadValue24m 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 4mBadValue24m 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 4mTrue24m for the client_started member specifies the con-
nection setup reply from the server to new clients.  If 4mFalse24m,
the connection setup reply is not specified by this 4mXRecordRange24m.

A value of 4mTrue24m for the client_died member specifies notification
when a client disconnects.  If 4mFalse24m, notification when a client
disconnects is not specified by this 4mXRecordRange24m.

1m3.  Library Extension Requests0m

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 4mBadAlloc24m or 4mBadLength24m errors.

1m3.1.	Query Extension Version0m

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






				1m60m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m

__
|
Status
XRecordQueryVersion(Display *4mdisplay24m, int *4mcmajor_return24m, int *4mcminor_return24m)


4mdisplay24m   Specifies the connection to the X server.

4mcmajor_return0m
	  Returns the extension protocol major version in use.

4mcminor_return0m
	  Returns the extension protocol minor version in use.
|__

The 4mXRecordQueryVersion24m function returns the major and minor pro-
tocol version numbers supported by the server.	4mXRecordQuery-0m
4mVersion24m returns nonzero (success) only if the returned version
numbers are common to both the library and the server; otherwise,
it returns zero.

1m3.2.	Create and Modify Context0m

An application uses the 4mXRecordCreateContext24m 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 *4mdisplay24m, int 4mdatum_flags24m, XRecordClientSpec *4mclients24m, int 4mnclients24m,
		      XRecordRange **4mranges24m, int 4mnranges24m)


4mdisplay24m   Specifies the connection to the X server.

4mdatum_flags0m
	  Specifies whether detailed time or sequence info should
	  be sent.

4mclients24m   Specifies the clients to record.

4mnclients24m  Specifies the number of clients.

4mranges24m    Specifies the protocol ranges to record.

4mnranges24m   Specifies the number of protocol ranges.
|__

The 4mXRecordCreateContext24m function creates a record context and
returns an 4mXRecordContext24m, which is then used in the other Record
library calls.	This request is typically executed by the record-
ing client over its control connection to the X server.	 The
datum_flags specifies whether server time and/or client sequence



				1m70m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m


number should precede protocol elements recorded by context (see
section 2.1).  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 4mXRecordCurrentClients24m, 4mXRecordFutureClients24m,
or 4mXRecordAllClients24m, the actions described in section 2.2
"Selecting Clients" are performed.

4mXRecordCreateContext24m returns zero if the request failed.
4mXRecordCreateContext24m can generate 4mBadIDChoice24m, 4mBadMatch24m, and 4mBad-0m
4mValue24m errors.

The ranges argument is an 4mXRecordRange24m* array, that is, an array
of pointers.  The structures the elements point to shall be allo-
cated by calling 4mXRecordAllocRange24m.

__
|
XRecordRange *
XRecordAllocRange(void)

|__

The 4mXRecordAllocRange24m function allocates and returns an 4mXRecor-0m
4mdRange24m 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 4mXFree24m.

1m3.2.1.  Additions0m

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























				1m80m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m

__
|
Status
XRecordRegisterClients(Display *4mdisplay24m, XRecordContext 4mcontext24m, int 4mdatum_flags24m,
		XRecordClientSpec *4mclients24m, int 4mnclients24m, XRecordRange **4mranges24m, int 4mnranges24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to modify.

4mdatum_flags0m
	  Specifies whether detailed time or sequence info should
	  be sent.

4mclients24m   Specifies the clients to record.

4mnclients24m  Specifies the number of clients.

4mranges24m    Specifies the protocol ranges to record.

4mnranges24m   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 section 2.1).	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
4mXRecordCurrentClients24m, 4mXRecordFutureClients24m, or 4mXRecordAll-0m
4mClients24m, the actions described in section 2.2 "Selecting Clients"
are performed.

4mXRecordRegisterClients24m returns zero if the request failed; other-
wise, it returns nonzero.

4mXRecordRegisterClients24m can generate 4mXRecordBadContext24m, 4mBadMatch24m,
and 4mBadValue24m errors.

1m3.2.2.  Deletions0m

An application uses the 4mXRecordUnregisterClients24m function to
delete clients from a previously created record context, typi-
cally over its control connection to the X server.










				1m90m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m

__
|
Status
XRecordUnregisterClients(Display *4mdisplay24m, XRecordContext 4mcontext24m, RecordClientSpec *4mclients24m,
		  int 4mnclients24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to modify.

4mclients24m   Specifies the clients to stop recording.

4mnclients24m  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 per-
formed.

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

When the item is 4mXRecordFutureClients24m, any future client connec-
tions will not automatically be targeted for recording in con-
text.

When the element is 4mXRecordAllClients24m, all clients currently tar-
geted 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.

4mXRecordUnregisterClients24m returns zero if the request failed; oth-
erwise, it returns nonzero.

4mXRecordUnregisterClients24m can generate 4mXRecordBadContext24m, 4mBad-0m
4mMatch24m, and 4mBadValue24m errors.

1m3.3.	Query Context State0m

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










				1m100m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m

__
|
Status
XRecordGetContext(Display *4mdisplay24m, XRecordContext 4mcontext24m, XRecordState **4mstate_return24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to query.

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

The 4mXRecordState24m typedef returned by 4mXRecordGetContext24m 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
4mTrue24m when the recording client has asked that recorded data be
sent; otherwise it is 4mFalse24m.  The datum_flags member is set to
the value of these flags for this context.  The nclients member
is set to the number of 4mXRecordClientInfo24m structures returned.
The client_info member is an array of pointers to 4mXRecordCli-0m
4mentInfo24m structures that contain the protocol to record for each
targeted client.  The 4mXRecordClientInfo24m 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 record-
ing or is set to 4mXRecordFutureClients24m 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 4mXRecordRange24m structures, which specify the proto-
col ranges to record.



				1m110m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m


4mXRecordGetContext24m returns zero if the request failed; otherwise,
it returns nonzero.  The context argument must specify a valid
4mXRecordContext24m or a 4mXRecordBadContext24m error results.

Recording clients should use the 4mXRecordFreeState24m function to
free the state data returned by 4mXRecordGetContext24m.

__
|
void
XRecordFreeState(XRecordState *4mstate24m)


4mstate24m     Specifies the structure that is to be freed.
|__

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

1m3.4.	Data Transfer0m

An application uses the 4mXRecordEnableContext24m and 4mXRecordDisable-0m
4mContext24m 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.

1m3.4.1.  Enable Context0m

To direct the X server to record and report protocol, a program
uses 4mXRecordEnableContext24m, 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 4mXRecordInterceptData0m
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



				1m120m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m


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 pro-
tocol element was recorded, if this information were included in
the recorded data; otherwise client_seq is 0.  The category mem-
ber is set to one of the following values: 4mXRecordStartOfData24m,
4mXRecordFromServer24m, 4mXRecordFromClient24m, 4mXRecordClientStarted24m,
4mXRecordClientDied24m, or 4mXRecordEndOfData24m.  4mXRecordStartOfData24m is
immediately sent as the first reply to confirm that the context
is enabled.  4mXRecordFromClient24m indicates the protocol data is
from the recorded client to the server (requests).  4mXRecordFrom-0m
4mServer24m indicates the protocol data is from the server to the
recorded client (replies, errors, events, or device events).
4mXRecordClientStarted24m indicates that the protocol data is the con-
nection setup reply from the server.  4mXRecordClientDied24m indicates
that the recorded client has closed its connection to the X
server; there is no protocol data.  4mXRecordEndOfData24m 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 4mTrue24m if the byte order of the
client being recorded is swapped relative to the recording
client; otherwise, it is set to 4mFalse24m.  All recorded protocol
data is returned in the byte order of the recorded client.
Therefore, recording clients are responsible for all byte swap-
ping, if required.  Device events are in the byte order of the
recording client.  For replies of category 4mXRecordStartOfData24m and
4mXRecordEndOfData24m, 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 4mXRecordStartOfData24m, 4mXRecordClientDied24m, or
4mXRecordEndOfData24m, no protocol data are contained in data.

For the core X events 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, and 4mBut-0m
4mtonRelease24m, the fields of a device event that contain valid
information are time and detail.  For the core X event 4mMotionNo-0m
4mtify24m, 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 4mDeviceKeyPress24m,
4mDeviceKeyRelease24m, 4mDeviceButtonPress24m, and 4mDeviceButtonRelease24m, the
fields of a device event that contain valid information are
device, time, and detail.  For 4mDeviceMotionNotify24m, the valid
device event fields are device and time.  For the extension input
device events 4mProximityIn24m and 4mProximityOut24m, the fields of a



				1m130m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m


device event that contain valid information are device and time.
For the extension input device event 4mDeviceValuator24m, 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 4mXRecordInterceptProc24m is called
for each protocol element in the reply.

__
|
typedef void(*XRecordInterceptProc)
     (XPointer 4mclosure24m, XRecordInterceptData *4mrecorded_data24m)


4mclosure24m   Pointer that was passed in when the context was
	  enabled.

4mrecorded_data0m
	  A protocol element recorded by the server extension.
|__

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

Recording clients should use the 4mXRecordFreeData24m function to free
the 4mXRecordInterceptData24m structure.

__
|
Status
XRecordEnableContext(Display *4mdisplay24m, XRecordContext 4mcontext24m, XRecordInterceptProc 4mcallback24m,
		    XPointer 4mclosure24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to enable.

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

4mclosure24m   Specifies data passed to 4mcallback.0m
|__

4mXRecordEnableContext24m enables data transfer between the recording



				1m140m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m


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.

4mXRecordEnableContext24m returns zero if the request failed; other-
wise, it returns nonzero.  The context argument must specify a
valid 4mXRecordContext24m or a 4mXRecordBadContext24m error results.  The
error 4mBadMatch24m results when data transfer is already enabled on
the given context.

1m3.4.2.  Enable Context Asynchronously0m

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

This interface is defined as follows:

__
|
Status
XRecordEnableContextAsync(Display *4mdisplay24m, XRecordContext 4mcontext24m,
			   XRecordInterceptProc 4mcallback24m, XPointer 4mclosure24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to enable.

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

4mclosure24m   Data passed to 4mcallback24m.
|__

4mXRecordEnableContextAsync24m enables data transfer between the
recording client and the X server just as 4mXRecordEnableContext0m
does.  Unlike 4mXRecordEnableContext24m, it does not wait for the con-
text to be disabled before returning; 4mXRecordEnableContextAsync0m
returns as soon as the 4mXRecordStartOfData24m reply has been received
and processed.

4mXRecordEnableContextAsync24m returns zero if it could not allocate
the necessary memory and nonzero if it sent the request success-
fully to the server.  The context argument must specify a valid
4mXRecordContext24m or a 4mXRecordBadContext24m error results.	The error
4mBadMatch24m results when data transfer is already enabled.

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



				1m150m





1mX Record Extension Library, Version 1.13	   X11, Release 6.40m

__
|
void
XRecordProcessReplies(Display *4mdisplay24m)


4mdisplay24m	Specifies the connection to the X server.
|__

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


To free the data passed to the 4mXRecordInterceptProc24m callback, use
4mXRecordFreeData24m.

__
|
void
XRecordFreeData(XRecordInterceptData *4mdata24m)


4mdata24m      Specifies the structure that is to be freed.
|__

4mXRecordFreeData24m frees the data pointed to by data.	 If the argu-
ment does not match an 4mXRecordInterceptData24m pointer earlier
passed to an 4mXRecordInterceptProc24m callback or if 4mXRecordFreeData0m
has already been called with it, the behavior is undefined.

1m3.4.3.  Disable Context0m

To direct the X server to halt the reporting of recorded proto-
col, the program executes 4mXRecordDisableContext24m, typically over
its control connection to the X server.

__
|
Status
XRecordDisableContext(Display *4mdisplay24m, XRecordContext 4mcontext24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to disable.
|__

The 4mXRecordDisableContext24m function disables context, stopping all
recording over its data connection.  Any complete protocol ele-
ments for context that were buffered in the server will be sent
to the recording client rather than being discarded.  If a pro-
gram attempts to disable an 4mXRecordContext24m that has not been



				1m160m





1mX11, Release 6.4	   X Record Extension Library, Version 1.130m


enabled, no action will take place.

4mXRecordDisableContext24m returns zero if the request failed; other-
wise, it returns nonzero.  The context argument must specify a
valid 4mXRecordContext24m or an 4mXRecordBadContext24m error results.

1m3.5.	ID Base Mask0m

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

__
|
XID
XRecordIdBaseMask(Display *4mdisplay24m)


4mdisplay24m   Specifies the connection to the X server.
|__

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

1m3.6.	Free Context0m

Before terminating, the program should request that the server
free the record context.  This is done with the 4mXRecordFreeCon-0m
4mtext24m function, typically over the record client's control connec-
tion to the X server.

__
|
Status
XRecordFreeContext(Display *4mdisplay24m, XRecordContext 4mcontext24m)


4mdisplay24m   Specifies the connection to the X server.

4mcontext24m   Specifies the record context to free.
|__

The 4mXRecordFreeContext24m 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 4mXRecordDisableContext24m 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.

4mXRecordFreeContext24m returns zero if the request failed; other-
wise,it returns nonzero.  The context argument must specify a
valid 4mXRecordContext24m or a 4mXRecordBadContext24m error results.



				1m170m