diff options
Diffstat (limited to 'specs/recordlib.xml')
| -rw-r--r-- | specs/recordlib.xml | 1516 |
1 files changed, 1516 insertions, 0 deletions
diff --git a/specs/recordlib.xml b/specs/recordlib.xml new file mode 100644 index 0000000..903f02a --- /dev/null +++ b/specs/recordlib.xml @@ -0,0 +1,1516 @@ +<?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> |