1517 lines
51 KiB
XML
1517 lines
51 KiB
XML
|
<?xml version="1.0" encoding="UTF-8" ?>
|
|||
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|||
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- 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 6.7</releaseinfo>
|
|||
|
|
<authorgroup>
|
|||
|
|
<author>
|
|||
|
|
<firstname>Martha</firstname><surname>Zimet</surname>
|
|||
|
|
</author>
|
|||
|
|
</authorgroup>
|
|||
|
|
<corpname>Network Computing Devices, Inc.</corpname>
|
|||
|
|
<copyright><year>1994</year><holder>Network Computing Devices, Inc.</holder></copyright>
|
|||
|
|
<copyright><year>1995</year><holder>X Consortium</holder></copyright>
|
|||
|
|
<releaseinfo>Version 1.13</releaseinfo>
|
|||
|
|
<affiliation><orgname>X Consortium</orgname></affiliation>
|
|||
|
|
<productnumber>X Version 11, Release 6.7</productnumber>
|
|||
|
|
<editor>
|
|||
|
|
<firstname>Stephen</firstname><surname>Gildea</surname>
|
|||
|
|
<affiliation><orgname>X Consortium</orgname></affiliation>
|
|||
|
|
</editor>
|
|||
|
|
|
|||
|
|
<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>
|
|||
|
|
|
|||
|
|
<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
|
|||
|
|
<link linkend="library_extension_requests">
|
|||
|
|
<xref linkend="library_extension_requests"></xref></link>
|
|||
|
|
A typical sequence of requests that a client would make is as follows:
|
|||
|
|
</para>
|
|||
|
|
<itemizedlist>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordQueryVersion</function>
|
|||
|
|
</para>
|
|||
|
|
<para>
|
|||
|
|
query the extension protocol version.
|
|||
|
|
</para>
|
|||
|
|
</listitem>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordCreateContext</function>
|
|||
|
|
</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>
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
</para>
|
|||
|
|
<para>
|
|||
|
|
begin the recording and reporting of protocol data.
|
|||
|
|
</para>
|
|||
|
|
</listitem>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
</para>
|
|||
|
|
<para>
|
|||
|
|
end the recording and reporting of protocol data.
|
|||
|
|
</para>
|
|||
|
|
</listitem>
|
|||
|
|
<listitem>
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordFreeContext</function>
|
|||
|
|
</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 <function>XRecordCreateContext</function>
|
|||
|
|
and <function>XRecordRegisterClients</function> 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
|
|||
|
|
<link linkend="protocol_ranges">
|
|||
|
|
<xref linkend="protocol_ranges"></xref></link>
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
The Record extension functions <function>XRecordCreateContext</function>
|
|||
|
|
and <function>XRecordRegisterClients</function> 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
|
|||
|
|
<link linkend="data_transfer">
|
|||
|
|
<xref linkend="data_transfer"></xref></link>
|
|||
|
|
</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 <function>XRecordCreateContext</function> and
|
|||
|
|
<function>XRecordRegisterClients</function> 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
|
|||
|
|
<function>XRecordQueryVersion</function>
|
|||
|
|
function to determine
|
|||
|
|
the version of the Record extension protocol supported by an X server.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordQueryVersion</function>
|
|||
|
|
function returns the major and minor protocol version numbers supported by
|
|||
|
|
the server.
|
|||
|
|
<function>XRecordQueryVersion</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordCreateContext</function>
|
|||
|
|
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>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordCreateContext</function>
|
|||
|
|
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 (
|
|||
|
|
<link linkend="datum_flags">
|
|||
|
|
<xref linkend="datum_flags"></xref></link>
|
|||
|
|
). 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
|
|||
|
|
<link linkend="selecting_clients">
|
|||
|
|
<xref linkend="selecting_clients"></xref></link>
|
|||
|
|
are performed.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordCreateContext</function>
|
|||
|
|
returns zero if the request failed.
|
|||
|
|
<function>XRecordCreateContext</function>
|
|||
|
|
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
|
|||
|
|
<function>XFree</function>
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<sect2 id='additions'>
|
|||
|
|
<title>Additions</title>
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
An application uses the
|
|||
|
|
<function>XRecordRegisterClients</function>
|
|||
|
|
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>
|
|||
|
|
<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
|
|||
|
|
<link linkend="datum_flags">
|
|||
|
|
<xref linkend="datum_flags"></xref></link>
|
|||
|
|
). 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
|
|||
|
|
<link linkend="selecting_clients">
|
|||
|
|
<xref linkend="selecting_clients"></xref></link>
|
|||
|
|
are performed.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordRegisterClients</function>
|
|||
|
|
returns zero if the request failed; otherwise, it
|
|||
|
|
returns nonzero.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordRegisterClients</function>
|
|||
|
|
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>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordGetContext</function>
|
|||
|
|
function to query the current state of a record context, typically over
|
|||
|
|
its control connection to the X server.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordGetContext</function>
|
|||
|
|
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>
|
|||
|
|
<function>XRecordGetContext</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordFreeState</function>
|
|||
|
|
function to free the state data returned by
|
|||
|
|
<function>XRecordGetContext</function>
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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>
|
|||
|
|
<function>XRecordFreeState</function>
|
|||
|
|
frees the data pointed to by state. If the argument does not match an
|
|||
|
|
<function>XRecordState</function>
|
|||
|
|
pointer returned from a successful call to
|
|||
|
|
<function>XRecordGetContext</function>
|
|||
|
|
or if
|
|||
|
|
<function>XRecordFreeState</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
and
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
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>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordFreeData</function>
|
|||
|
|
function to free the
|
|||
|
|
<function>XRecordInterceptData</function>
|
|||
|
|
structure.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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>
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
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>
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
does not return until
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
is executed on the control connection, a nonblocking interface in
|
|||
|
|
addition to
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
is provided. This interface also
|
|||
|
|
enables data transfer; however, it does not block.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
This interface is defined as follows:
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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>
|
|||
|
|
<function>XRecordEnableContextAsync</function>
|
|||
|
|
enables data transfer between the recording
|
|||
|
|
client and the X server just as
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
does. Unlike
|
|||
|
|
<function>XRecordEnableContext</function>
|
|||
|
|
it does not wait for the context to be disabled
|
|||
|
|
before returning;
|
|||
|
|
<function>XRecordEnableContextAsync</function>
|
|||
|
|
returns as soon as the
|
|||
|
|
<function>XRecordStartOfData</function>
|
|||
|
|
reply has been received and processed.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<para>
|
|||
|
|
<function>XRecordEnableContextAsync</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordProcessReplies</function>
|
|||
|
|
function.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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>
|
|||
|
|
<function>XRecordProcessReplies</function>
|
|||
|
|
will check for any replies that have not yet
|
|||
|
|
been processed by the application. The asynchronous callback will be called
|
|||
|
|
as appropriate.
|
|||
|
|
<function>XRecordProcessReplies</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordFreeData</function></para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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>
|
|||
|
|
<function>XRecordFreeData</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordFreeData</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
typically over its control connection to the X server.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
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>
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordIdBaseMask</function></para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordIdBaseMask</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordFreeContext</function>
|
|||
|
|
function, typically over the record client's control connection
|
|||
|
|
to the X server.
|
|||
|
|
</para>
|
|||
|
|
|
|||
|
|
<funcsynopsis>
|
|||
|
|
<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
|
|||
|
|
<function>XRecordFreeContext</function>
|
|||
|
|
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
|
|||
|
|
<function>XRecordDisableContext</function>
|
|||
|
|
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>
|
|||
|
|
<function>XRecordFreeContext</function>
|
|||
|
|
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>
|