diff options
Diffstat (limited to 'specs/recordlib.xml')
| -rw-r--r-- | specs/recordlib.xml | 208 |
1 files changed, 101 insertions, 107 deletions
diff --git a/specs/recordlib.xml b/specs/recordlib.xml index 85cdaf4..08d3eb2 100644 --- a/specs/recordlib.xml +++ b/specs/recordlib.xml @@ -67,7 +67,7 @@ X Consortium. </legalnotice> </bookinfo> -<chapter id="record_extension_overview"> +<chapter id='Record_Extension_Overview'> <title>Record Extension Overview</title> <para> The purpose of this extension is to support the recording and reporting of @@ -76,7 +76,7 @@ gives an overview of the Record extension. The following sections describe how to use the Record extension library. </para> -<sect1 id="synchronous_playback"> +<sect1 id='Synchronous_Playback'> <title>Synchronous Playback</title> <para> Environment information is generally provided to an X-based playback @@ -113,7 +113,7 @@ synchronization methodology. </para> </sect1> -<sect1 id="design_approach"> +<sect1 id='Design_Approach'> <title>Design Approach</title> <para> The design approach of the extension is to record core X protocol and @@ -125,7 +125,7 @@ events, including input device events that do not go to any clients. </para> </sect1> -<sect1 id="record_clients"> +<sect1 id='Record_Clients'> <title>Record Clients</title> <para> The recommended communication model for a Record application is to open two @@ -144,14 +144,13 @@ recording operations. <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> +<xref linkend='Library_Extension_Requests' xrefstyle='select: title'/> A typical sequence of requests that a client would make is as follows: </para> <itemizedlist> <listitem> <para> -<function>XRecordQueryVersion</function> +<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> </para> <para> query the extension protocol version. @@ -159,7 +158,7 @@ query the extension protocol version. </listitem> <listitem> <para> -<function>XRecordCreateContext</function> +<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> </para> <para> request that the server create a record context for access by this client, @@ -170,7 +169,7 @@ used by most other extension requests to identify the specified context. </listitem> <listitem> <para> -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> </para> <para> begin the recording and reporting of protocol data. @@ -178,7 +177,7 @@ begin the recording and reporting of protocol data. </listitem> <listitem> <para> -<function>XRecordDisableContext</function> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> </para> <para> end the recording and reporting of protocol data. @@ -186,7 +185,7 @@ end the recording and reporting of protocol data. </listitem> <listitem> <para> -<function>XRecordFreeContext</function> +<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> </para> <para> free the record context. @@ -205,11 +204,11 @@ The <function>Xtst</function> library contains the </sect1> </chapter> -<chapter id="common_arguments"> +<chapter id='Common_Arguments'> <title>Common Arguments</title> <para> -The Record extension functions <function>XRecordCreateContext</function> - and <function>XRecordRegisterClients</function> allow applications to +The Record extension functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> + and <xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> allow applications to specify the following: </para> <itemizedlist> @@ -231,21 +230,20 @@ 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> +<xref linkend='Protocol_Ranges' xrefstyle='select: title'/> </para> <para> -The Record extension functions <function>XRecordCreateContext</function> - and <function>XRecordRegisterClients</function> have the common arguments +The Record extension functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> + and <xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> have the common arguments datum_flags, clients, and ranges, which specify whether server time and/or client sequence number should precede protocol elements, the clients or client set to record, and the protocol ranges to record, respectively. These are discussed in the following sections. </para> -<sect1 id="datum_flags"> +<sect1 id='Datum_Flags'> <title>Datum Flags</title> <para> The datum_flags argument is a set of flags OR’ed together to specify options @@ -274,7 +272,7 @@ The <function>XRecordFromClientSequence</function> flag specifies that </para> </sect1> -<sect1 id="selecting_clients"> +<sect1 id='Selecting_Clients'> <title>Selecting Clients</title> <para> @@ -299,8 +297,7 @@ 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> +<xref linkend='Data_Transfer' xrefstyle='select: title'/> </para> <para> If the element is <function>XRecordCurrentClients</function>, the protocol @@ -320,12 +317,12 @@ silently exclude the recording data connection. It is an error to explicitly register the data connection. </para> </sect1> -<sect1 id="protocol_ranges"> +<sect1 id='Protocol_Ranges'> <title>Protocol Ranges</title> <para> -The functions <function>XRecordCreateContext</function> and -<function>XRecordRegisterClients</function> have another common argument, +The functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> and +<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> have another common argument, ranges, which is an array of pointers to <function>XRecordRange</function> structures. Each structure contains ranges of numeric values for each of the protocol types that can be specified and recorded individually by the @@ -507,7 +504,7 @@ notification when a client disconnects is not specified by this </sect1> </chapter> -<chapter id='library_extension_requests'> +<chapter id='Library_Extension_Requests'> <title>Library Extension Requests</title> <para> @@ -522,17 +519,17 @@ or errors. </para> -<sect1 id='query_extension_version'> +<sect1 id='Query_Extension_Version'> <title>Query Extension Version</title> <para> An application uses the -<function>XRecordQueryVersion</function> +<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> function to determine the version of the Record extension protocol supported by an X server. </para> -<funcsynopsis id='xrecordqueryversion'> +<funcsynopsis id='XRecordQueryVersion'> <funcprototype> <funcdef>Status <function>XRecordQueryVersion</function></funcdef> <paramdef>Display <parameter> *display</parameter></paramdef> @@ -558,27 +555,27 @@ the version of the Record extension protocol supported by an X server. <para> The -<function>XRecordQueryVersion</function> +<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> function returns the major and minor protocol version numbers supported by the server. -<function>XRecordQueryVersion</function> +<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> returns nonzero (success) only if the returned version numbers are common to both the library and the server; otherwise, it returns zero. </para> </sect1> -<sect1 id='create_and_modify_context'> +<sect1 id='Create_and_Modify_Context'> <title>Create and Modify Context</title> <para> An application uses the -<function>XRecordCreateContext</function> +<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> function to create a record context. At the time the record context is created by the recording client, the clients to be recorded and the protocol to record for each client may be specified. </para> -<funcsynopsis id='xrecordcreatecontext'> +<funcsynopsis id='XRecordCreateContext'> <funcprototype> <funcdef>XRecordContext <function>XRecordCreateContext</function></funcdef> <paramdef>Display <parameter> *display</parameter></paramdef> @@ -619,15 +616,14 @@ protocol to record for each client may be specified. <para> The -<function>XRecordCreateContext</function> +<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> function creates a record context and returns an <function>XRecordContext</function> which is then used in the other Record library calls. This request is typically executed by the recording client over its control connection to the X server. The datum_flags specifies whether server time and/or client sequence number should precede protocol elements recorded by context ( -<link linkend="datum_flags"> -<xref linkend="datum_flags"></xref></link> +<xref linkend='Datum_Flags' xrefstyle='select: title'/> ). When a clients element identifies a particular client, the client is added to the context and the protocol to record for that client is set to the union of all ranges. When a clients element is @@ -636,15 +632,14 @@ union of all ranges. When a clients element is or <function>XRecordAllClients</function> the actions described in -<link linkend="selecting_clients"> -<xref linkend="selecting_clients"></xref></link> +<xref linkend='Selecting_Clients' xrefstyle='select: title'/> are performed. </para> <para> -<function>XRecordCreateContext</function> +<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> returns zero if the request failed. -<function>XRecordCreateContext</function> +<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> can generate <function>BadIDChoice</function> <function>BadMatch</function> @@ -675,21 +670,21 @@ 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> +<olink targetdoc='libX11' targetptr='XFree'><function>XFree</function></olink> </para> -<sect2 id='additions'> +<sect2 id='Additions'> <title>Additions</title> <para> An application uses the -<function>XRecordRegisterClients</function> +<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> function to modify a previously created record context, by adding clients or modifying the recorded protocol, typically over its control connection to the X server. </para> -<funcsynopsis id='xrecordregisterclients'> +<funcsynopsis id='XRecordRegisterClients'> <funcprototype> <funcdef>Status <function>XRecordRegisterClients</function></funcdef> <paramdef>Display <parameter> *display</parameter></paramdef> @@ -736,8 +731,7 @@ typically over its control connection to the X server. <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> +<xref linkend='Datum_Flags' xrefstyle='select: title'/> ). When a clients element identifies a particular client and the client is not yet targeted for recording in the given context, the client is added to the set of clients to record, and the protocol to record for that client @@ -749,19 +743,18 @@ is set to the union of all ranges. When the element is or <function>XRecordAllClients</function> the actions described in -<link linkend="selecting_clients"> -<xref linkend="selecting_clients"></xref></link> +<xref linkend='Selecting_Clients' xrefstyle='select: title'/> are performed. </para> <para> -<function>XRecordRegisterClients</function> +<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> returns zero if the request failed; otherwise, it returns nonzero. </para> <para> -<function>XRecordRegisterClients</function> +<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> can generate <function>XRecordBadContext</function> <function>BadMatch</function> @@ -771,7 +764,7 @@ errors. </para> </sect2> -<sect2 id='deletions'> +<sect2 id='Deletions'> <title>Deletions</title> <para> @@ -781,7 +774,7 @@ function to delete clients from a previously created record context, typically over its control connection to the X server. </para> -<funcsynopsis id='xrecordunregisterclients'> +<funcsynopsis id='XRecordUnRegisterClients'> <funcprototype> <funcdef>Status <function>XRecordUnRegisterClients</function></funcdef> <paramdef>Display <parameter> *display</parameter></paramdef> @@ -857,17 +850,17 @@ errors.</para> </sect2> </sect1> -<sect1 id='query_context_state'> +<sect1 id='Query_Context_State'> <title>Query Context State</title> <para> An application uses the -<function>XRecordGetContext</function> +<xref linkend='XRecordGetContext' xrefstyle='select: title'/> function to query the current state of a record context, typically over its control connection to the X server. </para> -<funcsynopsis id='xrecordgetcontext'> +<funcsynopsis id='XRecordGetContext'> <funcprototype> <funcdef>Status <function>XRecordGetContext</function></funcdef> <paramdef>Display <parameter> *display</parameter></paramdef> @@ -897,7 +890,7 @@ the function stores a pointer to the current state of the record context. The <function>XRecordState</function> typedef returned by -<function>XRecordGetContext</function> +<xref linkend='XRecordGetContext' xrefstyle='select: title'/> is a structure with the following members: </para> @@ -945,7 +938,7 @@ structures, which specify the protocol ranges to record. </para> <para> -<function>XRecordGetContext</function> +<xref linkend='XRecordGetContext' xrefstyle='select: title'/> returns zero if the request failed; otherwise, it returns nonzero. The context argument must specify a valid <function>XRecordContext</function> @@ -956,12 +949,12 @@ error results. <para> Recording clients should use the -<function>XRecordFreeState</function> +<xref linkend='XRecordFreeState' xrefstyle='select: title'/> function to free the state data returned by -<function>XRecordGetContext</function> +<xref linkend='XRecordGetContext' xrefstyle='select: title'/> </para> -<funcsynopsis id='xrecordfreestate'> +<funcsynopsis id='XRecordFreeState'> <funcprototype> <funcdef>void <function>XRecordFreeState</function></funcdef> <paramdef>XRecordState <parameter> *state</parameter></paramdef> @@ -976,37 +969,37 @@ function to free the state data returned by </variablelist> <para> -<function>XRecordFreeState</function> +<xref linkend='XRecordFreeState' xrefstyle='select: title'/> frees the data pointed to by state. If the argument does not match an <function>XRecordState</function> pointer returned from a successful call to -<function>XRecordGetContext</function> +<xref linkend='XRecordGetContext' xrefstyle='select: title'/> or if -<function>XRecordFreeState</function> +<xref linkend='XRecordFreeState' xrefstyle='select: title'/> has already been called with it, the behavior is undefined. </para> </sect1> -<sect1 id='data_transfer'> +<sect1 id='Data_Transfer'> <title>Data Transfer</title> <para> An application uses the -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> and -<function>XRecordDisableContext</function> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> functions to change the state of data transfer between the X server and the recording client. These functions allow the application to start recording and reporting of protocol data and to stop recording and reporting of protocol data, respectively. </para> -<sect2 id='enable_context'> +<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> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> typically over its data connection to the X server. The reporting of recorded protocol back to the recording client is handled by the following data structures and procedure definitions. @@ -1150,7 +1143,7 @@ in the same reply packet. When a reply is received, a procedure of type is called for each protocol element in the reply. </para> -<funcsynopsis id='xrecordinterceptproc'> +<funcsynopsis id='XRecordInterceptProc'> <funcprototype> <funcdef>typedef void <function>(*XRecordInterceptProc)</function></funcdef> <paramdef>XPointer<parameter> closure</parameter></paramdef> @@ -1176,13 +1169,13 @@ connection other than the data connection). <para> Recording clients should use the -<function>XRecordFreeData</function> +<xref linkend='XRecordFreeData' xrefstyle='select: title'/> function to free the <function>XRecordInterceptData</function> structure. </para> -<funcsynopsis id='xrecordenablecontext'> +<funcsynopsis id='XRecordEnableContext'> <funcprototype> <funcdef>Status <function>XRecordEnableContext</function></funcdef> <paramdef>Display<parameter> *display</parameter></paramdef> @@ -1213,7 +1206,7 @@ structure. <para> -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> enables data transfer between the recording client and the X server. All core and extension protocol received from or sent to targeted clients that the recording client has expressed @@ -1221,7 +1214,7 @@ interest in will be recorded and reported to the recording client. </para> <para> -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> returns zero if the request failed; otherwise, it returns nonzero. The context argument must specify a valid <function>XRecordContext</function> @@ -1233,16 +1226,16 @@ results when data transfer is already enabled on the given context. </para> </sect2> -<sect2 id='enable_context_asynchronously'> +<sect2 id='Enable_Context_Asynchronously'> <title>Enable Context Asynchronously</title> <para>Because -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> does not return until -<function>XRecordDisableContext</function> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> is executed on the control connection, a nonblocking interface in addition to -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> is provided. This interface also enables data transfer; however, it does not block. </para> @@ -1251,7 +1244,7 @@ enables data transfer; however, it does not block. This interface is defined as follows: </para> -<funcsynopsis id='xrecordenablecontextasync'> +<funcsynopsis id='XRecordEnableContextAsync'> <funcprototype> <funcdef>Status <function>XRecordEnableContextAsync</function></funcdef> <paramdef>Display<parameter> *display</parameter></paramdef> @@ -1281,22 +1274,22 @@ This interface is defined as follows: </variablelist> <para> -<function>XRecordEnableContextAsync</function> +<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/> enables data transfer between the recording client and the X server just as -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> does. Unlike -<function>XRecordEnableContext</function> +<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> it does not wait for the context to be disabled before returning; -<function>XRecordEnableContextAsync</function> +<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/> returns as soon as the <function>XRecordStartOfData</function> reply has been received and processed. </para> <para> -<function>XRecordEnableContextAsync</function> +<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/> returns zero if it could not allocate the necessary memory and nonzero if it sent the request successfully to the server. The context argument must specify a valid @@ -1313,11 +1306,11 @@ 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> +<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/> function. </para> -<funcsynopsis id='xrecordprocessreplies'> +<funcsynopsis id='XRecordProcessReplies'> <funcprototype> <funcdef>void <function>XRecordProcessReplies</function></funcdef> <paramdef>Display<parameter> *display</parameter></paramdef> @@ -1332,11 +1325,11 @@ function. </variablelist> <para> -<function>XRecordProcessReplies</function> +<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/> will check for any replies that have not yet been processed by the application. The asynchronous callback will be called as appropriate. -<function>XRecordProcessReplies</function> +<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/> returns when all immediately available replies have been processed. It does not block. </para> @@ -1344,9 +1337,9 @@ available replies have been processed. It does not block. <para>To free the data passed to the <function>XRecordInterceptProc</function> callback, use -<function>XRecordFreeData</function></para> +<xref linkend='XRecordFreeData' xrefstyle='select: title'/></para> -<funcsynopsis id='xrecordfreedata'> +<funcsynopsis id='XRecordFreeData'> <funcprototype> <funcdef>void <function>XRecordFreeData</function></funcdef> <paramdef>XRecordInterceptData<parameter> *data</parameter></paramdef> @@ -1362,28 +1355,28 @@ callback, use <para> -<function>XRecordFreeData</function> +<xref linkend='XRecordFreeData' xrefstyle='select: title'/> frees the data pointed to by data. If the argument does not match an <function>XRecordInterceptData</function> pointer earlier passed to an <function>XRecordInterceptProc</function> callback or if -<function>XRecordFreeData</function> +<xref linkend='XRecordFreeData' xrefstyle='select: title'/> has already been called with it, the behavior is undefined. </para> </sect2> -<sect2 id='disable_context'> +<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> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> typically over its control connection to the X server. </para> -<funcsynopsis id='xrecorddisablecontext'> +<funcsynopsis id='XRecordDisableContext'> <funcprototype> <funcdef>Status <function>XRecordDisableContext</function></funcdef> <paramdef>Display<parameter> *display</parameter></paramdef> @@ -1405,7 +1398,7 @@ typically over its control connection to the X server. <para> The -<function>XRecordDisableContext</function> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> function disables context, stopping all recording over its data connection. Any complete protocol elements for context that were buffered in the server will be sent to the recording client rather than being discarded. @@ -1415,7 +1408,7 @@ that has not been enabled, no action will take place. </para> <para> -<function>XRecordDisableContext</function> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> returns zero if the request failed; otherwise, it returns nonzero. The context argument must specify a valid <function>XRecordContext</function> @@ -1426,13 +1419,14 @@ error results. </sect2> </sect1> -<sect1 id='id_base_mask'><title>ID Base Mask</title> +<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> +<xref linkend='XRecordIdBaseMask' xrefstyle='select: title'/></para> -<funcsynopsis id='xrecordidbasemask'> +<funcsynopsis id='XRecordIdBaseMask'> <funcprototype> <funcdef>XID <function>XRecordIdBaseMask</function></funcdef> <paramdef>Display<parameter> *display</parameter></paramdef> @@ -1448,25 +1442,25 @@ To determine the mask the server uses for the client ID base, use <para> The -<function>XRecordIdBaseMask</function> +<xref linkend='XRecordIdBaseMask' xrefstyle='select: title'/> function returns the resource ID mask passed to the client by the server at connection setup. </para> </sect1> -<sect1 id='free_context'> +<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> +<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> function, typically over the record client's control connection to the X server. </para> -<funcsynopsis id='xrecordfreecontext'> +<funcsynopsis id='XRecordFreeContext'> <funcprototype> <funcdef>Status <function>XRecordFreeContext</function></funcdef> <paramdef>Display<parameter> *display</parameter></paramdef> @@ -1487,21 +1481,21 @@ to the X server. <para> The -<function>XRecordFreeContext</function> +<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> function frees the given context for the requesting client. Freeing a record context releases the clients targeted for recording and their respective protocol ranges to record. If protocol data is being reported to the recording client, generally over the data connection to the X server, the reporting ceases as if -<function>XRecordDisableContext</function> +<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> had been called on the given context. When a program terminates without freeing its record context, the X server will automatically free that context on behalf of the client. </para> <para> -<function>XRecordFreeContext</function> +<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> returns zero if the request failed; otherwise,it returns nonzero. The context argument must specify a valid <function>XRecordContext</function> |