Record Extension Protocol Specification

			Version 1.13

		   X Consortium Standard

		 X Version 11, Release 6.4






			Martha Zimet
	      Network Computing Devices, Inc.






			 edited by
		       Stephen Gildea
			X Consortium
















































Copyright (C) 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 (C) 1994, 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.









X11, Release 6.4	  Record Extension Protocol, Version 1.13


1.  Introduction

Several proposals have been written over the past few years that
address some of the issues surrounding the recording and playback
of user actions in the X Window System1:

o  Some Proposals for a Minimal X11 Testing Extension, Kieron
   Drake, UniSoft Ltd., April 1991

o  X11 Input Synthesis Extension Proposal, Larry Woestman,
   Hewlett Packard, November 1991

o  XTrap Architecture, Dick Annicchiario, et al, Digital Equip-
   ment Corporation, July 1991

o  XTest Extension Recording Specification, Yochanan Slonim, Mer-
   cury Interactive, December 1992

This document both unifies and extends the previous diverse
approaches to generate a proposal for an X extension that pro-
vides support for the recording of all core X protocol and arbi-
trary extension protocol.  Input synthesis, or playback, has
already been implemented in the XTest extension, an X Consortium
standard.  Therefore, this extension is limited to recording.

In order to provide both record and playback functionality, a
hypothetical record application could use this extension to cap-
ture both user actions and their consequences.	For example, a
button press (a user action) may cause a window to be mapped and
a corresponding MapNotify event to be sent (a consequence).  This
information could be stored for later use by a playback applica-
tion.

The playback application could use the recorded actions as input
for the XTest extension's XTestFakeInput operation to synthesize
the appropriate input events.  The "consequence" or synchroniza-
tion information is then used as a synchronization point during
playback.  That is, the playback application does not generate
specific synthesized events until their matching synchronization
condition occurs.  When the condition occurs the processing of
synthesized events continues.  Determination that the condition
has occurred may be made by capturing the consequences of the
synthesized events and comparing them to the previously recorded
synchronization information.  For example, if a button press was
followed by a MapNotify event on a particular window in the
recorded data, the playback application might synthesize the but-
ton press then wait for the MapNotify event on the appropriate
window before proceeding with subsequent synthesized input.

Because it is impossible to predict what synchronization informa-
tion will be required by a particular application, the extension
provides facilities to record any subset of core X protocol and
-----------
  1 X Window System is a trademark of X Consortium, Inc.



				1





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


arbitrary extension protocol.  As such, this extension does not
enforce a specific synchronization methodology; any method based
on information in the X protocol stream (e.g., watching for win-
dow mapping/unmapping, cursor changes, drawing of certain text
strings, etc.) can capture the information it needs using RECORD
facilities.

1.1.  Acknowledgements

The document represents the culmination of two years of debate
and experiments done under the auspices of the X Consortium xtest
working group.	Although this was a group effort, the author
remains responsible for any errors or omissions.  Two years ago,
Robert Chesler of Absol-puter, Kieron Drake of UniSoft Ltd., Marc
Evans of Synergytics and Ken Miller of Digitial shared the vision
of a standard extension for recording and were all instrumental
in the early protocol development.  During the last two years,
Bob Scheifler of the X Consortium and Jim Fulton of NCD continu-
ously provided input to the protocol design, as well as encour-
agement to the author.	In the last few months, Stephen Gildea
and Dave Wiggins, both X Consortium staff, have spent consider-
able time fine tuning the protocol design and reviewing the pro-
tocol specifications.  Most recently, Amnon Cohen of Mercury
Interactive has assisted in clarification of the recorded event
policy, and Kent Siefkes of Performance Awareness has assisted in
clarification of the timestamp policy.

1.2.  Goals


     o	To provide a standard for recording, whereby both device
	events and synchronization information in the form of
	device event consequences are recorded.

     o	To record contextual information used in synchronized
	playback without prior knowledge of the application that
	is being recorded.

     o	To provide the ability to record arbitrary X protocol
	extensions.

1.3.  Requirements

The extension should function as follows:

     o	It should not be dependent on other clients or extensions
	for its operation.

     o	It should not significantly impact performance.

     o	It should support the recording of all device input (core
	devices and XInput devices).





				2





X11, Release 6.4	  Record Extension Protocol, Version 1.13


     o	It should be extendible.

     o	It should support the recording of synchronization infor-
	mation for user events.


2.  Design

This section gives an overview of the RECORD extension and dis-
cusses its overall operation and data types.


2.1.  Overview

The mechanism used by this extension for recording is to inter-
cept core X protocol and arbitrary X extension protocol entirely
within the X server itself.  When the extension has been
requested to intercept specific protocol by one or more clients,
the protocol data are formatted and returned to the recording
clients.

The extension provides a mechanism for capturing all events,
including input device events that go to no clients, that is
analogous to a client expressing "interest" in all events in all
windows, including the root window.  Event filtering in the
extension provides a mechanism for feeding device events to
recording clients; it does not provide a mechanism for in-place,
synchronous event substitution, modification, or withholding.  In
addition, the extension does not provide data compression before
intercepted protocol is returned to the recording clients.

2.1.1.	Data Delivery

Because events are limited in size to 32 bytes, using events to
return intercepted protocol data to recording clients is pro-
hibitive in terms of performance.  Therefore, intercepted proto-
col data are returned to recording clients through multiple
replies to the extension request to begin protocol interception
and reporting.	This utilization is consistent with
ListFontsWithInfo, for example, where a single request has multi-
ple replies.

Individual requests, replies, events or errors intercepted by the
extension on behalf of recording clients cannot be split across
reply packets.	In order to reduce overhead, multiple intercepted
requests, replies, events and errors might be collected into a
single reply.  Nevertheless, all data are returned to the client
in a timely manner.

2.1.2.	Record Context

The extension adds a record context resource (RC) to the set of
resources managed by the server.  All the extension operations
take an RC as an argument.  Although the protocol permits sharing



				3





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


of RCs between clients, it is expected that clients will use
their own RCs.	The attributes used in extension operations are
stored in the RCs, and these attributes include the protocol and
clients to intercept.

The terms "register" and "unregister" are used to describe the
relationship between clients to intercept and the RC.  To regis-
ter a client with an RC means the client is added to the list of
clients to intercept; to unregister a client means the client is
deleted from the list of clients to intercept.	When the server
is requested to register or unregister clients from an RC, it is
required to do so immediately.	That is, it is not permissible
for the server to wait until recording is enabled to register
clients or recording is disabled to unregister clients.

2.1.3.	Record Client Connections

The typical communication model for a recording client is to open
two connections to the server and use one for RC control and the
other for reading protocol data.

The "control" connection can execute requests to obtain informa-
tion about the supported protocol version, create and destroy
RCs, specify protocol types to intercept and clients to be
recorded, query the current state of an RC, and to stop intercep-
tion and reporting of protocol data.  The "data" connection can
execute a request to enable interception and reporting of speci-
fied protocol for a particular RC.  When the "enable" request is
issued, intercepted protocol is sent back on the same connection,
generally in more than one reply packet.  Until the last reply to
the "enable" request is sent by the server, signifying that the
request execution is complete, no other requests will be executed
by the server on that connection.  That is, the connection that
data are being reported on cannot issue the "disable" request
until the last reply to the "enable" request is sent by the
server.  Therefore, unless a recording client never has the need
to disable the interception and reporting of protocol data, two
client connections are necessary.

2.1.4.	Events

The terms "delivered events" and "device events" are used to
describe the two event classes recording clients may select for
interception.  These event classes are handled differently by the
extension.  Delivered events are core X events or X extension
events the server actually delivers to one or more clients.
Device events are events generated by core X devices or extension
input devices that the server may or may not deliver to any
clients.  When device events are selected for interception by a
recording client, the extension guarantees each device event is
recorded and will be forwarded to the recording client in the
same order it is generated by the device.





				4





X11, Release 6.4	  Record Extension Protocol, Version 1.13


The recording of selected device events is not affected by server
grabs.	Delivered events, on the other hand, can be affected by
server grabs.  If a recording client selects both a device event
and delivered events that result from that device event, the
delivered events are recorded after the device event.  In the
absence of grabs, the delivered events for a device event precede
later device events.

Requests that have side effects on devices, such as WarpPointer
and GrabPointer with a confine-to window, will cause RECORD to
record an associated device event.  The XTEST extension request
XTestFakeInput causes a device event to be recorded; the device
events are recorded in the same order that the XTestFakeInput
requests are received by the server.

If a key autorepeats, multiple KeyPress and KeyRelease device
events are reported.

2.1.5.	Timing

Requests are recorded just before they are executed; the time
associated with a request is the server time when it is recorded.


2.2.  Types


The following new types are used in the request definitions that
appear in section 3.


RC:   CARD32


The RC type is a resource identifier for a server record context.


RANGE8:     [first, last:   CARD8]
RANGE16:    [first, last:   CARD16]
EXTRANGE:   [major:	    RANGE8
	    minor:	    RANGE16]



RECORDRANGE:   [core-requests:	   RANGE8
	       core-replies:	   RANGE8
	       ext-requests:	   EXTRANGE
	       ext-replies:	   EXTRANGE
	       delivered-events:   RANGE8
	       device-events:	   RANGE8
	       errors:		   RANGE8
	       client-started:	   BOOL
	       client-died:	   BOOL]




				5





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


The RECORDRANGE structure contains the protocol values to inter-
cept.  Typically, this structure is sent by recording clients
over the control connection when creating or modifying an RC.

core-requests
     Specifies core X protocol requests with an opcode field
     between first and last inclusive.	If first is equal to 0
     and last is equal to 0, no core requests are specified by
     this RECORDRANGE.	If first is greater than last, a Value
     error results.

core-replies
     Specifies replies resulting from core X protocol requests
     with an opcode field between first and last inclusive.  If
     first is equal to 0 and last is equal to 0, no core replies
     are specified by this RECORDRANGE.  If first is greater than
     last, a Value error results.

ext-requests
     Specifies extension protocol requests with a major opcode
     field between major.first and major.last and a minor opcode
     field between minor.first and minor.last inclusive.  If
     major.first and major.last are equal to 0, no extension pro-
     tocol requests are specified by this RECORDRANGE.	If
     major.first or major.last is less than 128 and greater than
     0, if major.first is greater than major.last, or if
     minor.first is greater than minor.last, a Value error
     results.

ext-replies
     Specifies replies resulting from extension protocol requests
     with a major opcode field between major.first and major.last
     and a minor opcode field between minor.first and minor.last
     inclusive.  If major.first and major.last are equal to 0, no
     extension protocol replies are specified by this RECORD-
     RANGE.  If major.first or major.last is less than 128 and
     greater than 0, if major.first is greater than major.last,
     or if minor.first is greater than minor.last, a Value error
     results.

delivered-events
     This is used for both core X protocol events and arbitrary
     extension events.	Specifies events that are delivered to at
     least one client that have a code field between first and
     last inclusive.  If first is equal to 0 and last is equal to
     0, no events are specified by this RECORDRANGE.  Otherwise,
     if first is less than 2 or last is less than 2, or if first
     is greater than last, a Value error results.

device-events
     This is used for both core X device events and X extension
     device events that may or may not be delivered to a client.
     Specifies device events that have a code field between first
     and last inclusive.  If first is equal to 0 and last is



				6





X11, Release 6.4	  Record Extension Protocol, Version 1.13


     equal to 0, no device events are specified by this RECORD-
     RANGE.  Otherwise, if first is less than 2 or last is less
     than 2, or if first is greater than last, a Value error
     results.

     Because the generated device event may or may not be associ-
     ated with a client, unlike other RECORDRANGE components,
     which select protocol for a specific client, selecting for
     device events in any RECORDRANGE in an RC causes the record-
     ing client to receive one instance for each device event
     generated that is in the range specified.

errors
     This is used for both core X protocol errors and arbitrary
     extension errors.	Specifies errors that have a code field
     between first and last inclusive.	If first is equal to 0
     and last is equal to 0, no errors are specified by this
     RECORDRANGE.  If first is greater than last, a Value error
     results.

client-started
     Specifies the connection setup reply.  If False, the connec-
     tion setup reply is not specified by this RECORDRANGE.

client-died
     Specifies notification when a client disconnects.	If False,
     notification when a client disconnects is not specified by
     this RECORDRANGE.


ELEMENT_HEADER:   [from-server-time:	  BOOL
		  from-client-time:	  BOOL
		  from-client-sequence:   BOOL]


The ELEMENT_HEADER structure specifies additional data that pre-
cedes each protocol element in the data field of a RecordEnable-
Context reply.

o  If from-server-time is True, each intercepted protocol element
   with category FromServer is preceded by the server time when
   the protocol was recorded.

o  If from-client-time is True, each intercepted protocol element
   with category FromClient is preceded by the server time when
   the protocol was recorded.

o  If from-client-sequence is True, each intercepted protocol
   element with category FromClient or ClientDied is preceded by
   the 32-bit sequence number of the recorded client's most
   recent request processed by the server at that time.  For
   FromClient, this will be one less than the sequence number of
   the following request.  For ClientDied, the sequence number
   will be the only data, because no protocol is recorded.



				7





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


Note that a reply containing device events is treated the same as
other replies with category FromServer for purposes of these
flags.	Protocol with category FromServer is never preceded by a
sequence number because almost all such protocol has a sequence
number in it anyway.

If both a server time and a sequence number have been requested
for a reply, each protocol request is preceded first by the time
and second by the sequence number.


XIDBASE:   CARD32


The XIDBASE type is used to identify a particular client.  Valid
values are any existing resource identifier of any connected
client, in which case the client that created the resource is
specified, or the resource identifier base sent to the target
client from the server in the connection setup reply.  A value of
0 (zero) is valid when the XIDBASE is associated with device
events that may not have been delivered to a client.


CLIENTSPEC:   XIDBASE or {CurrentClients, FutureClients, AllClients}


The CLIENTSPEC type defines the set of clients the RC attributes
are associated with.  This type is used by recording clients when
creating an RC or when changing RC attributes.	XIDBASE specifies
that the RC attributes apply to a single client only.  Current-
Clients specifies that the RC attributes apply to current client
connections; FutureClients specifies future client connections;
AllClients specifies all client connections, which includes cur-
rent and future.

The numeric values for CurrentClients, FutureClients and All-
Clients are defined such that there will be no intersection with
valid XIDBASEs.

When the context is enabled, the data connection is unregistered
if it was registered.  If the context is enabled, CurrentClients
and AllClients silently exclude the recording data connection.
It is an error to explicitly register the data connection.


CLIENT_INFO:   [client-resource:       CLIENTSPEC
	       intercepted-protocol:   LISTofRECORDRANGE]


This structure specifies an intercepted client and the protocol
to be intercepted for the client.  The client-resource field is a
resource base that identifies the intercepted client.  The inter-
cepted-protocol field specifies the protocol to intercept for the
client-resource.



				8





X11, Release 6.4	  Record Extension Protocol, Version 1.13


2.3.  Errors


RecordContext
     This error is returned if the value for an RC argument in a
     request does not name a defined record context.


3.  Protocol Requests


RecordQueryVersion

     major-version, minor-version: CARD16

->

     major-version, minor-version: CARD16

This request specifies the RECORD extension protocol version the
client would like to use.  When the specified protocol version is
supported by the extension, the protocol version the server
expects from the client is returned.  Clients must use this
request before other RECORD extension requests.

This request also determines whether or not the RECORD extension
protocol version specified by the client is supported by the
extension.  If the extension supports the version specified by
the client, this version number should be returned.  If the
client has requested a higher version than is supported by the
server, the server's highest version should be returned.  Other-
wise, if the client has requested a lower version than is sup-
ported by the server, the server's lowest version should be
returned.  This document defines major version one (1), minor
version thirteen (13).

RecordCreateContext

     context: RC

     element-header: ELEMENT_HEADER

     client-specifiers: LISTofCLIENTSPEC

     ranges: LISTofRECORDRANGE

     Errors: Match, Value, IDChoice, Alloc

This request creates a new record context within the server and
assigns the identifier context to it.  After the context is cre-
ated, this request registers the set of clients in client-speci-
fiers with the context and specifies the protocol to intercept
for those clients.  The recorded protocol elements will be pre-
ceded by data as specified by element-header.  Typically, this



				9





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


request is used by a recording client over the control connec-
tion.  Multiple RC objects can exist simultaneously, containing
overlapping sets of protocol and clients to intercept.

If any of the values in element-header or ranges is invalid, a
Value error results.  Duplicate items in the list of client-spec-
ifiers are ignored.  If any item in the client-specifiers list is
not a valid CLIENTSPEC, a Match error results.	Otherwise, each
item in the client-specifiers list is processed as follows:

o  If the item is an XIDBASE identifying a particular client, the
   specified client is registered with the context and the proto-
   col to intercept for the client is then set to ranges.

o  If the item is CurrentClients, all existing clients are regis-
   tered with the context at this time.  The protocol to inter-
   cept for all clients registered with the context is then set
   to ranges.

o  If the item is FutureClients, all clients that connect to the
   server after this request executes will be automatically reg-
   istered with the context.  The protocol to intercept for such
   clients will be set to ranges in the context.

o  If the item is AllClients, the effect is as if the actions
   described for FutureClients are performed, followed by the
   actions for CurrentClients.

The Alloc error results when the server is unable to allocate the
necessary resources.


RecordRegisterClients

     context: RC

     element-header: ELEMENT_HEADER

     client-specifiers: LISTofCLIENTSPEC

     ranges: LISTofRECORDRANGE

     Errors: Match, Value, RecordContext, Alloc

This request registers the set of clients in client-specifiers
with the given context and specifies the protocol to intercept
for those clients.  The header preceding each recorded protocol
element is set as specified by element-header.	These flags
affect the entire context; their effect is not limited to the
clients registered by this request.  Typically, this request is
used by a recording client over the control connection.

If context does not name a valid RC, a RecordContext error
results.  If any of the values in element-header or ranges is



				10





X11, Release 6.4	  Record Extension Protocol, Version 1.13


invalid, a Value error results.  Duplicate items in the list of
client-specifiers are ignored.	If any item in the list of
client-specifiers is not a valid CLIENTSPEC, a Match error
results.  If the context is enabled and the XID of the enabling
connection is specified, a Match error results.  Otherwise, each
item in the client-specifiers list is processed as follows:

o  If the item is an XIDBASE identifying a particular client, the
   specified client is registered with the context if it is not
   already registered.	The protocol to intercept for the client
   is then set to ranges.

o  If the item is CurrentClients, all existing clients that are
   not already registered with the specified context, except the
   enabling connection if the context is enabled, are registered
   at this time.  The protocol to intercept for all clients reg-
   istered with the context is then set to ranges.

o  If the item is FutureClients, all clients that connect to the
   server after this request executes will be automatically reg-
   istered with the context.  The protocol to intercept for such
   clients will be set to ranges in the context.  The set of
   clients that are registered with the context and their corre-
   sponding sets of protocol to intercept are left intact.

o  If the item is AllClients, the effect is as if the actions
   described for FutureClients are performed, followed by the
   actions for CurrentClients.

The Alloc error results when the server is unable to allocate the
necessary resources.


RecordUnregisterClients

     context: RC

     client-specifiers: LISTofCLIENTSPEC

     Errors: Match, RecordContext

This request removes the set of clients in client-specifiers from
the given context's set of registered clients.	Typically, this
request is used by a recording client over the control connec-
tion.

If context does not name a valid RC, a RecordContext error
results.  Duplicate items in the list of client-specifiers are
ignored.  If any item in the list is not a valid CLIENTSPEC, a
Match error results.  Otherwise, each item in the client-speci-
fiers list is processed as follows:

o  If the item is an XIDBASE identifying a particular client, and
   the specified client is currently registered with the context,



				11





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


   it is unregistered, and the set of protocol to intercept for
   the client is deleted from the context.  If the specified
   client is not registered with the context, the item has no
   effect.

o  If the item is CurrentClients, all clients currently regis-
   tered with the context are unregistered from it, and their
   corresponding sets of protocol to intercept are deleted from
   the context.

o  If the item is FutureClients, clients that connect to the
   server after this request executes will not automatically be
   registered with the context.  The set of clients that are reg-
   istered with this context and their corresponding sets of pro-
   tocol that will be intercepted are left intact.

o  If the item is AllClients, the effect is as if the actions
   described for FutureClients are performed, followed by the
   actions for CurrentClients.

A client is unregistered automatically when it disconnects.


RecordGetContext

     context: RC

->

     enabled: BOOL

     element-header: ELEMENT_HEADER

     intercepted-clients: LISTofCLIENT_INFO

     Errors: RecordContext

This request queries the current state of the specified context
and is typically used by a recording client over the control con-
nection.  The enabled field specifies the state of data transfer
between the extension and the recording client, and is either
enabled (True) or disabled (False).  The initial state is dis-
abled.	When enabled, all core X protocol and extension protocol
received from (requests) or sent to (replies, errors, events) a
particular client, and requested to be intercepted by the record-
ing client, is reported to the recording client over the data
connection.  The element-header specifies the header that pre-
cedes each recorded protocol element.  The intercepted-clients
field specifies the list of clients currently being recorded and
the protocol associated with each client.  If future clients will
be automatically registered with the context, one of the returned
CLIENT_INFO structures has a client-resource value of Future-
Clients and an intercepted-protocol giving the protocol to inter-
cept for future clients.  Protocol ranges may be decomposed,



				12





X11, Release 6.4	  Record Extension Protocol, Version 1.13


coalesced, or otherwise modified by the server from how they were
specified by the client.  All CLIENTSPECs registered with the
server are returned, even if the RECORDRANGE(s) associated with
them specify no protocol to record.

When the context argument is not valid, a RecordContext error
results.


RecordEnableContext

     context: RC

->+

     category: {FromServer, FromClient, ClientStarted, Client-
     Died, StartOfData, EndOfData}

     element-header: ELEMENT_HEADER

     client-swapped: BOOL

     id-base: XIDBASE

     server-time: TIMESTAMP

     recorded-sequence-number: CARD32

     data: LISTofBYTE

     Errors: Match, RecordContext

This request enables data transfer between the recording client
and the extension and returns the protocol data the recording
client has previously expressed interest in.  Typically, this
request is executed by the recording client over the data connec-
tion.

If the client is registered on the context, it is unregistered
before any recording begins.

Once the server receives this request, it begins intercepting and
reporting to the recording client all core and extension protocol
received from or sent to clients registered with the RC that the
recording client has expressed interest in.  All intercepted pro-
tocol data is returned in the byte-order of the recorded client.
Therefore, recording clients are responsible for all byte swap-
ping, if required.  More than one recording client cannot enable
data transfer on the same RC at the same time.	Multiple inter-
cepted requests, replies, events and errors might be packaged
into a single reply before being returned to the recording
clients.





				13





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


The category field determines the possible types of the data.
When a context is enabled, the server will immediately send a
reply of category StartOfData to notify the client that recording
is enabled.  A category of FromClient means the data are from the
client (requests); FromServer means data are from the server
(replies, errors, events, or device events).  For a new client,
the category is ClientStarted and the data are the connection
setup reply.  When the recorded client connection is closed, cat-
egory is set to the value ClientDied and no protocol is included
in this reply.	When the disable request is made over the control
connection, a final reply is sent over the data connection with
category EndOfData and no protocol.

The element-header field returns the value currently set for the
context, which tells what header information precedes each
recorded protocol element in this reply.

The client-swapped field is True if the byte order of the proto-
col being recorded is swapped relative to the recording client;
otherwise, client-swapped is False.  The recorded protocol is in
the byte order of the client being recorded; device events are in
the byte order of the recording client.  For replies of category
StartOfData and EndOfData the client-swapped bit is set according
to the byte order of the server relative to the recording client.
The id-base field is the resource identifier base sent to the
client from the server in the connection setup reply, and hence,
identifies the client being recorded.  The id-base field is 0
(zero) when the protocol data being returned are device events.
The server-time field is set to the time of the server when the
first protocol element in this reply was intercepted.  The
server-time of reply N+1 is greater than or equal to the server-
time of reply N, and is greater than or equal to the time of the
last protocol element in reply N.

The recorded-sequence-number field is set to the sequence number
of the recorded client's most recent request processed by the
server.

The data field contains the raw protocol data being returned to
the recording client.  If requested by the element-header of this
record context, each protocol element may be preceded by a 32-bit
timestamp and/or a 32-bit sequence number.  If present, both the
timestamp and sequence number are always in the byte order of the
recording client.

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



				14





X11, Release 6.4	  Record Extension Protocol, Version 1.13


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 error Match is returned when data transfer is already
enabled.  When the context argument is not valid, a RecordContext
error results.


RecordDisableContext

     context: RC

     Errors: RecordContext

This request is typically executed by the recording client over
the control connection.  This request directs the extension to
immediately send any complete protocol elements currently
buffered, to send a final reply with category EndOfData, and to
discontinue data transfer between the extension and the recording
client.  Protocol reporting is disabled on the data connection
that is currently enabled for the given context.  Once the exten-
sion completes processing this request, no additional recorded
protocol will be reported to the recording client.  If a data
connection is not currently enabled when this request is exe-
cuted, then this request has no affect on the state of data
transfer.  An RC is disabled automatically when the connection to
the enabling client is closed down.

When the context argument is not valid, a RecordContext error
results.


RecordFreeContext

     context : RC

     Errors: RecordContext

This request deletes the association between the resource ID and
the RC and destroys the RC.  If a client has enabled data trans-
fer on this context, the actions described in RecordDisable-
Context are performed before the context is freed.

An RC is destroyed automatically when the connection to the cre-
ating client is closed down and the close-down mode is Destroy-
All.  When the context argument is not valid, a RecordContext
error results.



				15





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


4.  Encoding

Please refer to the X11 Protocol Encoding document as this docu-
ment uses conventions established there.

The name of this extension is "RECORD".


4.1.  Types

RC: CARD32


RANGE8
  1	  CARD8 	      first
  1	  CARD8 	      last



RANGE16
  2	  CARD16	      first
  2	  CARD16	      last



EXTRANGE
  2	  RANGE8	      major
  4	  RANGE16	      minor



RECORDRANGE
  2	  RANGE8	      core-requests
  2	  RANGE8	      core-replies
  6	  EXTRANGE	      ext-requests
  6	  EXTRANGE	      ext-replies
  2	  RANGE8	      delivered-events
  2	  RANGE8	      device-events
  2	  RANGE8	      errors
  1	  BOOL		      client-started
  1	  BOOL		      client-died



ELEMENT_HEADER
  1	  CARD8
	  0x01	    from-server-time
	  0x02	    from-client-time
	  0x04	    from-client-sequence


XIDBASE: CARD32





				16





X11, Release 6.4	  Record Extension Protocol, Version 1.13


CLIENTSPEC
  4	  XIDBASE	      client-id-base
	  1	    CurrentClients
	  2	    FutureClients
	  3	    AllClients



CLIENT_INFO
  4	  CLIENTSPEC	      client-resource
  4	  CARD32	      n, number of record ranges in intercepted-protocol
  24n	  LISTofRECORDRANGE   intercepted-protocol


4.2.  Errors


RecordContext
  1	  0		      Error
  1	  CARD8 	      extension's base error code + 0
  2	  CARD16	      sequence number
  4	  CARD32	      invalid record context
  24			      unused


4.3.  Requests


RecordQueryVersion
  1	  CARD8 	      major opcode
  1	  0		      minor opcode
  2	  2		      request length
  2	  CARD16	      major version
  2	  CARD16	      minor version
 =>
  1	  1		      Reply
  1			      unused
  2	  CARD16	      sequence number
  4	  0		      reply length
  2	  CARD16	      major version
  2	  CARD16	      minor version
  20			      unused















				17





Record Extension Protocol, Version 1.13 	 X11, Release 6.4


RecordCreateContext
  1	  CARD8 	      major opcode
  1	  1		      minor opcode
  2	  5+m+6n	      request length
  4	  RC		      context
  1	  ELEMENT_HEADER      element-header
  3			      unused
  4	  CARD32	      m, number of client-specifiers
  4	  CARD32	      n, number of ranges
  4m	  LISTofCLIENTSPEC    client-specifiers
  24n	  LISTofRECORDRANGE   ranges



RecordRegisterClients
  1	  CARD8 	      major opcode
  1	  2		      minor opcode
  2	  5+m+6n	      request length
  4	  RC		      context
  1	  ELEMENT_HEADER      element-header
  3			      unused
  4	  CARD32	      m, number of client-specifiers
  4	  CARD32	      n, number of ranges
  4m	  LISTofCLIENTSPEC    client-specifiers
  24n	  LISTofRECORDRANGE   ranges



RecordUnregisterClients
  1	  CARD8 	      major opcode
  1	  3		      minor opcode
  2	  3+m		      request length
  4	  RC		      context
  4	  CARD32	      m, number of client-specifiers
  4m	  LISTofCLIENTSPEC    client-specifiers



RecordGetContext
  1	  CARD8 	      major opcode
  1	  4		      minor opcode
  2	  2		      request length
  4	  RC		      context
 =>
  1	  1		      Reply
  1	  BOOL		      enabled
  2	  CARD16	      sequence number
  4	  j		      reply length
  1	  ELEMENT_HEADER      element-header
  3			      unused
  4	  CARD32	      n, number of intercepted-clients
  16			      unused
  4j	  LISTofCLIENT_INFO   intercepted-clients




				18





X11, Release 6.4	  Record Extension Protocol, Version 1.13


RecordEnableContext
  1	  CARD8 	      major opcode
  1	  5		      minor opcode
  2	  2		      request length
  4	  RC		      context
 =>+
  1	  1		      Reply
  1			      category
	  0	    FromServer
	  1	    FromClient
	  2	    ClientStarted
	  3	    ClientDied
	  4	    StartOfData
	  5	    EndOfData
  2	  CARD16	      sequence number
  4	  n		      reply length
  1	  ELEMENT_HEADER      element-header
  1	  BOOL		      client-swapped
  2			      unused
  4	  XIDBASE	      id-base
  4	  TIMESTAMP	      server-time
  4	  CARD32	      recorded-sequence-number
  8			      unused
  4n	  BYTE		      data



RecordDisableContext
  1	  CARD8 	      major opcode
  1	  6		      minor opcode
  2	  2		      request length
  4	  RC		      context



RecordFreeContext
  1	  CARD8 	      major opcode
  1	  7		      minor opcode
  2	  2		      request length
  4	  RC		      context

















				19