Your IP : 216.73.216.48
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>X Record Extension Library</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><style xmlns="" type="text/css">/*
* Copyright (c) 2011 Gaetan Nadon
* Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice (including the next
* paragraph) shall be included in all copies or substantial portions of the
* Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS 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.
*/
/*
* Shared stylesheet for X.Org documentation translated to HTML format
* http://www.sagehill.net/docbookxsl/UsingCSS.html
* http://www.w3schools.com/css/default.asp
* https://addons.mozilla.org/en-US/firefox/addon/web-developer/developers
* https://addons.mozilla.org/en-US/firefox/addon/font-finder/
*/
/*
* The sans-serif fonts are considered more legible on a computer screen
* http://dry.sailingissues.com/linux-equivalents-verdana-arial.html
*
*/
body {
font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
/* In support of using "em" font size unit, the w3c recommended method */
font-size: 100%;
}
/*
* Selection: all elements requiring mono spaced fonts.
*
* The family names attempt to match the proportionally spaced font
* family names such that the same font name is used for both.
* We'd like to use Bitstream, for example, in both proportionally and
* mono spaced font text.
*/
.command,
.errorcode,
.errorname,
.errortype,
.filename,
.funcsynopsis,
.function,
.parameter,
.programlisting,
.property,
.screen,
.structname,
.symbol,
.synopsis,
.type
{
font-family: "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
}
/*
* Books have a title page, a preface, some chapters and appendices,
* a glossary, an index and a bibliography, in that order.
*
* An Article has no preface and no chapters. It has sections, appendices,
* a glossary, an index and a bibliography.
*/
/*
* Selection: book main title and subtitle
*/
div.book>div.titlepage h1.title,
div.book>div.titlepage h2.subtitle {
text-align: center;
}
/*
* Selection: article main title and subtitle
*/
div.article>div.titlepage h2.title,
div.article>div.titlepage h3.subtitle,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title {
text-align: center;
}
/*
* Selection: various types of authors and collaborators, individuals or corporate
*
* These authors are not always contained inside an authorgroup.
* They can be contained inside a lot of different parent types where they might
* not be centered.
* Reducing the margin at the bottom makes a visual separation between authors
* We specify here the ones on the title page, others may be added based on merit.
*/
div.titlepage .authorgroup,
div.titlepage .author,
div.titlepage .collab,
div.titlepage .corpauthor,
div.titlepage .corpcredit,
div.titlepage .editor,
div.titlepage .othercredit {
text-align: center;
margin-bottom: 0.25em;
}
/*
* Selection: the affiliation of various types of authors and collaborators,
* individuals or corporate.
*/
div.titlepage .affiliation {
text-align: center;
}
/*
* Selection: product release information (X Version 11, Release 7)
*
* The releaseinfo element can be contained inside a lot of different parent
* types where it might not be centered.
* We specify here the one on the title page, others may be added based on merit.
*/
div.titlepage p.releaseinfo {
font-weight: bold;
text-align: center;
}
/*
* Selection: publishing date
*/
div.titlepage .pubdate {
text-align: center;
}
/*
* The legal notices are displayed in smaller sized fonts
* Justification is only supported in IE and therefore not requested.
*
*/
.legalnotice {
font-size: small;
font-style: italic;
}
/*
* For documentation having multiple licenses, the copyright and legalnotice
* elements sequence cannot instantiated multiple times.
* The copyright notice and license text are therefore coded inside a legalnotice
* element. The role attribute on the paragraph is used to allow styling of the
* copyright notice text which should not be italicized.
*/
p.multiLicensing {
font-style: normal;
font-size: medium;
}
/*
* Selection: book or article main ToC title
* A paragraph is generated for the title rather than a level 2 heading.
* We do not want to select chapters sub table of contents, only the main one
*/
div.book>div.toc>p,
div.article>div.toc>p {
font-size: 1.5em;
text-align: center;
}
/*
* Selection: major sections of a book or an article
*
* Unlike books, articles do not have a titlepage element for appendix.
* Using the selector "div.titlepage h2.title" would be too general.
*/
div.book>div.preface>div.titlepage h2.title,
div.book>div.chapter>div.titlepage h2.title,
div.article>div.sect1>div.titlepage h2.title,
div.article>div.section>div.titlepage h2.title,
div.book>div.appendix>div.titlepage h2.title,
div.article>div.appendix h2.title,
div.glossary>div.titlepage h2.title,
div.index>div.titlepage h2.title,
div.bibliography>div.titlepage h2.title {
/* Add a border top over the major parts, just like printed books */
/* The Gray color is already used for the ruler over the main ToC. */
border-top-style: solid;
border-top-width: 2px;
border-top-color: Gray;
/* Put some space between the border and the title */
padding-top: 0.2em;
text-align: center;
}
/*
* A Screen is a verbatim environment for displaying text that the user might
* see on a computer terminal. It is often used to display the results of a command.
*
* http://www.css3.info/preview/rounded-border/
*/
.screen {
background: #e0ffff;
border-width: 1px;
border-style: solid;
border-color: #B0C4DE;
border-radius: 1.0em;
/* Browser's vendor properties prior to CSS 3 */
-moz-border-radius: 1.0em;
-webkit-border-radius: 1.0em;
-khtml-border-radius: 1.0em;
margin-left: 1.0em;
margin-right: 1.0em;
padding: 0.5em;
}
/*
* Emphasis program listings with a light shade of gray similar to what
* DocBook XSL guide does: http://www.sagehill.net/docbookxsl/ProgramListings.html
* Found many C API docs on the web using like shades of gray.
*/
.programlisting {
background: #F4F4F4;
border-width: 1px;
border-style: solid;
border-color: Gray;
padding: 0.5em;
}
/*
* Emphasis functions synopsis using a darker shade of gray.
* Add a border such that it stands out more.
* Set the padding so the text does not touch the border.
*/
.funcsynopsis, .synopsis {
background: #e6e6fa;
border-width: 1px;
border-style: solid;
border-color: Gray;
clear: both;
margin: 0.5em;
padding: 0.25em;
}
/*
* Selection: paragraphs inside synopsis
*
* Removes the default browser margin, let the container set the padding.
* Paragraphs are not always used in synopsis
*/
.funcsynopsis p,
.synopsis p {
margin: 0;
padding: 0;
}
/*
* Selection: variable lists, informal tables and tables
*
* Note the parameter name "variablelist.as.table" in xorg-xhtml.xsl
* A table with rows and columns is constructed inside div.variablelist
*
* Set the left margin so it is indented to the right
* Display informal tables with single line borders
*/
table {
margin-left: 0.5em;
border-collapse: collapse;
}
/*
* Selection: paragraphs inside tables
*
* Removes the default browser margin, let the container set the padding.
* Paragraphs are not always used in tables
*/
td p {
margin: 0;
padding: 0;
}
/*
* Add some space between the left and right column.
* The vertical alignment helps the reader associate a term
* with a multi-line definition.
*/
td, th {
padding-left: 1.0em;
padding-right: 1.0em;
vertical-align: top;
}
.warning {
border: 1px solid red;
background: #FFFF66;
padding-left: 0.5em;
}
</style></head><body><div class="book"><div class="titlepage"><div><div><h1 class="title"><a id="recordlib"></a>X Record Extension Library</h1></div><div><h2 class="subtitle">X Consortium Standard</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Martha</span> <span class="surname">Zimet</span></h3><div class="affiliation"><span class="orgname">Network Computing Devices, Inc.<br /></span></div></div><div class="editor"><h4 class="editedby">Edited by</h4><h3 class="editor"><span class="firstname">Stephen</span> <span class="surname">Gildea</span></h3><div class="affiliation"><span class="orgname">X Consortium<br /></span></div></div></div></div><div><p class="releaseinfo">X Version 11, Release 7.7</p></div><div><p class="releaseinfo">Version 1.13</p></div><div><p class="copyright">Copyright © 1994 Network Computing Devices, Inc.</p></div><div><div class="legalnotice"><a id="idm139752150504672"></a><p>
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.
</p></div></div><div><div class="legalnotice"><a id="idm139752152126096"></a><p class="multiLicensing">Copyright © 1995 X Consortium</p><p>
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:
</p><p>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.
</p><p>
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.
</p><p>X Window System is a trademark of The Open Group.</p></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="#Record_Extension_Overview">1. Record Extension Overview</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Synchronous_Playback">Synchronous Playback</a></span></dt><dt><span class="sect1"><a href="#Design_Approach">Design Approach</a></span></dt><dt><span class="sect1"><a href="#Record_Clients">Record Clients</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Common_Arguments">2. Common Arguments</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Datum_Flags">Datum Flags</a></span></dt><dt><span class="sect1"><a href="#Selecting_Clients">Selecting Clients</a></span></dt><dt><span class="sect1"><a href="#Protocol_Ranges">Protocol Ranges</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Library_Extension_Requests">3. Library Extension Requests</a></span></dt><dd><dl><dt><span class="sect1"><a href="#Query_Extension_Version">Query Extension Version</a></span></dt><dt><span class="sect1"><a href="#Create_and_Modify_Context">Create and Modify Context</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Additions">Additions</a></span></dt><dt><span class="sect2"><a href="#Deletions">Deletions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Query_Context_State">Query Context State</a></span></dt><dt><span class="sect1"><a href="#Data_Transfer">Data Transfer</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Enable_Context">Enable Context</a></span></dt><dt><span class="sect2"><a href="#Enable_Context_Asynchronously">Enable Context Asynchronously</a></span></dt><dt><span class="sect2"><a href="#Disable_Context">Disable Context</a></span></dt></dl></dd><dt><span class="sect1"><a href="#ID_Base_Mask">ID Base Mask</a></span></dt><dt><span class="sect1"><a href="#Free_Context">Free Context</a></span></dt></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Record_Extension_Overview"></a>Chapter 1. Record Extension Overview</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Synchronous_Playback">Synchronous Playback</a></span></dt><dt><span class="sect1"><a href="#Design_Approach">Design Approach</a></span></dt><dt><span class="sect1"><a href="#Record_Clients">Record Clients</a></span></dt></dl></div><p>
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.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Synchronous_Playback"></a>Synchronous Playback</h2></div></div></div><p>
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
<code class="function">MotionNotify</code>, <code class="function">ButtonPress</code>,
and <code class="function">ButtonRelease</code> 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
<code class="function">ImageText8</code> and <code class="function">PolyLine</code> to the
X server, or the X server could send non-device events such as
<code class="function">Expose</code> and <code class="function">MapNotify</code> 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)
</p><p>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Design_Approach"></a>Design Approach</h2></div></div></div><p>
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.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Record_Clients"></a>Record Clients</h2></div></div></div><p>
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.
</p><p>
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 <code class="function">XRecordContext</code>). 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.
</p><p>
A client that wishes to record X protocol does so through the library
functions defined in
<a class="xref" href="#Library_Extension_Requests" title="Chapter 3. Library Extension Requests"><em>Library Extension Requests</em></a>
A typical sequence of requests that a client would make is as follows:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="xref" href="#XRecordQueryVersion"><code class="function">XRecordQueryVersion</code></a>
</p><p>
query the extension protocol version.
</p></li><li class="listitem"><p>
<a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
</p><p>
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 <code class="function">XRecord-Context</code>, which is an XID that is
used by most other extension requests to identify the specified context.
</p></li><li class="listitem"><p>
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
</p><p>
begin the recording and reporting of protocol data.
</p></li><li class="listitem"><p>
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
</p><p>
end the recording and reporting of protocol data.
</p></li><li class="listitem"><p>
<a class="xref" href="#XRecordFreeContext"><code class="function">XRecordFreeContext</code></a>
</p><p>
free the record context.
</p></li></ul></div><p>
The header for this library is
<<code class="function">X11/extensions/record.h</code>>. All identifiers defined
in the interface are supplied by this header and are prefixed with "XRecord".
The <code class="function">Xtst</code> library contains the
<code class="function">XRecord</code> functions.
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Common_Arguments"></a>Chapter 2. Common Arguments</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Datum_Flags">Datum Flags</a></span></dt><dt><span class="sect1"><a href="#Selecting_Clients">Selecting Clients</a></span></dt><dt><span class="sect1"><a href="#Protocol_Ranges">Protocol Ranges</a></span></dt></dl></div><p>
The Record extension functions <a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
and <a class="xref" href="#XRecordRegisterClients"><code class="function">XRecordRegisterClients</code></a> allow applications to
specify the following:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Individual clients or sets of clients to record
</p></li><li class="listitem"><p>
Ranges of core X protocol and X extension protocol to record for each client
</p></li></ul></div><p>
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
<a class="xref" href="#Protocol_Ranges" title="Protocol Ranges">Protocol Ranges</a>
</p><p>
The Record extension functions <a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
and <a class="xref" href="#XRecordRegisterClients"><code class="function">XRecordRegisterClients</code></a> 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.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Datum_Flags"></a>Datum Flags</h2></div></div></div><p>
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.
</p><p>
The <code class="function">XRecordFromServerTime</code> flag specifies that
<code class="function">XRecordInterceptData</code> structures with a category of
<code class="function">XRecordFromServer</code> will have a server_time field specific to each
protocol element.
</p><p>
The <code class="function">XRecordFromClientTime</code> flag specifies that
<code class="function">XRecordInterceptData</code> structures with a category of
<code class="function">XRecordFromClient</code> will have a server_time field specific
to each protocol element.
</p><p>
The <code class="function">XRecordFromClientSequence</code> flag specifies that
<code class="function">XRecordInterceptData</code> structures with a category of
<code class="function">XRecordFromClient</code> or
<code class="function">XRecordClientDied</code> will have a valid client_seq field.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Selecting_Clients"></a>Selecting Clients</h2></div></div></div><p>
The clients argument is a pointer to an array of
<code class="function">XRecordClientSpec</code>.
<code class="function">XRecordClientSpec</code> is an integral type that holds a
resource ID, a client resource ID base, or one of the client set constants
defined below.
</p><p>
Duplicate elements in the array are ignored by the functions, and if any
element in the array is not valid, a
<code class="function">BadMatch</code>
error results. A resource ID references the client that created that
resource. The client set may be one of the following constants:
<code class="function">XRecordCurrentClients</code>,
<code class="function">XRecordFutureClients</code>, or
<code class="function">XRecordAllClients</code>.
</p><p>
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
<a class="xref" href="#Data_Transfer" title="Data Transfer">Data Transfer</a>
</p><p>
If the element is <code class="function">XRecordCurrentClients</code>, the protocol
ranges specified by the ranges argument, except for device_events, are
associated with each current client connection. If the element is
<code class="function">XRecordFutureClients</code>, the
protocol ranges specified by the ranges argument are associated with each new
client connection. If the element is
<code class="function">XRecordAllClients</code>,
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,
<code class="function">XRecordCurrentClients</code> and
<code class="function">XRecordAllClients</code>
silently exclude the recording data connection. It is an error to explicitly
register the data connection.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Protocol_Ranges"></a>Protocol Ranges</h2></div></div></div><p>
The functions <a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a> and
<a class="xref" href="#XRecordRegisterClients"><code class="function">XRecordRegisterClients</code></a> have another common argument,
ranges, which is an array of pointers to <code class="function">XRecordRange</code>
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 <code class="function">XRecordRange</code> structure must be
allocated by the Record library using the
<code class="function">XRecordAllocRange</code> function.
</p><p>
The <code class="function">XRecordRange</code> typedef is a structure with the
following members:
</p><div class="literallayout"><p><br />
XRecordRange:<br />
XRecordRange8 core_requests /* core X requests */<br />
XRecordRange8 core_replies /* core X replies */<br />
XRecordExtRange ext_requests /* extension requests */<br />
XRecordExtRange ext_replies /* extension replies */<br />
XRecordRange8 delivered_events /* delivered core and ext events */<br />
XRecordRange8 device_events /* all core and ext device events */<br />
XRecordRange8 errors /* core X and X ext errors */<br />
Bool client_started /* connection setup reply from server */<br />
Bool client_died /* notification of client disconnect */<br />
</p></div><p>
The types used in
<code class="function">XRecordRange</code>
members are defined as follows. The
<code class="function">XRecordRange8</code>
typedef is a structure with the following members:
</p><div class="literallayout"><p><br />
XRecordRange8:<br />
unsigned char first<br />
unsigned char last<br />
</p></div><p>
The
<code class="function">XRecordRange16</code>
typedef is a structure with the following members:
</p><div class="literallayout"><p><br />
XRecordRange16:<br />
unsigned short first<br />
unsigned short last<br />
</p></div><p>
The
<code class="function">XRecordExtRange</code>
typedef is a structure with the following members:
</p><div class="literallayout"><p><br />
XRecordExtRange:<br />
XRecordRange8 ext_major<br />
XRecordRange16 ext_minor<br />
</p></div><p>
If any of the values specified in
<code class="function">XRecordRange</code>
is invalid, a
<code class="function">BadValue</code>
error results.
</p><p>
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
<code class="function">BadValue</code>
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.
</p><p>
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
<code class="function">BadValue</code>
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.
</p><p>
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
<code class="function">BadValue</code>
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.
</p><p>
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
<code class="function">BadValue</code>
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.
</p><p>
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
<code class="function">BadValue</code>
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.
</p><p>
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
<code class="function">BadValue</code>
error results if the value of first is greater than the value of last. A
<code class="function">BadValue</code>
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.
</p><p>
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
<code class="function">BadValue</code>
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.
</p><p>
A value of
<code class="function">True</code>
for the client_started member specifies the
connection setup reply from the server to new clients. If
<code class="function">False</code>
the connection setup reply is not specified by this
<code class="function">XRecordRange</code>
</p><p>
A value of
<code class="function">True</code>
for the client_died member specifies
notification when a client disconnects. If
<code class="function">False</code>
notification when a client disconnects is not specified by this
<code class="function">XRecordRange</code>
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="Library_Extension_Requests"></a>Chapter 3. Library Extension Requests</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="#Query_Extension_Version">Query Extension Version</a></span></dt><dt><span class="sect1"><a href="#Create_and_Modify_Context">Create and Modify Context</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Additions">Additions</a></span></dt><dt><span class="sect2"><a href="#Deletions">Deletions</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Query_Context_State">Query Context State</a></span></dt><dt><span class="sect1"><a href="#Data_Transfer">Data Transfer</a></span></dt><dd><dl><dt><span class="sect2"><a href="#Enable_Context">Enable Context</a></span></dt><dt><span class="sect2"><a href="#Enable_Context_Asynchronously">Enable Context Asynchronously</a></span></dt><dt><span class="sect2"><a href="#Disable_Context">Disable Context</a></span></dt></dl></dd><dt><span class="sect1"><a href="#ID_Base_Mask">ID Base Mask</a></span></dt><dt><span class="sect1"><a href="#Free_Context">Free Context</a></span></dt></dl></div><p>
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
<code class="function">BadAlloc</code>
or
<code class="function">BadLength</code>
errors.
</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Query_Extension_Version"></a>Query Extension Version</h2></div></div></div><p>
An application uses the
<a class="xref" href="#XRecordQueryVersion"><code class="function">XRecordQueryVersion</code></a>
function to determine
the version of the Record extension protocol supported by an X server.
</p><div class="funcsynopsis"><a id="XRecordQueryVersion"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordQueryVersion</strong>(</code>Display <var class="pdparam"> *display</var>, int <var class="pdparam"> cmajor_return</var>, int <var class="pdparam"> cminor_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Returns the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>cmajor_return</em></span></span></p></td><td><p>Returns the extension protocol major version in use.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>cminor_return</em></span></span></p></td><td><p>Returns the extension protocol minor version in use.</p></td></tr></tbody></table></div><p>
The
<a class="xref" href="#XRecordQueryVersion"><code class="function">XRecordQueryVersion</code></a>
function returns the major and minor protocol version numbers supported by
the server.
<a class="xref" href="#XRecordQueryVersion"><code class="function">XRecordQueryVersion</code></a>
returns nonzero (success) only if the returned version numbers are
common to both the library and the server; otherwise, it returns zero.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Create_and_Modify_Context"></a>Create and Modify Context</h2></div></div></div><p>
An application uses the
<a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
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.
</p><div class="funcsynopsis"><a id="XRecordCreateContext"></a><p><code class="funcdef">XRecordContext <strong class="fsfunc">XRecordCreateContext</strong>(</code>Display <var class="pdparam"> *display</var>, int <var class="pdparam"> datum_flags</var>, XRecordClientSpec <var class="pdparam"> *clients</var>, int <var class="pdparam"> nclients</var>, XRecordRange <var class="pdparam"> *ranges</var>, int <var class="pdparam"> nranges</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Returns the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>datum_flags</em></span></span></p></td><td><p>Specifies whether detailed time or sequence info should be sent.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>clients</em></span></span></p></td><td><p>Specifies the clients to record.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>nclients</em></span></span></p></td><td><p>Specifies the number of clients.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>ranges</em></span></span></p></td><td><p>Specifies the protocol ranges to record.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>nranges</em></span></span></p></td><td><p>Specifies the number of protocol ranges.</p></td></tr></tbody></table></div><p>
The
<a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
function creates a record context and returns an
<code class="function">XRecordContext</code>
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 (
<a class="xref" href="#Datum_Flags" title="Datum Flags">Datum Flags</a>
). 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
<code class="function">XRecordCurrentClients</code>
<code class="function">XRecordFutureClients</code>
or
<code class="function">XRecordAllClients</code>
the actions described in
<a class="xref" href="#Selecting_Clients" title="Selecting Clients">Selecting Clients</a>
are performed.
</p><p>
<a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
returns zero if the request failed.
<a class="xref" href="#XRecordCreateContext"><code class="function">XRecordCreateContext</code></a>
can generate
<code class="function">BadIDChoice</code>
<code class="function">BadMatch</code>
and
<code class="function">BadValue</code>
errors.
</p><p>The ranges argument is an
<code class="function">XRecordRange</code>
array, that is, an array
of pointers. The structures the elements point to shall be allocated
by calling
<code class="function">XRecordAllocRange</code></p><div class="literallayout"><p><br />
XRecordRange *<br />
XRecordAllocRange(void)<br />
</p></div><p>
The
<code class="function">XRecordAllocRange</code>
function
allocates and returns an
<code class="function">XRecordRange</code>
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
<a href="../libX11/libX11/libX11.html#XFree" class="olink"><code class="function">XFree</code></a>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Additions"></a>Additions</h3></div></div></div><p>
An application uses the
<a class="xref" href="#XRecordRegisterClients"><code class="function">XRecordRegisterClients</code></a>
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.
</p><div class="funcsynopsis"><a id="XRecordRegisterClients"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordRegisterClients</strong>(</code>Display <var class="pdparam"> *display</var>, XRecordContext <var class="pdparam"> context</var>, int <var class="pdparam"> datum_flags</var>, XRecordClientSpec <var class="pdparam"> *clients</var>, int <var class="pdparam"> nclients</var>, XRecordRange <var class="pdparam"> *ranges</var>, int <var class="pdparam"> nranges</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Returns the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to modify.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>datum_flags</em></span></span></p></td><td><p>Specifies whether detailed time or sequence info should be sent.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>clients</em></span></span></p></td><td><p>Specifies the clients to record.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>nclients</em></span></span></p></td><td><p>Specifies the number of clients.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>ranges</em></span></span></p></td><td><p>Specifies the protocol ranges to record.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>nranges</em></span></span></p></td><td><p>Specifies the number of protocol ranges.</p></td></tr></tbody></table></div><p>
The datum_flags specifies whether server time and/or client sequence number
should precede protocol elements for all clients recorded by context (See
<a class="xref" href="#Datum_Flags" title="Datum Flags">Datum Flags</a>
). 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
<code class="function">XRecordCurrentClients</code>
<code class="function">XRecordFutureClients</code>
or
<code class="function">XRecordAllClients</code>
the actions described in
<a class="xref" href="#Selecting_Clients" title="Selecting Clients">Selecting Clients</a>
are performed.
</p><p>
<a class="xref" href="#XRecordRegisterClients"><code class="function">XRecordRegisterClients</code></a>
returns zero if the request failed; otherwise, it
returns nonzero.
</p><p>
<a class="xref" href="#XRecordRegisterClients"><code class="function">XRecordRegisterClients</code></a>
can generate
<code class="function">XRecordBadContext</code>
<code class="function">BadMatch</code>
and
<code class="function">BadValue</code>
errors.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Deletions"></a>Deletions</h3></div></div></div><p>
An application uses the
<code class="function">XRecordUnregisterClients</code>
function to delete clients from a previously created
record context, typically over its control connection to the X server.
</p><div class="funcsynopsis"><a id="XRecordUnRegisterClients"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordUnRegisterClients</strong>(</code>Display <var class="pdparam"> *display</var>, XRecordContext <var class="pdparam"> context</var>, XRecordClientSpec <var class="pdparam"> *clients</var>, int <var class="pdparam"> nclients</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Returns the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to modify.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>clients</em></span></span></p></td><td><p>Specifies the clients to stop recording.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>nclients</em></span></span></p></td><td><p>Specifies the number of clients.</p></td></tr></tbody></table></div><p>
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.
</p><p>
When the element is
<code class="function">XRecordCurrentClients</code>
all clients currently targeted for recording in context and their
corresponding sets of protocol to record are deleted from context.
</p><p>
When the item is
<code class="function">XRecordFutureClients</code>
any future client connections will not automatically be targeted for
recording in context.
</p><p>
When the element is
<code class="function">XRecordAllClients</code>
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.
</p><p>
<code class="function">XRecordUnregisterClients</code>
returns zero if the request failed; otherwise, it returns nonzero.
</p><p>
<code class="function">XRecordUnregisterClients</code>
can generate
<code class="function">XRecordBadContext</code>
<code class="function">BadMatch</code>
and
<code class="function">BadValue</code>
errors.</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Query_Context_State"></a>Query Context State</h2></div></div></div><p>
An application uses the
<a class="xref" href="#XRecordGetContext"><code class="function">XRecordGetContext</code></a>
function to query the current state of a record context, typically over
its control connection to the X server.
</p><div class="funcsynopsis"><a id="XRecordGetContext"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordGetContext</strong>(</code>Display <var class="pdparam"> *display</var>, XRecordContext <var class="pdparam"> context</var>, XRecordState <var class="pdparam"> **state_return</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to query.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>state_return</em></span></span></p></td><td><p>Specifies the address of a variable into which
the function stores a pointer to the current state of the record context.
</p></td></tr></tbody></table></div><p>
The
<code class="function">XRecordState</code>
typedef returned by
<a class="xref" href="#XRecordGetContext"><code class="function">XRecordGetContext</code></a>
is a structure with the following members:
</p><div class="literallayout"><p><br />
XRecordState:<br />
Bool enabled<br />
int datum_flags<br />
unsigned long nclients<br />
XRecordClientInfo **client_info<br />
</p></div><p>
The enabled member is set to the state of data transfer and is
<code class="function">True</code>
when the recording client has asked that recorded data be sent;
otherwise it is
<code class="function">False</code>
The datum_flags member is set to the value of these flags for this context.
The nclients member is set to the number of
<code class="function">XRecordClientInfo</code>
structures returned. The client_info member is an array of pointers to
<code class="function">XRecordClientInfo</code>
structures that contain the protocol to record for each targeted client. The
<code class="function">XRecordClientInfo</code>
typedef is a structure with the following members:
</p><div class="literallayout"><p><br />
XRecordClientInfo:<br />
XRecordClientSpec client<br />
unsigned long nranges<br />
XRecordRange **ranges<br />
</p></div><p>
The client member either identifies a client targeted for recording
or is set to
<code class="function">XRecordFutureClients</code>
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
<code class="function">XRecordRange</code>
structures, which specify the protocol ranges to record.
</p><p>
<a class="xref" href="#XRecordGetContext"><code class="function">XRecordGetContext</code></a>
returns zero if the request failed; otherwise, it returns nonzero.
The context argument must specify a valid
<code class="function">XRecordContext</code>
or a
<code class="function">XRecordBadContext</code>
error results.
</p><p>
Recording clients should use the
<a class="xref" href="#XRecordFreeState"><code class="function">XRecordFreeState</code></a>
function to free the state data returned by
<a class="xref" href="#XRecordGetContext"><code class="function">XRecordGetContext</code></a>
</p><div class="funcsynopsis"><a id="XRecordFreeState"></a><p><code class="funcdef">void <strong class="fsfunc">XRecordFreeState</strong>(</code>XRecordState <var class="pdparam"> *state</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>state</em></span></span></p></td><td><p>Specifies the structure that is to be freed.</p></td></tr></tbody></table></div><p>
<a class="xref" href="#XRecordFreeState"><code class="function">XRecordFreeState</code></a>
frees the data pointed to by state. If the argument does not match an
<code class="function">XRecordState</code>
pointer returned from a successful call to
<a class="xref" href="#XRecordGetContext"><code class="function">XRecordGetContext</code></a>
or if
<a class="xref" href="#XRecordFreeState"><code class="function">XRecordFreeState</code></a>
has already been called with it, the behavior is undefined.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Data_Transfer"></a>Data Transfer</h2></div></div></div><p>
An application uses the
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
and
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
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.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Enable_Context"></a>Enable Context</h3></div></div></div><p>
To direct the X server to record and report protocol, a program uses
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
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
<code class="function">XRecordInterceptData</code>
typedef, a structure with the following members:
</p><div class="literallayout"><p><br />
XRecordInterceptData:<br />
XID id_base<br />
Time server_time<br />
unsigned long client_seq<br />
int category<br />
Bool client_swapped<br />
unsigned char *data<br />
unsigned long data_len<br />
</p></div><p>
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:
<code class="function">XRecordStartOfData</code>
<code class="function">XRecordFromServer</code>
<code class="function">XRecordFromClient</code>
<code class="function">XRecordClientStarted</code>
<code class="function">XRecordClientDied</code>
or
<code class="function">XRecordEndOfData</code>
<code class="function">XRecordStartOfData</code>
is immediately sent as the first reply to confirm that the context is enabled.
<code class="function">XRecordFromClient</code>
indicates the protocol
data is from the recorded client to the server (requests).
<code class="function">XRecordFromServer</code>
indicates the protocol data is from the server to the recorded client
(replies, errors, events, or device events).
<code class="function">XRecordClientStarted</code>
indicates that the protocol data is the connection setup reply from the server.
<code class="function">XRecordClientDied</code>
indicates that the recorded client has closed its connection
to the X server; there is no protocol data.
<code class="function">XRecordEndOfData</code>
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.
</p><p>
The client_swapped member is set to
<code class="function">True</code>
if the byte order of the client being recorded is swapped relative to
the recording client; otherwise, it is set to
<code class="function">False</code>
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
<code class="function">XRecordStartOfData</code>
and
<code class="function">XRecordEndOfData</code>
client_swapped is set according
to the byte order of the server relative to the recording client.
</p><p>
The data member contains the actual recorded protocol data.
When category is set to
<code class="function">XRecordStartOfData</code>
<code class="function">XRecordClientDied</code>
or
<code class="function">XRecordEndOfData</code>
no protocol data are contained in data.
</p><p>
For the core X events
<code class="function">KeyPress</code>
<code class="function">KeyRelease</code>
<code class="function">ButtonPress</code>
and
<code class="function">ButtonRelease</code>,
the fields of a device event that contain
valid information are time and detail. For the core X event
<code class="function">MotionNotify</code>
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.
</p><p>For the extension input device events
<code class="function">DeviceKeyPress</code>
<code class="function">DeviceKeyRelease</code>
<code class="function">DeviceButtonPress</code>
and
<code class="function">DeviceButtonRelease</code>
the fields of a device event that contain valid information are
device, time, and detail. For
<code class="function">DeviceMotionNotify</code>
the valid device event fields are device and time.
For the extension input device events
<code class="function">ProximityIn</code>
and
<code class="function">ProximityOut</code>
the fields of a device event that contain valid
information are device and time. For the extension input device event
<code class="function">DeviceValuator</code>
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.
</p><p>
The data_len member is set to the length of the actual recorded protocol
data in 4-byte units.
</p><p>
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
<code class="function">XRecordInterceptProc</code>
is called for each protocol element in the reply.
</p><div class="funcsynopsis"><a id="XRecordInterceptProc"></a><p><code class="funcdef">typedef void <strong class="fsfunc">(*XRecordInterceptProc)</strong>(</code>XPointer<var class="pdparam"> closure</var>, XRecordInterceptData<var class="pdparam"> *recorded_data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>closure</em></span></span></p></td><td><p>Pointer that was passed in when the context was enabled.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>recorded_data</em></span></span></p></td><td><p>A protocol element recorded by the server extension.</p></td></tr></tbody></table></div><p>
This callback may use the control display connection (or any display
connection other than the data connection).
</p><p>
Recording clients should use the
<a class="xref" href="#XRecordFreeData"><code class="function">XRecordFreeData</code></a>
function to free the
<code class="function">XRecordInterceptData</code>
structure.
</p><div class="funcsynopsis"><a id="XRecordEnableContext"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordEnableContext</strong>(</code>Display<var class="pdparam"> *display</var>, XRecordContext<var class="pdparam"> context</var>, XRecordInterceptProc<var class="pdparam"> callback</var>, XPointer<var class="pdparam"> closure</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to enable.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>callback</em></span></span></p></td><td><p>Specifies the function to be called for each protocol element received.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>closure</em></span></span></p></td><td><p>Specifies data passed to callback.</p></td></tr></tbody></table></div><p>
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
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.
</p><p>
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
returns zero if the request failed; otherwise, it
returns nonzero. The context argument must specify a valid
<code class="function">XRecordContext</code>
or a
<code class="function">XRecordBadContext</code>
error results. The error
<code class="function">BadMatch</code>
results when data transfer is already enabled on the given context.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Enable_Context_Asynchronously"></a>Enable Context Asynchronously</h3></div></div></div><p>Because
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
does not return until
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
is executed on the control connection, a nonblocking interface in
addition to
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
is provided. This interface also
enables data transfer; however, it does not block.
</p><p>
This interface is defined as follows:
</p><div class="funcsynopsis"><a id="XRecordEnableContextAsync"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordEnableContextAsync</strong>(</code>Display<var class="pdparam"> *display</var>, XRecordContext<var class="pdparam"> context</var>, XRecordInterceptProc<var class="pdparam"> callback</var>, XPointer<var class="pdparam"> closure</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to enable.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>callback</em></span></span></p></td><td><p>Specifies the function to be called for each protocol element received.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>closure</em></span></span></p></td><td><p>Specifies data passed to callback.</p></td></tr></tbody></table></div><p>
<a class="xref" href="#XRecordEnableContextAsync"><code class="function">XRecordEnableContextAsync</code></a>
enables data transfer between the recording
client and the X server just as
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
does. Unlike
<a class="xref" href="#XRecordEnableContext"><code class="function">XRecordEnableContext</code></a>
it does not wait for the context to be disabled
before returning;
<a class="xref" href="#XRecordEnableContextAsync"><code class="function">XRecordEnableContextAsync</code></a>
returns as soon as the
<code class="function">XRecordStartOfData</code>
reply has been received and processed.
</p><p>
<a class="xref" href="#XRecordEnableContextAsync"><code class="function">XRecordEnableContextAsync</code></a>
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
<code class="function">XRecordContext</code>
or a
<code class="function">XRecordBadContext</code>
error results. The error
<code class="function">BadMatch</code>
results when data transfer is already enabled.
</p><p>
Each time it reads data from the server connection, Xlib will check
for incoming replies and call <span class="emphasis"><em>callback</em></span>
as necessary. The application may direct Xlib explicitly to check
for Record data with the
<a class="xref" href="#XRecordProcessReplies"><code class="function">XRecordProcessReplies</code></a>
function.
</p><div class="funcsynopsis"><a id="XRecordProcessReplies"></a><p><code class="funcdef">void <strong class="fsfunc">XRecordProcessReplies</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr></tbody></table></div><p>
<a class="xref" href="#XRecordProcessReplies"><code class="function">XRecordProcessReplies</code></a>
will check for any replies that have not yet
been processed by the application. The asynchronous callback will be called
as appropriate.
<a class="xref" href="#XRecordProcessReplies"><code class="function">XRecordProcessReplies</code></a>
returns when all immediately
available replies have been processed. It does not block.
</p><p>To free the data passed to the
<code class="function">XRecordInterceptProc</code>
callback, use
<a class="xref" href="#XRecordFreeData"><code class="function">XRecordFreeData</code></a></p><div class="funcsynopsis"><a id="XRecordFreeData"></a><p><code class="funcdef">void <strong class="fsfunc">XRecordFreeData</strong>(</code>XRecordInterceptData<var class="pdparam"> *data</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>data</em></span></span></p></td><td><p>Specifies the structure that is to be freed.</p></td></tr></tbody></table></div><p>
<a class="xref" href="#XRecordFreeData"><code class="function">XRecordFreeData</code></a>
frees the data pointed to by data. If the argument does not match an
<code class="function">XRecordInterceptData</code>
pointer earlier passed to an
<code class="function">XRecordInterceptProc</code>
callback or if
<a class="xref" href="#XRecordFreeData"><code class="function">XRecordFreeData</code></a>
has already been called with it, the behavior is undefined.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="Disable_Context"></a>Disable Context</h3></div></div></div><p>
To direct the X server to halt the reporting of recorded protocol, the
program executes
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
typically over its control connection to the X server.
</p><div class="funcsynopsis"><a id="XRecordDisableContext"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordDisableContext</strong>(</code>Display<var class="pdparam"> *display</var>, XRecordContext<var class="pdparam"> context</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to disable.</p></td></tr></tbody></table></div><p>
The
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
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
<code class="function">XRecordContext</code>
that has not been enabled, no action will take place.
</p><p>
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
returns zero if the request failed; otherwise, it
returns nonzero. The context argument must specify a valid
<code class="function">XRecordContext</code>
or an
<code class="function">XRecordBadContext</code>
error results.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ID_Base_Mask"></a>ID Base Mask</h2></div></div></div><p>
To determine the mask the server uses for the client ID base, use
<a class="xref" href="#XRecordIdBaseMask"><code class="function">XRecordIdBaseMask</code></a></p><div class="funcsynopsis"><a id="XRecordIdBaseMask"></a><p><code class="funcdef">XID <strong class="fsfunc">XRecordIdBaseMask</strong>(</code>Display<var class="pdparam"> *display</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr></tbody></table></div><p>
The
<a class="xref" href="#XRecordIdBaseMask"><code class="function">XRecordIdBaseMask</code></a>
function returns the resource ID mask passed to the client by the
server at connection setup.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Free_Context"></a>Free Context</h2></div></div></div><p>
Before terminating, the program should request that the server
free the record context. This is done with the
<a class="xref" href="#XRecordFreeContext"><code class="function">XRecordFreeContext</code></a>
function, typically over the record client's control connection
to the X server.
</p><div class="funcsynopsis"><a id="XRecordFreeContext"></a><p><code class="funcdef">Status <strong class="fsfunc">XRecordFreeContext</strong>(</code>Display<var class="pdparam"> *display</var>, XRecordContext<var class="pdparam"> context</var><code>)</code>;</p></div><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top" /><col /></colgroup><tbody><tr><td><p><span class="term"><span class="emphasis"><em>display</em></span></span></p></td><td><p>Specifies the connection to the X server.</p></td></tr><tr><td><p><span class="term"><span class="emphasis"><em>context</em></span></span></p></td><td><p>Specifies the record context to free.</p></td></tr></tbody></table></div><p>
The
<a class="xref" href="#XRecordFreeContext"><code class="function">XRecordFreeContext</code></a>
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
<a class="xref" href="#XRecordDisableContext"><code class="function">XRecordDisableContext</code></a>
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.
</p><p>
<a class="xref" href="#XRecordFreeContext"><code class="function">XRecordFreeContext</code></a>
returns zero if the request failed; otherwise,it
returns nonzero. The context argument must specify a valid
<code class="function">XRecordContext</code>
or a
<code class="function">XRecordBadContext</code>
error results.
</p></div></div></div></body></html>