1510 lines
53 KiB
XML
1510 lines
53 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
|
||
[
|
||
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
|
||
]>
|
||
|
||
|
||
<!-- lifted from troff+ms+XMan by doclifter -->
|
||
<book id="recordlib">
|
||
|
||
<bookinfo>
|
||
<title>X Record Extension Library</title>
|
||
<subtitle>X Consortium Standard</subtitle>
|
||
<releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
|
||
<releaseinfo>Version 1.13</releaseinfo>
|
||
<authorgroup>
|
||
<author>
|
||
<firstname>Martha</firstname><surname>Zimet</surname>
|
||
<affiliation><orgname>Network Computing Devices, Inc.</orgname></affiliation>
|
||
</author>
|
||
<editor>
|
||
<firstname>Stephen</firstname><surname>Gildea</surname>
|
||
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||
</editor>
|
||
</authorgroup>
|
||
<copyright><year>1994</year><holder>Network Computing Devices, Inc.</holder></copyright>
|
||
|
||
<legalnotice>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</legalnotice>
|
||
|
||
<legalnotice>
|
||
<para role="multiLicensing">Copyright © 1995 X Consortium</para>
|
||
<para>
|
||
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:
|
||
</para>
|
||
<para>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.
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>X Window System is a trademark of The Open Group.</para>
|
||
</legalnotice>
|
||
</bookinfo>
|
||
|
||
<chapter id='Record_Extension_Overview'>
|
||
<title>Record Extension Overview</title>
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<sect1 id='Synchronous_Playback'>
|
||
<title>Synchronous Playback</title>
|
||
<para>
|
||
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
|
||
<function>MotionNotify</function>, <function>ButtonPress</function>,
|
||
and <function>ButtonRelease</function> 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
|
||
<function>ImageText8</function> and <function>PolyLine</function> to the
|
||
X server, or the X server could send non-device events such as
|
||
<function>Expose</function> and <function>MapNotify</function> 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)
|
||
</para>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id='Design_Approach'>
|
||
<title>Design Approach</title>
|
||
<para>
|
||
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.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id='Record_Clients'>
|
||
<title>Record Clients</title>
|
||
<para>
|
||
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.
|
||
</para>
|
||
<para>
|
||
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 <function>XRecordContext</function>). 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.
|
||
</para>
|
||
<para>
|
||
A client that wishes to record X protocol does so through the library
|
||
functions defined in
|
||
<xref linkend='Library_Extension_Requests' xrefstyle='select: title'/>
|
||
A typical sequence of requests that a client would make is as follows:
|
||
</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/>
|
||
</para>
|
||
<para>
|
||
query the extension protocol version.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
</para>
|
||
<para>
|
||
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 <function>XRecord-Context</function>, which is an XID that is
|
||
used by most other extension requests to identify the specified context.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
</para>
|
||
<para>
|
||
begin the recording and reporting of protocol data.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
</para>
|
||
<para>
|
||
end the recording and reporting of protocol data.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<xref linkend='XRecordFreeContext' xrefstyle='select: title'/>
|
||
</para>
|
||
<para>
|
||
free the record context.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>
|
||
The header for this library is
|
||
<<function>X11/extensions/record.h</function>>. All identifiers defined
|
||
in the interface are supplied by this header and are prefixed with "XRecord".
|
||
The <function>Xtst</function> library contains the
|
||
<function>XRecord</function> functions.
|
||
</para>
|
||
|
||
</sect1>
|
||
</chapter>
|
||
|
||
<chapter id='Common_Arguments'>
|
||
<title>Common Arguments</title>
|
||
<para>
|
||
The Record extension functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
and <xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> allow applications to
|
||
specify the following:
|
||
</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
Individual clients or sets of clients to record
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Ranges of core X protocol and X extension protocol to record for each client
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
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
|
||
<xref linkend='Protocol_Ranges' xrefstyle='select: title'/>
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The Record extension functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
and <xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> 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,
|
||
respectively. These are discussed in the following sections.
|
||
</para>
|
||
|
||
<sect1 id='Datum_Flags'>
|
||
<title>Datum Flags</title>
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
The <function>XRecordFromServerTime</function> flag specifies that
|
||
<function>XRecordInterceptData</function> structures with a category of
|
||
<function>XRecordFromServer</function> will have a server_time field specific to each
|
||
protocol element.
|
||
</para>
|
||
|
||
<para>
|
||
The <function>XRecordFromClientTime</function> flag specifies that
|
||
<function>XRecordInterceptData</function> structures with a category of
|
||
<function>XRecordFromClient</function> will have a server_time field specific
|
||
to each protocol element.
|
||
</para>
|
||
|
||
<para>
|
||
The <function>XRecordFromClientSequence</function> flag specifies that
|
||
<function>XRecordInterceptData</function> structures with a category of
|
||
<function>XRecordFromClient</function> or
|
||
<function>XRecordClientDied</function> will have a valid client_seq field.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id='Selecting_Clients'>
|
||
<title>Selecting Clients</title>
|
||
|
||
<para>
|
||
The clients argument is a pointer to an array of
|
||
<function>XRecordClientSpec</function>.
|
||
<function>XRecordClientSpec</function> is an integral type that holds a
|
||
resource ID, a client resource ID base, or one of the client set constants
|
||
defined below.
|
||
</para>
|
||
<para>
|
||
Duplicate elements in the array are ignored by the functions, and if any
|
||
element in the array is not valid, a
|
||
<function>BadMatch</function>
|
||
error results. A resource ID references the client that created that
|
||
resource. The client set may be one of the following constants:
|
||
<function>XRecordCurrentClients</function>,
|
||
<function>XRecordFutureClients</function>, or
|
||
<function>XRecordAllClients</function>.
|
||
</para>
|
||
<para>
|
||
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
|
||
<xref linkend='Data_Transfer' xrefstyle='select: title'/>
|
||
</para>
|
||
<para>
|
||
If the element is <function>XRecordCurrentClients</function>, the protocol
|
||
ranges specified by the ranges argument, except for device_events, are
|
||
associated with each current client connection. If the element is
|
||
<function>XRecordFutureClients</function>, the
|
||
protocol ranges specified by the ranges argument are associated with each new
|
||
client connection. If the element is
|
||
<function>XRecordAllClients</function>,
|
||
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,
|
||
<function>XRecordCurrentClients</function> and
|
||
<function>XRecordAllClients</function>
|
||
silently exclude the recording data connection. It is an error to explicitly
|
||
register the data connection.
|
||
</para>
|
||
</sect1>
|
||
<sect1 id='Protocol_Ranges'>
|
||
<title>Protocol Ranges</title>
|
||
|
||
<para>
|
||
The functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> and
|
||
<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> have another common argument,
|
||
ranges, which is an array of pointers to <function>XRecordRange</function>
|
||
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 <function>XRecordRange</function> structure must be
|
||
allocated by the Record library using the
|
||
<function>XRecordAllocRange</function> function.
|
||
</para>
|
||
<para>
|
||
The <function>XRecordRange</function> typedef is a structure with the
|
||
following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
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 */
|
||
</literallayout>
|
||
|
||
<para>
|
||
The types used in
|
||
<function>XRecordRange</function>
|
||
members are defined as follows. The
|
||
<function>XRecordRange8</function>
|
||
typedef is a structure with the following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
XRecordRange8:
|
||
unsigned char first
|
||
unsigned char last
|
||
</literallayout>
|
||
|
||
<para>
|
||
The
|
||
<function>XRecordRange16</function>
|
||
typedef is a structure with the following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
XRecordRange16:
|
||
unsigned short first
|
||
unsigned short last
|
||
</literallayout>
|
||
|
||
<para>
|
||
The
|
||
<function>XRecordExtRange</function>
|
||
typedef is a structure with the following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
XRecordExtRange:
|
||
XRecordRange8 ext_major
|
||
XRecordRange16 ext_minor
|
||
</literallayout>
|
||
|
||
<para>
|
||
If any of the values specified in
|
||
<function>XRecordRange</function>
|
||
is invalid, a
|
||
<function>BadValue</function>
|
||
error results.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
error results if the value of first is greater than the value of last. A
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>BadValue</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
A value of
|
||
<function>True</function>
|
||
for the client_started member specifies the
|
||
connection setup reply from the server to new clients. If
|
||
<function>False</function>
|
||
the connection setup reply is not specified by this
|
||
<function>XRecordRange</function>
|
||
</para>
|
||
|
||
<para>
|
||
A value of
|
||
<function>True</function>
|
||
for the client_died member specifies
|
||
notification when a client disconnects. If
|
||
<function>False</function>
|
||
notification when a client disconnects is not specified by this
|
||
<function>XRecordRange</function>
|
||
</para>
|
||
</sect1>
|
||
</chapter>
|
||
|
||
<chapter id='Library_Extension_Requests'>
|
||
<title>Library Extension Requests</title>
|
||
|
||
<para>
|
||
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
|
||
<function>BadAlloc</function>
|
||
or
|
||
<function>BadLength</function>
|
||
errors.
|
||
</para>
|
||
|
||
<sect1 id='Query_Extension_Version'>
|
||
<title>Query Extension Version</title>
|
||
|
||
<para>
|
||
An application uses the
|
||
<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/>
|
||
function to determine
|
||
the version of the Record extension protocol supported by an X server.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordQueryVersion'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordQueryVersion</function></funcdef>
|
||
<paramdef>Display <parameter> *display</parameter></paramdef>
|
||
<paramdef>int <parameter> cmajor_return</parameter></paramdef>
|
||
<paramdef>int <parameter> cminor_return</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Returns the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>cmajor_return</emphasis></term>
|
||
<listitem><para>Returns the extension protocol major version in use.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>cminor_return</emphasis></term>
|
||
<listitem><para>Returns the extension protocol minor version in use.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/>
|
||
function returns the major and minor protocol version numbers supported by
|
||
the server.
|
||
<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/>
|
||
returns nonzero (success) only if the returned version numbers are
|
||
common to both the library and the server; otherwise, it returns zero.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id='Create_and_Modify_Context'>
|
||
<title>Create and Modify Context</title>
|
||
|
||
<para>
|
||
An application uses the
|
||
<xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
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.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordCreateContext'>
|
||
<funcprototype>
|
||
<funcdef>XRecordContext <function>XRecordCreateContext</function></funcdef>
|
||
<paramdef>Display <parameter> *display</parameter></paramdef>
|
||
<paramdef>int <parameter> datum_flags</parameter></paramdef>
|
||
<paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef>
|
||
<paramdef>int <parameter> nclients</parameter></paramdef>
|
||
<paramdef>XRecordRange <parameter> *ranges</parameter></paramdef>
|
||
<paramdef>int <parameter> nranges</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Returns the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>datum_flags</emphasis></term>
|
||
<listitem><para>Specifies whether detailed time or sequence info should be sent.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>clients</emphasis></term>
|
||
<listitem><para>Specifies the clients to record.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>nclients</emphasis></term>
|
||
<listitem><para>Specifies the number of clients.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>ranges</emphasis></term>
|
||
<listitem><para>Specifies the protocol ranges to record.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>nranges</emphasis></term>
|
||
<listitem><para>Specifies the number of protocol ranges.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
function creates a record context and returns an
|
||
<function>XRecordContext</function>
|
||
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 (
|
||
<xref linkend='Datum_Flags' xrefstyle='select: title'/>
|
||
). 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
|
||
<function>XRecordCurrentClients</function>
|
||
<function>XRecordFutureClients</function>
|
||
or
|
||
<function>XRecordAllClients</function>
|
||
the actions described in
|
||
<xref linkend='Selecting_Clients' xrefstyle='select: title'/>
|
||
are performed.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
returns zero if the request failed.
|
||
<xref linkend='XRecordCreateContext' xrefstyle='select: title'/>
|
||
can generate
|
||
<function>BadIDChoice</function>
|
||
<function>BadMatch</function>
|
||
and
|
||
<function>BadValue</function>
|
||
errors.
|
||
</para>
|
||
|
||
<para>The ranges argument is an
|
||
<function>XRecordRange</function>
|
||
array, that is, an array
|
||
of pointers. The structures the elements point to shall be allocated
|
||
by calling
|
||
<function>XRecordAllocRange</function></para>
|
||
|
||
<literallayout remap='FD'>
|
||
XRecordRange *
|
||
XRecordAllocRange(void)
|
||
</literallayout> <!-- remap='FN' -->
|
||
|
||
<para>
|
||
The
|
||
<function>XRecordAllocRange</function>
|
||
function
|
||
allocates and returns an
|
||
<function>XRecordRange</function>
|
||
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
|
||
<olink targetdoc='libX11' targetptr='XFree'><function>XFree</function></olink>
|
||
</para>
|
||
|
||
<sect2 id='Additions'>
|
||
<title>Additions</title>
|
||
|
||
<para>
|
||
An application uses the
|
||
<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/>
|
||
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.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordRegisterClients'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordRegisterClients</function></funcdef>
|
||
<paramdef>Display <parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext <parameter> context</parameter></paramdef>
|
||
<paramdef>int <parameter> datum_flags</parameter></paramdef>
|
||
<paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef>
|
||
<paramdef>int <parameter> nclients</parameter></paramdef>
|
||
<paramdef>XRecordRange <parameter> *ranges</parameter></paramdef>
|
||
<paramdef>int <parameter> nranges</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Returns the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to modify.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>datum_flags</emphasis></term>
|
||
<listitem><para>Specifies whether detailed time or sequence info should be sent.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>clients</emphasis></term>
|
||
<listitem><para>Specifies the clients to record.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>nclients</emphasis></term>
|
||
<listitem><para>Specifies the number of clients.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>ranges</emphasis></term>
|
||
<listitem><para>Specifies the protocol ranges to record.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>nranges</emphasis></term>
|
||
<listitem><para>Specifies the number of protocol ranges.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The datum_flags specifies whether server time and/or client sequence number
|
||
should precede protocol elements for all clients recorded by context (See
|
||
<xref linkend='Datum_Flags' xrefstyle='select: title'/>
|
||
). 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
|
||
<function>XRecordCurrentClients</function>
|
||
<function>XRecordFutureClients</function>
|
||
or
|
||
<function>XRecordAllClients</function>
|
||
the actions described in
|
||
<xref linkend='Selecting_Clients' xrefstyle='select: title'/>
|
||
are performed.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/>
|
||
returns zero if the request failed; otherwise, it
|
||
returns nonzero.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/>
|
||
can generate
|
||
<function>XRecordBadContext</function>
|
||
<function>BadMatch</function>
|
||
and
|
||
<function>BadValue</function>
|
||
errors.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id='Deletions'>
|
||
<title>Deletions</title>
|
||
|
||
<para>
|
||
An application uses the
|
||
<function>XRecordUnregisterClients</function>
|
||
function to delete clients from a previously created
|
||
record context, typically over its control connection to the X server.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordUnRegisterClients'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordUnRegisterClients</function></funcdef>
|
||
<paramdef>Display <parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext <parameter> context</parameter></paramdef>
|
||
<paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef>
|
||
<paramdef>int <parameter> nclients</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Returns the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to modify.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>clients</emphasis></term>
|
||
<listitem><para>Specifies the clients to stop recording.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>nclients</emphasis></term>
|
||
<listitem><para>Specifies the number of clients.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
When the element is
|
||
<function>XRecordCurrentClients</function>
|
||
all clients currently targeted for recording in context and their
|
||
corresponding sets of protocol to record are deleted from context.
|
||
</para>
|
||
|
||
<para>
|
||
When the item is
|
||
<function>XRecordFutureClients</function>
|
||
any future client connections will not automatically be targeted for
|
||
recording in context.
|
||
</para>
|
||
|
||
<para>
|
||
When the element is
|
||
<function>XRecordAllClients</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
<function>XRecordUnregisterClients</function>
|
||
returns zero if the request failed; otherwise, it returns nonzero.
|
||
</para>
|
||
|
||
<para>
|
||
<function>XRecordUnregisterClients</function>
|
||
can generate
|
||
<function>XRecordBadContext</function>
|
||
<function>BadMatch</function>
|
||
and
|
||
<function>BadValue</function>
|
||
errors.</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id='Query_Context_State'>
|
||
<title>Query Context State</title>
|
||
|
||
<para>
|
||
An application uses the
|
||
<xref linkend='XRecordGetContext' xrefstyle='select: title'/>
|
||
function to query the current state of a record context, typically over
|
||
its control connection to the X server.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordGetContext'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordGetContext</function></funcdef>
|
||
<paramdef>Display <parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext <parameter> context</parameter></paramdef>
|
||
<paramdef>XRecordState <parameter> **state_return</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to query.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>state_return</emphasis></term>
|
||
<listitem><para>Specifies the address of a variable into which
|
||
the function stores a pointer to the current state of the record context.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<function>XRecordState</function>
|
||
typedef returned by
|
||
<xref linkend='XRecordGetContext' xrefstyle='select: title'/>
|
||
is a structure with the following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
XRecordState:
|
||
Bool enabled
|
||
int datum_flags
|
||
unsigned long nclients
|
||
XRecordClientInfo **client_info
|
||
</literallayout>
|
||
|
||
<para>
|
||
The enabled member is set to the state of data transfer and is
|
||
<function>True</function>
|
||
when the recording client has asked that recorded data be sent;
|
||
otherwise it is
|
||
<function>False</function>
|
||
The datum_flags member is set to the value of these flags for this context.
|
||
The nclients member is set to the number of
|
||
<function>XRecordClientInfo</function>
|
||
structures returned. The client_info member is an array of pointers to
|
||
<function>XRecordClientInfo</function>
|
||
structures that contain the protocol to record for each targeted client. The
|
||
<function>XRecordClientInfo</function>
|
||
typedef is a structure with the following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
XRecordClientInfo:
|
||
XRecordClientSpec client
|
||
unsigned long nranges
|
||
XRecordRange **ranges
|
||
</literallayout>
|
||
|
||
<para>
|
||
The client member either identifies a client targeted for recording
|
||
or is set to
|
||
<function>XRecordFutureClients</function>
|
||
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
|
||
<function>XRecordRange</function>
|
||
structures, which specify the protocol ranges to record.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordGetContext' xrefstyle='select: title'/>
|
||
returns zero if the request failed; otherwise, it returns nonzero.
|
||
The context argument must specify a valid
|
||
<function>XRecordContext</function>
|
||
or a
|
||
<function>XRecordBadContext</function>
|
||
error results.
|
||
</para>
|
||
|
||
<para>
|
||
Recording clients should use the
|
||
<xref linkend='XRecordFreeState' xrefstyle='select: title'/>
|
||
function to free the state data returned by
|
||
<xref linkend='XRecordGetContext' xrefstyle='select: title'/>
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordFreeState'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XRecordFreeState</function></funcdef>
|
||
<paramdef>XRecordState <parameter> *state</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>state</emphasis></term>
|
||
<listitem><para>Specifies the structure that is to be freed.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XRecordFreeState' xrefstyle='select: title'/>
|
||
frees the data pointed to by state. If the argument does not match an
|
||
<function>XRecordState</function>
|
||
pointer returned from a successful call to
|
||
<xref linkend='XRecordGetContext' xrefstyle='select: title'/>
|
||
or if
|
||
<xref linkend='XRecordFreeState' xrefstyle='select: title'/>
|
||
has already been called with it, the behavior is undefined.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id='Data_Transfer'>
|
||
<title>Data Transfer</title>
|
||
|
||
<para>
|
||
An application uses the
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
and
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
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.
|
||
</para>
|
||
|
||
<sect2 id='Enable_Context'>
|
||
<title>Enable Context</title>
|
||
|
||
<para>
|
||
To direct the X server to record and report protocol, a program uses
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
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
|
||
<function>XRecordInterceptData</function>
|
||
typedef, a structure with the following members:
|
||
</para>
|
||
|
||
<literallayout remap='Ds'>
|
||
XRecordInterceptData:
|
||
XID id_base
|
||
Time server_time
|
||
unsigned long client_seq
|
||
int category
|
||
Bool client_swapped
|
||
unsigned char *data
|
||
unsigned long data_len
|
||
</literallayout>
|
||
|
||
<para>
|
||
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:
|
||
<function>XRecordStartOfData</function>
|
||
<function>XRecordFromServer</function>
|
||
<function>XRecordFromClient</function>
|
||
<function>XRecordClientStarted</function>
|
||
<function>XRecordClientDied</function>
|
||
or
|
||
<function>XRecordEndOfData</function>
|
||
<function>XRecordStartOfData</function>
|
||
is immediately sent as the first reply to confirm that the context is enabled.
|
||
<function>XRecordFromClient</function>
|
||
indicates the protocol
|
||
data is from the recorded client to the server (requests).
|
||
<function>XRecordFromServer</function>
|
||
indicates the protocol data is from the server to the recorded client
|
||
(replies, errors, events, or device events).
|
||
<function>XRecordClientStarted</function>
|
||
indicates that the protocol data is the connection setup reply from the server.
|
||
<function>XRecordClientDied</function>
|
||
indicates that the recorded client has closed its connection
|
||
to the X server; there is no protocol data.
|
||
<function>XRecordEndOfData</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
The client_swapped member is set to
|
||
<function>True</function>
|
||
if the byte order of the client being recorded is swapped relative to
|
||
the recording client; otherwise, it is set to
|
||
<function>False</function>
|
||
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
|
||
<function>XRecordStartOfData</function>
|
||
and
|
||
<function>XRecordEndOfData</function>
|
||
client_swapped is set according
|
||
to the byte order of the server relative to the recording client.
|
||
</para>
|
||
|
||
<para>
|
||
The data member contains the actual recorded protocol data.
|
||
When category is set to
|
||
<function>XRecordStartOfData</function>
|
||
<function>XRecordClientDied</function>
|
||
or
|
||
<function>XRecordEndOfData</function>
|
||
no protocol data are contained in data.
|
||
</para>
|
||
|
||
|
||
<!-- copied exactly from the protocol document -->
|
||
<para>
|
||
For the core X events
|
||
<function>KeyPress</function>
|
||
<function>KeyRelease</function>
|
||
<function>ButtonPress</function>
|
||
and
|
||
<function>ButtonRelease</function>,
|
||
the fields of a device event that contain
|
||
valid information are time and detail. For the core X event
|
||
<function>MotionNotify</function>
|
||
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.
|
||
</para>
|
||
|
||
<para>For the extension input device events
|
||
<function>DeviceKeyPress</function>
|
||
<function>DeviceKeyRelease</function>
|
||
<function>DeviceButtonPress</function>
|
||
and
|
||
<function>DeviceButtonRelease</function>
|
||
the fields of a device event that contain valid information are
|
||
device, time, and detail. For
|
||
<function>DeviceMotionNotify</function>
|
||
the valid device event fields are device and time.
|
||
For the extension input device events
|
||
<function>ProximityIn</function>
|
||
and
|
||
<function>ProximityOut</function>
|
||
the fields of a device event that contain valid
|
||
information are device and time. For the extension input device event
|
||
<function>DeviceValuator</function>
|
||
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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
The data_len member is set to the length of the actual recorded protocol
|
||
data in 4-byte units.
|
||
</para>
|
||
|
||
<para>
|
||
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
|
||
<function>XRecordInterceptProc</function>
|
||
is called for each protocol element in the reply.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordInterceptProc'>
|
||
<funcprototype>
|
||
<funcdef>typedef void <function>(*XRecordInterceptProc)</function></funcdef>
|
||
<paramdef>XPointer<parameter> closure</parameter></paramdef>
|
||
<paramdef>XRecordInterceptData<parameter> *recorded_data</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>closure</emphasis></term>
|
||
<listitem><para>Pointer that was passed in when the context was enabled.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>recorded_data</emphasis></term>
|
||
<listitem><para>A protocol element recorded by the server extension.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
This callback may use the control display connection (or any display
|
||
connection other than the data connection).
|
||
</para>
|
||
|
||
<para>
|
||
Recording clients should use the
|
||
<xref linkend='XRecordFreeData' xrefstyle='select: title'/>
|
||
function to free the
|
||
<function>XRecordInterceptData</function>
|
||
structure.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordEnableContext'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordEnableContext</function></funcdef>
|
||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext<parameter> context</parameter></paramdef>
|
||
<paramdef>XRecordInterceptProc<parameter> callback</parameter></paramdef>
|
||
<paramdef>XPointer<parameter> closure</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to enable.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>callback</emphasis></term>
|
||
<listitem><para>Specifies the function to be called for each protocol element received.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>closure</emphasis></term>
|
||
<listitem><para>Specifies data passed to callback.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
|
||
<para>
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
returns zero if the request failed; otherwise, it
|
||
returns nonzero. The context argument must specify a valid
|
||
<function>XRecordContext</function>
|
||
or a
|
||
<function>XRecordBadContext</function>
|
||
error results. The error
|
||
<function>BadMatch</function>
|
||
results when data transfer is already enabled on the given context.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id='Enable_Context_Asynchronously'>
|
||
<title>Enable Context Asynchronously</title>
|
||
|
||
<para>Because
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
does not return until
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
is executed on the control connection, a nonblocking interface in
|
||
addition to
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
is provided. This interface also
|
||
enables data transfer; however, it does not block.
|
||
</para>
|
||
|
||
<para>
|
||
This interface is defined as follows:
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordEnableContextAsync'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordEnableContextAsync</function></funcdef>
|
||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext<parameter> context</parameter></paramdef>
|
||
<paramdef>XRecordInterceptProc<parameter> callback</parameter></paramdef>
|
||
<paramdef>XPointer<parameter> closure</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to enable.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>callback</emphasis></term>
|
||
<listitem><para>Specifies the function to be called for each protocol element received.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>closure</emphasis></term>
|
||
<listitem><para>Specifies data passed to callback.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/>
|
||
enables data transfer between the recording
|
||
client and the X server just as
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
does. Unlike
|
||
<xref linkend='XRecordEnableContext' xrefstyle='select: title'/>
|
||
it does not wait for the context to be disabled
|
||
before returning;
|
||
<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/>
|
||
returns as soon as the
|
||
<function>XRecordStartOfData</function>
|
||
reply has been received and processed.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/>
|
||
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
|
||
<function>XRecordContext</function>
|
||
or a
|
||
<function>XRecordBadContext</function>
|
||
error results. The error
|
||
<function>BadMatch</function>
|
||
results when data transfer is already enabled.
|
||
</para>
|
||
|
||
<para>
|
||
Each time it reads data from the server connection, Xlib will check
|
||
for incoming replies and call <emphasis remap='I'>callback</emphasis>
|
||
as necessary. The application may direct Xlib explicitly to check
|
||
for Record data with the
|
||
<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/>
|
||
function.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordProcessReplies'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XRecordProcessReplies</function></funcdef>
|
||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/>
|
||
will check for any replies that have not yet
|
||
been processed by the application. The asynchronous callback will be called
|
||
as appropriate.
|
||
<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/>
|
||
returns when all immediately
|
||
available replies have been processed. It does not block.
|
||
</para>
|
||
|
||
<para>To free the data passed to the
|
||
<function>XRecordInterceptProc</function>
|
||
callback, use
|
||
<xref linkend='XRecordFreeData' xrefstyle='select: title'/></para>
|
||
|
||
<funcsynopsis id='XRecordFreeData'>
|
||
<funcprototype>
|
||
<funcdef>void <function>XRecordFreeData</function></funcdef>
|
||
<paramdef>XRecordInterceptData<parameter> *data</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>data</emphasis></term>
|
||
<listitem><para>Specifies the structure that is to be freed.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
|
||
<para>
|
||
<xref linkend='XRecordFreeData' xrefstyle='select: title'/>
|
||
frees the data pointed to by data. If the argument does not match an
|
||
<function>XRecordInterceptData</function>
|
||
pointer earlier passed to an
|
||
<function>XRecordInterceptProc</function>
|
||
callback or if
|
||
<xref linkend='XRecordFreeData' xrefstyle='select: title'/>
|
||
has already been called with it, the behavior is undefined.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id='Disable_Context'>
|
||
<title>Disable Context</title>
|
||
|
||
<para>
|
||
To direct the X server to halt the reporting of recorded protocol, the
|
||
program executes
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
typically over its control connection to the X server.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordDisableContext'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordDisableContext</function></funcdef>
|
||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext<parameter> context</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to disable.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
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
|
||
<function>XRecordContext</function>
|
||
that has not been enabled, no action will take place.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
returns zero if the request failed; otherwise, it
|
||
returns nonzero. The context argument must specify a valid
|
||
<function>XRecordContext</function>
|
||
or an
|
||
<function>XRecordBadContext</function>
|
||
error results.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id='ID_Base_Mask'>
|
||
<title>ID Base Mask</title>
|
||
|
||
<para>
|
||
To determine the mask the server uses for the client ID base, use
|
||
<xref linkend='XRecordIdBaseMask' xrefstyle='select: title'/></para>
|
||
|
||
<funcsynopsis id='XRecordIdBaseMask'>
|
||
<funcprototype>
|
||
<funcdef>XID <function>XRecordIdBaseMask</function></funcdef>
|
||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XRecordIdBaseMask' xrefstyle='select: title'/>
|
||
function returns the resource ID mask passed to the client by the
|
||
server at connection setup.
|
||
</para>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id='Free_Context'>
|
||
<title>Free Context</title>
|
||
|
||
<para>
|
||
Before terminating, the program should request that the server
|
||
free the record context. This is done with the
|
||
<xref linkend='XRecordFreeContext' xrefstyle='select: title'/>
|
||
function, typically over the record client's control connection
|
||
to the X server.
|
||
</para>
|
||
|
||
<funcsynopsis id='XRecordFreeContext'>
|
||
<funcprototype>
|
||
<funcdef>Status <function>XRecordFreeContext</function></funcdef>
|
||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||
<paramdef>XRecordContext<parameter> context</parameter></paramdef>
|
||
</funcprototype>
|
||
</funcsynopsis>
|
||
|
||
<variablelist remap='IP'>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>display</emphasis></term>
|
||
<listitem><para>Specifies the connection to the X server.</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><emphasis remap='I'>context</emphasis></term>
|
||
<listitem><para>Specifies the record context to free.</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>
|
||
The
|
||
<xref linkend='XRecordFreeContext' xrefstyle='select: title'/>
|
||
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
|
||
<xref linkend='XRecordDisableContext' xrefstyle='select: title'/>
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend='XRecordFreeContext' xrefstyle='select: title'/>
|
||
returns zero if the request failed; otherwise,it
|
||
returns nonzero. The context argument must specify a valid
|
||
<function>XRecordContext</function>
|
||
or a
|
||
<function>XRecordBadContext</function>
|
||
error results.
|
||
</para>
|
||
|
||
</sect1>
|
||
</chapter>
|
||
</book>
|