1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" 4[ 5<!ENTITY % defs SYSTEM "defs.ent"> %defs; 6]> 7 8 9<!-- lifted from troff+ms+XMan by doclifter --> 10<book id="recordlib"> 11 12<bookinfo> 13 <title>X Record Extension Library</title> 14 <subtitle>X Consortium Standard</subtitle> 15 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 16 <releaseinfo>Version 1.13</releaseinfo> 17 <authorgroup> 18 <author> 19 <firstname>Martha</firstname><surname>Zimet</surname> 20 <affiliation><orgname>Network Computing Devices, Inc.</orgname></affiliation> 21 </author> 22 <editor> 23 <firstname>Stephen</firstname><surname>Gildea</surname> 24 <affiliation><orgname>X Consortium</orgname></affiliation> 25 </editor> 26 </authorgroup> 27 <copyright><year>1994</year><holder>Network Computing Devices, Inc.</holder></copyright> 28 29<legalnotice> 30<para> 31Permission to use, copy, modify, distribute, and sell this 32documentation for any purpose is hereby granted without fee, 33provided that the above copyright notice and this permission 34notice appear in all copies. Network Computing Devices, Inc. 35makes no representations about the suitability for any purpose 36of the information in this document. This documentation is 37provided "as is" without express or implied warranty. 38</para> 39</legalnotice> 40 41<legalnotice> 42<para role="multiLicensing">Copyright © 1995 X Consortium</para> 43<para> 44Permission is hereby granted, free of charge, to any person obtaining 45a copy of this software and associated documentation files 46(the “Software”), to deal in the Software without 47restriction, including without limitation the rights to use, copy, 48modify, merge, publish, distribute, sublicense, and/or sell copies of 49the Software, and to permit persons to whom the Software is furnished 50to do so, subject to the following conditions: 51</para> 52<para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, 53EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 54MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 55IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR 56OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 57ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 58OTHER DEALINGS IN THE SOFTWARE. 59</para> 60<para> 61Except as contained in this notice, the name of the X Consortium shall 62not be used in advertising or otherwise to promote the sale, use or other 63dealings in this Software without prior written authorization from the 64X Consortium. 65</para> 66<para>X Window System is a trademark of The Open Group.</para> 67</legalnotice> 68</bookinfo> 69 70<chapter id='Record_Extension_Overview'> 71<title>Record Extension Overview</title> 72<para> 73The purpose of this extension is to support the recording and reporting of 74all core X protocol and arbitrary X extension protocol. This first section 75gives an overview of the Record extension. The following sections describe 76how to use the Record extension library. 77</para> 78 79<sect1 id='Synchronous_Playback'> 80<title>Synchronous Playback</title> 81<para> 82Environment information is generally provided to an X-based playback 83mechanism, which might use the XTest extension to synthesize input 84events. This synchronization information defines the X state prior to 85event synthesis (for example, location of the cursor, window locations 86and sizes, installed colormap, window manager running, and so on) and 87the consequences that occur after the playback mechanism synthesizes 88the event. If the user moves the mouse into the icon window and presses 89and releases a mouse button, the device events 90<function>MotionNotify</function>, <function>ButtonPress</function>, 91and <function>ButtonRelease</function> are generated by the X server. 92Because X follows an 93event-driven model, there are consequences that follow from the user 94actions, or device events, that are in the form of X protocol. As a result 95of the previous user actions, the client could generate requests such as 96<function>ImageText8</function> and <function>PolyLine</function> to the 97X server, or the X server could send non-device events such as 98<function>Expose</function> and <function>MapNotify</function> to the 99client window. Both the 100requests and non-device events that result from user actions are known 101as consequences, which can be used as a synchronization, or control point, 102during playback. That is, the playback mechanism does not generate a specific 103synthesized event until its matching synchronization condition occurs 104(for example, the window is mapped or unmapped, the cursor changes, a text 105string displays, and so on) 106</para> 107<para> 108Because it cannot be predicted what synchronization information is required 109during playback, the Record extension makes no assumptions about the intended 110use of the recorded data. Facilities exist to record any core X protocol or 111X extension protocol. Therefore, Record does not enforce a specific 112synchronization methodology. 113</para> 114</sect1> 115 116<sect1 id='Design_Approach'> 117<title>Design Approach</title> 118<para> 119The design approach of the extension is to record core X protocol and 120arbitrary X extension protocol entirely within the X server itself. When 121the extension has been requested to record specific protocol by one or more 122recording clients, the protocol data is formatted and returned to the 123recording clients. The extension provides a mechanism for capturing all 124events, including input device events that do not go to any clients. 125</para> 126</sect1> 127 128<sect1 id='Record_Clients'> 129<title>Record Clients</title> 130<para> 131The recommended communication model for a Record application is to open two 132connections to the server—one connection for recording control and one 133connection for reading recorded protocol data. 134</para> 135<para> 136Information about recording (for example, what clients to record, what 137protocol to record for each client, and so on) is stored in resources 138called record contexts (type <function>XRecordContext</function>). Most 139Record extension functions take a record context as an argument. Although 140in theory it is possible to share record contexts between applications, 141it is expected that applications will use their own context when performing 142recording operations. 143</para> 144<para> 145A client that wishes to record X protocol does so through the library 146functions defined in 147<xref linkend='Library_Extension_Requests' xrefstyle='select: title'/> 148A typical sequence of requests that a client would make is as follows: 149</para> 150<itemizedlist> 151 <listitem> 152 <para> 153<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> 154 </para> 155 <para> 156query the extension protocol version. 157 </para> 158</listitem> 159<listitem> 160 <para> 161<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 162 </para> 163 <para> 164request that the server create a record context for access by this client, 165and express interest in clients and protocol to be recorded. This request 166returns an <function>XRecord-Context</function>, which is an XID that is 167used by most other extension requests to identify the specified context. 168 </para> 169 </listitem> 170 <listitem> 171 <para> 172<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 173 </para> 174 <para> 175begin the recording and reporting of protocol data. 176 </para> 177 </listitem> 178 <listitem> 179 <para> 180<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 181 </para> 182 <para> 183end the recording and reporting of protocol data. 184 </para> 185 </listitem> 186 <listitem> 187 <para> 188<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> 189 </para> 190 <para> 191free the record context. 192 </para> 193 </listitem> 194</itemizedlist> 195 196<para> 197The header for this library is 198<<function>X11/extensions/record.h</function>>. All identifiers defined 199in the interface are supplied by this header and are prefixed with "XRecord". 200The <function>Xtst</function> library contains the 201<function>XRecord</function> functions. 202</para> 203 204</sect1> 205</chapter> 206 207<chapter id='Common_Arguments'> 208<title>Common Arguments</title> 209<para> 210The Record extension functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 211 and <xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> allow applications to 212specify the following: 213</para> 214<itemizedlist> 215 <listitem> 216 <para> 217Individual clients or sets of clients to record 218 </para> 219 </listitem> 220 <listitem> 221 <para> 222Ranges of core X protocol and X extension protocol to record for each client 223 </para> 224 </listitem> 225</itemizedlist> 226<para> 227Protocol in the ranges specified by the recording client will be recorded 228by the server. The device_events protocol type can be specified by a 229recording client although it may not be sent to a recorded client. The 230device_events type differs from delivered_events, which also can be 231specified by a recording client; delivered_events are actually delivered to 232one or more clients. These event types are discussed in 233<xref linkend='Protocol_Ranges' xrefstyle='select: title'/> 234</para> 235 236 237<para> 238The Record extension functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 239 and <xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> have the common arguments 240datum_flags, clients, and ranges, which specify whether server time 241and/or client sequence number should precede protocol elements, the 242clients or client set to record, and the protocol ranges to record, 243respectively. These are discussed in the following sections. 244</para> 245 246<sect1 id='Datum_Flags'> 247<title>Datum Flags</title> 248<para> 249The datum_flags argument is a set of flags OR’ed together to specify options 250for the record context. Specify zero to disable all the options. 251</para> 252 253<para> 254The <function>XRecordFromServerTime</function> flag specifies that 255<function>XRecordInterceptData</function> structures with a category of 256<function>XRecordFromServer</function> will have a server_time field specific to each 257protocol element. 258</para> 259 260<para> 261The <function>XRecordFromClientTime</function> flag specifies that 262<function>XRecordInterceptData</function> structures with a category of 263<function>XRecordFromClient</function> will have a server_time field specific 264to each protocol element. 265</para> 266 267<para> 268The <function>XRecordFromClientSequence</function> flag specifies that 269<function>XRecordInterceptData</function> structures with a category of 270<function>XRecordFromClient</function> or 271<function>XRecordClientDied</function> will have a valid client_seq field. 272</para> 273</sect1> 274 275<sect1 id='Selecting_Clients'> 276<title>Selecting Clients</title> 277 278<para> 279The clients argument is a pointer to an array of 280<function>XRecordClientSpec</function>. 281<function>XRecordClientSpec</function> is an integral type that holds a 282resource ID, a client resource ID base, or one of the client set constants 283defined below. 284</para> 285<para> 286Duplicate elements in the array are ignored by the functions, and if any 287element in the array is not valid, a 288<function>BadMatch</function> 289error results. A resource ID references the client that created that 290resource. The client set may be one of the following constants: 291<function>XRecordCurrentClients</function>, 292<function>XRecordFutureClients</function>, or 293<function>XRecordAllClients</function>. 294</para> 295<para> 296If the element in the array identifies a particular client, protocol 297specified by the ranges argument will be recorded by the server. The 298recorded protocol data will not be returned to the recording client until 299the record context has been enabled. This is described in 300<xref linkend='Data_Transfer' xrefstyle='select: title'/> 301</para> 302<para> 303If the element is <function>XRecordCurrentClients</function>, the protocol 304ranges specified by the ranges argument, except for device_events, are 305associated with each current client connection. If the element is 306<function>XRecordFutureClients</function>, the 307protocol ranges specified by the ranges argument are associated with each new 308client connection. If the element is 309<function>XRecordAllClients</function>, 310the protocol ranges specified by the ranges argument are associated with 311each current client connection and with each new client connection. 312When the context is enabled, the data connection is unregistered if it 313was registered. If the context is enabled, 314<function>XRecordCurrentClients</function> and 315<function>XRecordAllClients</function> 316silently exclude the recording data connection. It is an error to explicitly 317register the data connection. 318</para> 319</sect1> 320<sect1 id='Protocol_Ranges'> 321<title>Protocol Ranges</title> 322 323<para> 324The functions <xref linkend='XRecordCreateContext' xrefstyle='select: title'/> and 325<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> have another common argument, 326ranges, which is an array of pointers to <function>XRecordRange</function> 327structures. Each structure contains ranges of numeric values for each of 328the protocol types that can be specified and recorded individually by the 329Record extension. An <function>XRecordRange</function> structure must be 330allocated by the Record library using the 331<function>XRecordAllocRange</function> function. 332</para> 333<para> 334The <function>XRecordRange</function> typedef is a structure with the 335following members: 336</para> 337 338<literallayout remap='Ds'> 339XRecordRange: 340 XRecordRange8 core_requests /* core X requests */ 341 XRecordRange8 core_replies /* core X replies */ 342 XRecordExtRange ext_requests /* extension requests */ 343 XRecordExtRange ext_replies /* extension replies */ 344 XRecordRange8 delivered_events /* delivered core and ext events */ 345 XRecordRange8 device_events /* all core and ext device events */ 346 XRecordRange8 errors /* core X and X ext errors */ 347 Bool client_started /* connection setup reply from server */ 348 Bool client_died /* notification of client disconnect */ 349</literallayout> 350 351<para> 352The types used in 353<function>XRecordRange</function> 354members are defined as follows. The 355<function>XRecordRange8</function> 356typedef is a structure with the following members: 357</para> 358 359<literallayout remap='Ds'> 360XRecordRange8: 361 unsigned char first 362 unsigned char last 363</literallayout> 364 365<para> 366The 367<function>XRecordRange16</function> 368typedef is a structure with the following members: 369</para> 370 371<literallayout remap='Ds'> 372XRecordRange16: 373 unsigned short first 374 unsigned short last 375</literallayout> 376 377<para> 378The 379<function>XRecordExtRange</function> 380typedef is a structure with the following members: 381</para> 382 383<literallayout remap='Ds'> 384XRecordExtRange: 385 XRecordRange8 ext_major 386 XRecordRange16 ext_minor 387</literallayout> 388 389<para> 390If any of the values specified in 391<function>XRecordRange</function> 392is invalid, a 393<function>BadValue</function> 394error results. 395</para> 396 397<para> 398The core_requests member specifies the range of core X protocol 399requests to record. Core X protocol requests with a major opcode 400that is between first and last, inclusive, will be 401recorded. A 402<function>BadValue</function> 403error results if the value of first is greater than the value of last. 404If the values of both first and last are zero, no core 405X protocol requests will be recorded. 406</para> 407 408<para> 409The core_replies member specifies the range of replies resulting 410from core X protocol requests to record. Replies that result from 411core X protocol requests with a major opcode between first 412and last, inclusive, will be recorded. A 413<function>BadValue</function> 414error results if the value of first is greater than the value of last. 415If the values of both first and last are zero, no core X protocol 416replies will be recorded. 417</para> 418 419<para> 420The ext_requests member specifies the range of X extension 421requests to record. X extension requests with a major opcode 422between ext_major.first and ext_major.last, and with a 423minor opcode 424between ext_minor.first and ext_minor.last, inclusive, will be 425recorded. A 426<function>BadValue</function> 427error results 428if the value of ext_major.first is greater than the value of 429ext_major.last or if the value of ext_minor.first is 430greater than the value of ext_minor.last. If the values of both 431ext_major.first 432and ext_major.last are zero, 433no X extension requests will be recorded. 434</para> 435 436<para> 437The ext_replies member specifies the range of replies resulting 438from X extension requests to record. Replies that result from an X 439extension request with a major opcode between 440ext_major.first and 441ext_major.last, and a minor opcode that is between 442ext_minor.first and ext_minor.last will be recorded. A 443<function>BadValue</function> 444error results 445if the value of ext_major.first is greater than the value of 446ext_major.last or if the value of ext_minor.first is greater than 447the value of ext_minor.last. If the values of both 448ext_major.first and ext_major.last are zero, no X extension 449replies will be recorded. 450</para> 451 452<para> 453The delivered_events member specifies the range of both core 454X events and X extension events to record. These events are 455delivered to at least one client. Core X events and X extension events 456with a code value between first and last inclusive will be recorded. A 457<function>BadValue</function> 458error results if the value of first is greater than the value of last. 459If the values of first and last are zero, no events will be recorded. 460</para> 461 462<para> 463The device_events member specifies the range of both core X device 464events and X extension device events to record. These events may or 465may not be delivered to a client. Core X device events and X extension 466device events with a code value between first and last inclusive that 467are not delivered to any clients will be recorded. A 468<function>BadValue</function> 469error results if the value of first is greater than the value of last. A 470<function>BadValue</function> 471error results if first is less than two or last is less than two, except 472that if first and last are zero, no events will be recorded. 473</para> 474 475<para> 476The errors member specifies the range of both core X errors and X 477extension errors to record. Core X errors and X extension errors with 478a code value between first and last inclusive will be 479recorded. A 480<function>BadValue</function> 481error results if the value of first is greater than the value of last. 482If the values of first and last are zero, no errors will be recorded. 483</para> 484 485<para> 486A value of 487<function>True</function> 488for the client_started member specifies the 489connection setup reply from the server to new clients. If 490<function>False</function> 491the connection setup reply is not specified by this 492<function>XRecordRange</function> 493</para> 494 495<para> 496A value of 497<function>True</function> 498for the client_died member specifies 499notification when a client disconnects. If 500<function>False</function> 501notification when a client disconnects is not specified by this 502<function>XRecordRange</function> 503</para> 504</sect1> 505</chapter> 506 507<chapter id='Library_Extension_Requests'> 508<title>Library Extension Requests</title> 509 510<para> 511Recording operations are accessed by programs through the use of 512new protocol requests. The following functions are provided as extensions 513to Xlib. An Xlib error results if 514an extension request is made to an X server that does not support the 515Record extension. Note that any of the extension protocol requests may generate 516<function>BadAlloc</function> 517or 518<function>BadLength</function> 519errors. 520</para> 521 522<sect1 id='Query_Extension_Version'> 523<title>Query Extension Version</title> 524 525<para> 526An application uses the 527<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> 528function to determine 529the version of the Record extension protocol supported by an X server. 530</para> 531 532<funcsynopsis id='XRecordQueryVersion'> 533<funcprototype> 534 <funcdef>Status <function>XRecordQueryVersion</function></funcdef> 535 <paramdef>Display <parameter> *display</parameter></paramdef> 536 <paramdef>int <parameter> cmajor_return</parameter></paramdef> 537 <paramdef>int <parameter> cminor_return</parameter></paramdef> 538</funcprototype> 539</funcsynopsis> 540 541<variablelist remap='IP'> 542 <varlistentry> 543 <term><emphasis remap='I'>display</emphasis></term> 544 <listitem><para>Returns the connection to the X server.</para></listitem> 545 </varlistentry> 546 <varlistentry> 547 <term><emphasis remap='I'>cmajor_return</emphasis></term> 548 <listitem><para>Returns the extension protocol major version in use.</para></listitem> 549 </varlistentry> 550 <varlistentry> 551 <term><emphasis remap='I'>cminor_return</emphasis></term> 552 <listitem><para>Returns the extension protocol minor version in use.</para></listitem> 553 </varlistentry> 554</variablelist> 555 556<para> 557The 558<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> 559function returns the major and minor protocol version numbers supported by 560the server. 561<xref linkend='XRecordQueryVersion' xrefstyle='select: title'/> 562returns nonzero (success) only if the returned version numbers are 563common to both the library and the server; otherwise, it returns zero. 564</para> 565</sect1> 566 567<sect1 id='Create_and_Modify_Context'> 568<title>Create and Modify Context</title> 569 570<para> 571An application uses the 572<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 573function to create a record context. At the time the record context is 574created by the recording client, the clients to be recorded and the 575protocol to record for each client may be specified. 576</para> 577 578<funcsynopsis id='XRecordCreateContext'> 579<funcprototype> 580 <funcdef>XRecordContext <function>XRecordCreateContext</function></funcdef> 581 <paramdef>Display <parameter> *display</parameter></paramdef> 582 <paramdef>int <parameter> datum_flags</parameter></paramdef> 583 <paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef> 584 <paramdef>int <parameter> nclients</parameter></paramdef> 585 <paramdef>XRecordRange <parameter> *ranges</parameter></paramdef> 586 <paramdef>int <parameter> nranges</parameter></paramdef> 587</funcprototype> 588</funcsynopsis> 589 590<variablelist remap='IP'> 591 <varlistentry> 592 <term><emphasis remap='I'>display</emphasis></term> 593 <listitem><para>Returns the connection to the X server.</para></listitem> 594 </varlistentry> 595 <varlistentry> 596 <term><emphasis remap='I'>datum_flags</emphasis></term> 597 <listitem><para>Specifies whether detailed time or sequence info should be sent.</para></listitem> 598 </varlistentry> 599 <varlistentry> 600 <term><emphasis remap='I'>clients</emphasis></term> 601 <listitem><para>Specifies the clients to record.</para></listitem> 602 </varlistentry> 603 <varlistentry> 604 <term><emphasis remap='I'>nclients</emphasis></term> 605 <listitem><para>Specifies the number of clients.</para></listitem> 606 </varlistentry> 607 <varlistentry> 608 <term><emphasis remap='I'>ranges</emphasis></term> 609 <listitem><para>Specifies the protocol ranges to record.</para></listitem> 610 </varlistentry> 611 <varlistentry> 612 <term><emphasis remap='I'>nranges</emphasis></term> 613 <listitem><para>Specifies the number of protocol ranges.</para></listitem> 614 </varlistentry> 615</variablelist> 616 617<para> 618The 619<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 620function creates a record context and returns an 621<function>XRecordContext</function> 622which is then used in the other Record library calls. This request is 623typically executed by the recording client over its control connection to 624the X server. The datum_flags specifies whether server time and/or client 625sequence number should precede protocol elements recorded by context ( 626<xref linkend='Datum_Flags' xrefstyle='select: title'/> 627). When a clients element identifies a particular client, the client is added 628to the context and the protocol to record for that client is set to the 629union of all ranges. When a clients element is 630<function>XRecordCurrentClients</function> 631<function>XRecordFutureClients</function> 632or 633<function>XRecordAllClients</function> 634the actions described in 635<xref linkend='Selecting_Clients' xrefstyle='select: title'/> 636are performed. 637</para> 638 639<para> 640<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 641returns zero if the request failed. 642<xref linkend='XRecordCreateContext' xrefstyle='select: title'/> 643can generate 644<function>BadIDChoice</function> 645<function>BadMatch</function> 646and 647<function>BadValue</function> 648errors. 649</para> 650 651<para>The ranges argument is an 652<function>XRecordRange</function> 653array, that is, an array 654of pointers. The structures the elements point to shall be allocated 655by calling 656<function>XRecordAllocRange</function></para> 657 658<literallayout remap='FD'> 659XRecordRange * 660XRecordAllocRange(void) 661</literallayout> <!-- remap='FN' --> 662 663<para> 664The 665<function>XRecordAllocRange</function> 666function 667allocates and returns an 668<function>XRecordRange</function> 669structure. 670The structure is initialized to specify no protocol. 671The function returns NULL if the structure allocation fails. 672The application can free the structure by calling 673<olink targetdoc='libX11' targetptr='XFree'><function>XFree</function></olink> 674</para> 675 676<sect2 id='Additions'> 677<title>Additions</title> 678 679<para> 680An application uses the 681<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> 682function to modify a previously created 683record context, by adding clients or modifying the recorded protocol, 684typically over its control connection to the X server. 685</para> 686 687<funcsynopsis id='XRecordRegisterClients'> 688<funcprototype> 689 <funcdef>Status <function>XRecordRegisterClients</function></funcdef> 690 <paramdef>Display <parameter> *display</parameter></paramdef> 691 <paramdef>XRecordContext <parameter> context</parameter></paramdef> 692 <paramdef>int <parameter> datum_flags</parameter></paramdef> 693 <paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef> 694 <paramdef>int <parameter> nclients</parameter></paramdef> 695 <paramdef>XRecordRange <parameter> *ranges</parameter></paramdef> 696 <paramdef>int <parameter> nranges</parameter></paramdef> 697</funcprototype> 698</funcsynopsis> 699 700<variablelist remap='IP'> 701 <varlistentry> 702 <term><emphasis remap='I'>display</emphasis></term> 703 <listitem><para>Returns the connection to the X server.</para></listitem> 704 </varlistentry> 705 <varlistentry> 706 <term><emphasis remap='I'>context</emphasis></term> 707 <listitem><para>Specifies the record context to modify.</para></listitem> 708 </varlistentry> 709 <varlistentry> 710 <term><emphasis remap='I'>datum_flags</emphasis></term> 711 <listitem><para>Specifies whether detailed time or sequence info should be sent.</para></listitem> 712 </varlistentry> 713 <varlistentry> 714 <term><emphasis remap='I'>clients</emphasis></term> 715 <listitem><para>Specifies the clients to record.</para></listitem> 716 </varlistentry> 717 <varlistentry> 718 <term><emphasis remap='I'>nclients</emphasis></term> 719 <listitem><para>Specifies the number of clients.</para></listitem> 720 </varlistentry> 721 <varlistentry> 722 <term><emphasis remap='I'>ranges</emphasis></term> 723 <listitem><para>Specifies the protocol ranges to record.</para></listitem> 724 </varlistentry> 725 <varlistentry> 726 <term><emphasis remap='I'>nranges</emphasis></term> 727 <listitem><para>Specifies the number of protocol ranges.</para></listitem> 728 </varlistentry> 729</variablelist> 730 731<para> 732The datum_flags specifies whether server time and/or client sequence number 733should precede protocol elements for all clients recorded by context (See 734<xref linkend='Datum_Flags' xrefstyle='select: title'/> 735). When a clients element identifies a particular client and the client is 736not yet targeted for recording in the given context, the client is added 737to the set of clients to record, and the protocol to record for that client 738is set to the union of all ranges. When the client is 739already targeted for recording, the protocol to record for that client 740is set to the union of all ranges. When the element is 741<function>XRecordCurrentClients</function> 742<function>XRecordFutureClients</function> 743or 744<function>XRecordAllClients</function> 745the actions described in 746<xref linkend='Selecting_Clients' xrefstyle='select: title'/> 747are performed. 748</para> 749 750<para> 751<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> 752returns zero if the request failed; otherwise, it 753returns nonzero. 754</para> 755 756<para> 757<xref linkend='XRecordRegisterClients' xrefstyle='select: title'/> 758can generate 759<function>XRecordBadContext</function> 760<function>BadMatch</function> 761and 762<function>BadValue</function> 763errors. 764</para> 765</sect2> 766 767<sect2 id='Deletions'> 768<title>Deletions</title> 769 770<para> 771An application uses the 772<function>XRecordUnregisterClients</function> 773function to delete clients from a previously created 774record context, typically over its control connection to the X server. 775</para> 776 777<funcsynopsis id='XRecordUnRegisterClients'> 778<funcprototype> 779 <funcdef>Status <function>XRecordUnRegisterClients</function></funcdef> 780 <paramdef>Display <parameter> *display</parameter></paramdef> 781 <paramdef>XRecordContext <parameter> context</parameter></paramdef> 782 <paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef> 783 <paramdef>int <parameter> nclients</parameter></paramdef> 784</funcprototype> 785</funcsynopsis> 786 787<variablelist remap='IP'> 788 <varlistentry> 789 <term><emphasis remap='I'>display</emphasis></term> 790 <listitem><para>Returns the connection to the X server.</para></listitem> 791 </varlistentry> 792 <varlistentry> 793 <term><emphasis remap='I'>context</emphasis></term> 794 <listitem><para>Specifies the record context to modify.</para></listitem> 795 </varlistentry> 796 <varlistentry> 797 <term><emphasis remap='I'>clients</emphasis></term> 798 <listitem><para>Specifies the clients to stop recording.</para></listitem> 799 </varlistentry> 800 <varlistentry> 801 <term><emphasis remap='I'>nclients</emphasis></term> 802 <listitem><para>Specifies the number of clients.</para></listitem> 803 </varlistentry> 804</variablelist> 805 806<para> 807When an element in clients identifies a particular client, and the 808specified client is already targeted for recording in the given 809context, the client and the set of protocol to record for that 810client are deleted from the context. If the specified client is not 811targeted for recording, then no action is performed. 812</para> 813 814<para> 815When the element is 816<function>XRecordCurrentClients</function> 817all clients currently targeted for recording in context and their 818corresponding sets of protocol to record are deleted from context. 819</para> 820 821<para> 822When the item is 823<function>XRecordFutureClients</function> 824any future client connections will not automatically be targeted for 825recording in context. 826</para> 827 828<para> 829When the element is 830<function>XRecordAllClients</function> 831all clients currently targeted for recording in context and their 832corresponding sets of protocol to record are deleted from context. 833Any future client connections will not automatically be targeted 834for recording in context. 835</para> 836 837<para> 838<function>XRecordUnregisterClients</function> 839returns zero if the request failed; otherwise, it returns nonzero. 840</para> 841 842<para> 843<function>XRecordUnregisterClients</function> 844can generate 845<function>XRecordBadContext</function> 846<function>BadMatch</function> 847and 848<function>BadValue</function> 849errors.</para> 850</sect2> 851</sect1> 852 853<sect1 id='Query_Context_State'> 854<title>Query Context State</title> 855 856<para> 857An application uses the 858<xref linkend='XRecordGetContext' xrefstyle='select: title'/> 859function to query the current state of a record context, typically over 860its control connection to the X server. 861</para> 862 863<funcsynopsis id='XRecordGetContext'> 864<funcprototype> 865 <funcdef>Status <function>XRecordGetContext</function></funcdef> 866 <paramdef>Display <parameter> *display</parameter></paramdef> 867 <paramdef>XRecordContext <parameter> context</parameter></paramdef> 868 <paramdef>XRecordState <parameter> **state_return</parameter></paramdef> 869</funcprototype> 870</funcsynopsis> 871 872<variablelist remap='IP'> 873 <varlistentry> 874 <term><emphasis remap='I'>display</emphasis></term> 875 <listitem><para>Specifies the connection to the X server.</para></listitem> 876 </varlistentry> 877 <varlistentry> 878 <term><emphasis remap='I'>context</emphasis></term> 879 <listitem><para>Specifies the record context to query.</para></listitem> 880 </varlistentry> 881 <varlistentry> 882 <term><emphasis remap='I'>state_return</emphasis></term> 883 <listitem><para>Specifies the address of a variable into which 884the function stores a pointer to the current state of the record context. 885 </para></listitem> 886 </varlistentry> 887</variablelist> 888 889<para> 890The 891<function>XRecordState</function> 892typedef returned by 893<xref linkend='XRecordGetContext' xrefstyle='select: title'/> 894is a structure with the following members: 895</para> 896 897<literallayout remap='Ds'> 898XRecordState: 899 Bool enabled 900 int datum_flags 901 unsigned long nclients 902 XRecordClientInfo **client_info 903</literallayout> 904 905<para> 906The enabled member is set to the state of data transfer and is 907<function>True</function> 908when the recording client has asked that recorded data be sent; 909otherwise it is 910<function>False</function> 911The datum_flags member is set to the value of these flags for this context. 912The nclients member is set to the number of 913<function>XRecordClientInfo</function> 914structures returned. The client_info member is an array of pointers to 915<function>XRecordClientInfo</function> 916structures that contain the protocol to record for each targeted client. The 917<function>XRecordClientInfo</function> 918typedef is a structure with the following members: 919</para> 920 921<literallayout remap='Ds'> 922XRecordClientInfo: 923 XRecordClientSpec client 924 unsigned long nranges 925 XRecordRange **ranges 926</literallayout> 927 928<para> 929The client member either identifies a client targeted for recording 930or is set to 931<function>XRecordFutureClients</function> 932to describe how future clients will be automatically targeted for recording. 933The nranges member is set to the number of protocol 934ranges to be recorded for the specified client. The ranges member 935is an array of pointers to 936<function>XRecordRange</function> 937structures, which specify the protocol ranges to record. 938</para> 939 940<para> 941<xref linkend='XRecordGetContext' xrefstyle='select: title'/> 942returns zero if the request failed; otherwise, it returns nonzero. 943The context argument must specify a valid 944<function>XRecordContext</function> 945or a 946<function>XRecordBadContext</function> 947error results. 948</para> 949 950<para> 951Recording clients should use the 952<xref linkend='XRecordFreeState' xrefstyle='select: title'/> 953function to free the state data returned by 954<xref linkend='XRecordGetContext' xrefstyle='select: title'/> 955</para> 956 957<funcsynopsis id='XRecordFreeState'> 958<funcprototype> 959 <funcdef>void <function>XRecordFreeState</function></funcdef> 960 <paramdef>XRecordState <parameter> *state</parameter></paramdef> 961</funcprototype> 962</funcsynopsis> 963 964<variablelist remap='IP'> 965 <varlistentry> 966 <term><emphasis remap='I'>state</emphasis></term> 967 <listitem><para>Specifies the structure that is to be freed.</para></listitem> 968 </varlistentry> 969</variablelist> 970 971<para> 972<xref linkend='XRecordFreeState' xrefstyle='select: title'/> 973frees the data pointed to by state. If the argument does not match an 974<function>XRecordState</function> 975pointer returned from a successful call to 976<xref linkend='XRecordGetContext' xrefstyle='select: title'/> 977or if 978<xref linkend='XRecordFreeState' xrefstyle='select: title'/> 979has already been called with it, the behavior is undefined. 980</para> 981</sect1> 982 983<sect1 id='Data_Transfer'> 984<title>Data Transfer</title> 985 986<para> 987An application uses the 988<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 989and 990<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 991functions to change the state of data transfer 992between the X server and the recording client. These functions allow 993the application to start recording and reporting of protocol data 994and to stop recording and reporting of protocol data, respectively. 995</para> 996 997<sect2 id='Enable_Context'> 998<title>Enable Context</title> 999 1000<para> 1001To direct the X server to record and report protocol, a program uses 1002<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1003typically over its data connection to the X 1004server. The reporting of recorded protocol back to the recording client 1005is handled by the following data structures and procedure definitions. 1006Each recorded protocol element is reported to the recording client through an 1007<function>XRecordInterceptData</function> 1008typedef, a structure with the following members: 1009</para> 1010 1011<literallayout remap='Ds'> 1012XRecordInterceptData: 1013 XID id_base 1014 Time server_time 1015 unsigned long client_seq 1016 int category 1017 Bool client_swapped 1018 unsigned char *data 1019 unsigned long data_len 1020</literallayout> 1021 1022<para> 1023The id_base member is set to the resource identifier base sent to the 1024client in the connection setup reply and therefore identifies the client 1025being recorded, except when the recorded protocol data is a device 1026event that may have not been delivered to a client. In this case, 1027id_base is set to zero. The server_time member 1028is set to the time of the server when the protocol was recorded. 1029It is the time that was attached to this protocol element in the reply, 1030if so specified by datum_flags, 1031or else the time from the header of the reply that contained 1032this protocol element. 1033The client_seq member is the sequence number of the recorded 1034client's most recent request processed by the server at the time this 1035protocol element was recorded, if this information were included in the 1036recorded data; otherwise client_seq is 0. 1037The category member is set to one of the following values: 1038<function>XRecordStartOfData</function> 1039<function>XRecordFromServer</function> 1040<function>XRecordFromClient</function> 1041<function>XRecordClientStarted</function> 1042<function>XRecordClientDied</function> 1043or 1044<function>XRecordEndOfData</function> 1045<function>XRecordStartOfData</function> 1046is immediately sent as the first reply to confirm that the context is enabled. 1047<function>XRecordFromClient</function> 1048indicates the protocol 1049data is from the recorded client to the server (requests). 1050<function>XRecordFromServer</function> 1051indicates the protocol data is from the server to the recorded client 1052(replies, errors, events, or device events). 1053<function>XRecordClientStarted</function> 1054indicates that the protocol data is the connection setup reply from the server. 1055<function>XRecordClientDied</function> 1056indicates that the recorded client has closed its connection 1057to the X server; there is no protocol data. 1058<function>XRecordEndOfData</function> 1059indicates that the context has been disabled and that 1060this is the last datum. It does not correspond to any protocol or 1061state change in a recorded client. There is no protocol data. 1062</para> 1063 1064<para> 1065The client_swapped member is set to 1066<function>True</function> 1067if the byte order of the client being recorded is swapped relative to 1068the recording client; otherwise, it is set to 1069<function>False</function> 1070All recorded protocol data is returned in the byte order of the recorded 1071client. Therefore, recording clients are responsible for all byte swapping, 1072if required. Device events are in the byte order of the recording client. 1073For replies of category 1074<function>XRecordStartOfData</function> 1075and 1076<function>XRecordEndOfData</function> 1077client_swapped is set according 1078to the byte order of the server relative to the recording client. 1079</para> 1080 1081<para> 1082The data member contains the actual recorded protocol data. 1083When category is set to 1084<function>XRecordStartOfData</function> 1085<function>XRecordClientDied</function> 1086or 1087<function>XRecordEndOfData</function> 1088no protocol data are contained in data. 1089</para> 1090 1091 1092<!-- copied exactly from the protocol document --> 1093<para> 1094For the core X events 1095<function>KeyPress</function> 1096<function>KeyRelease</function> 1097<function>ButtonPress</function> 1098and 1099<function>ButtonRelease</function>, 1100the fields of a device event that contain 1101valid information are time and detail. For the core X event 1102<function>MotionNotify</function> 1103the fields of a device event that contain valid information are time, root, 1104root-x and root-y. 1105The time field refers to the time the event was generated by the device. 1106</para> 1107 1108<para>For the extension input device events 1109<function>DeviceKeyPress</function> 1110<function>DeviceKeyRelease</function> 1111<function>DeviceButtonPress</function> 1112and 1113<function>DeviceButtonRelease</function> 1114the fields of a device event that contain valid information are 1115device, time, and detail. For 1116<function>DeviceMotionNotify</function> 1117the valid device event fields are device and time. 1118For the extension input device events 1119<function>ProximityIn</function> 1120and 1121<function>ProximityOut</function> 1122the fields of a device event that contain valid 1123information are device and time. For the extension input device event 1124<function>DeviceValuator</function> 1125the fields of a device event that contain valid information are 1126device, num_valuators, first_valuator, and valuators. 1127The time field refers to the time the event was generated by the device. 1128</para> 1129 1130 1131<para> 1132The data_len member is set to the length of the actual recorded protocol 1133data in 4-byte units. 1134</para> 1135 1136<para> 1137When the context has been enabled, protocol data the recording client has 1138previously expressed interest in is recorded and returned to the 1139recording client via multiple replies. Because the X server batches 1140the recorded data, more than one protocol element may be contained 1141in the same reply packet. When a reply is received, a procedure of type 1142<function>XRecordInterceptProc</function> 1143is called for each protocol element in the reply. 1144</para> 1145 1146<funcsynopsis id='XRecordInterceptProc'> 1147<funcprototype> 1148 <funcdef>typedef void <function>(*XRecordInterceptProc)</function></funcdef> 1149 <paramdef>XPointer<parameter> closure</parameter></paramdef> 1150 <paramdef>XRecordInterceptData<parameter> *recorded_data</parameter></paramdef> 1151</funcprototype> 1152</funcsynopsis> 1153 1154<variablelist remap='IP'> 1155 <varlistentry> 1156 <term><emphasis remap='I'>closure</emphasis></term> 1157 <listitem><para>Pointer that was passed in when the context was enabled.</para></listitem> 1158 </varlistentry> 1159 <varlistentry> 1160 <term><emphasis remap='I'>recorded_data</emphasis></term> 1161 <listitem><para>A protocol element recorded by the server extension.</para></listitem> 1162 </varlistentry> 1163</variablelist> 1164 1165<para> 1166This callback may use the control display connection (or any display 1167connection other than the data connection). 1168</para> 1169 1170<para> 1171Recording clients should use the 1172<xref linkend='XRecordFreeData' xrefstyle='select: title'/> 1173function to free the 1174<function>XRecordInterceptData</function> 1175structure. 1176</para> 1177 1178<funcsynopsis id='XRecordEnableContext'> 1179<funcprototype> 1180 <funcdef>Status <function>XRecordEnableContext</function></funcdef> 1181 <paramdef>Display<parameter> *display</parameter></paramdef> 1182 <paramdef>XRecordContext<parameter> context</parameter></paramdef> 1183 <paramdef>XRecordInterceptProc<parameter> callback</parameter></paramdef> 1184 <paramdef>XPointer<parameter> closure</parameter></paramdef> 1185</funcprototype> 1186</funcsynopsis> 1187 1188<variablelist remap='IP'> 1189 <varlistentry> 1190 <term><emphasis remap='I'>display</emphasis></term> 1191 <listitem><para>Specifies the connection to the X server.</para></listitem> 1192 </varlistentry> 1193 <varlistentry> 1194 <term><emphasis remap='I'>context</emphasis></term> 1195 <listitem><para>Specifies the record context to enable.</para></listitem> 1196 </varlistentry> 1197 <varlistentry> 1198 <term><emphasis remap='I'>callback</emphasis></term> 1199 <listitem><para>Specifies the function to be called for each protocol element received.</para></listitem> 1200 </varlistentry> 1201 <varlistentry> 1202 <term><emphasis remap='I'>closure</emphasis></term> 1203 <listitem><para>Specifies data passed to callback.</para></listitem> 1204 </varlistentry> 1205</variablelist> 1206 1207 1208<para> 1209<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1210enables data transfer between the recording client and 1211the X server. All core and extension protocol received from or sent to 1212targeted clients that the recording client has expressed 1213interest in will be recorded and reported to the recording client. 1214</para> 1215 1216<para> 1217<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1218returns zero if the request failed; otherwise, it 1219returns nonzero. The context argument must specify a valid 1220<function>XRecordContext</function> 1221or a 1222<function>XRecordBadContext</function> 1223error results. The error 1224<function>BadMatch</function> 1225results when data transfer is already enabled on the given context. 1226</para> 1227</sect2> 1228 1229<sect2 id='Enable_Context_Asynchronously'> 1230<title>Enable Context Asynchronously</title> 1231 1232<para>Because 1233<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1234does not return until 1235<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 1236is executed on the control connection, a nonblocking interface in 1237addition to 1238<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1239is provided. This interface also 1240enables data transfer; however, it does not block. 1241</para> 1242 1243<para> 1244This interface is defined as follows: 1245</para> 1246 1247<funcsynopsis id='XRecordEnableContextAsync'> 1248<funcprototype> 1249 <funcdef>Status <function>XRecordEnableContextAsync</function></funcdef> 1250 <paramdef>Display<parameter> *display</parameter></paramdef> 1251 <paramdef>XRecordContext<parameter> context</parameter></paramdef> 1252 <paramdef>XRecordInterceptProc<parameter> callback</parameter></paramdef> 1253 <paramdef>XPointer<parameter> closure</parameter></paramdef> 1254</funcprototype> 1255</funcsynopsis> 1256 1257<variablelist remap='IP'> 1258 <varlistentry> 1259 <term><emphasis remap='I'>display</emphasis></term> 1260 <listitem><para>Specifies the connection to the X server.</para></listitem> 1261 </varlistentry> 1262 <varlistentry> 1263 <term><emphasis remap='I'>context</emphasis></term> 1264 <listitem><para>Specifies the record context to enable.</para></listitem> 1265 </varlistentry> 1266 <varlistentry> 1267 <term><emphasis remap='I'>callback</emphasis></term> 1268 <listitem><para>Specifies the function to be called for each protocol element received.</para></listitem> 1269 </varlistentry> 1270 <varlistentry> 1271 <term><emphasis remap='I'>closure</emphasis></term> 1272 <listitem><para>Specifies data passed to callback.</para></listitem> 1273 </varlistentry> 1274</variablelist> 1275 1276<para> 1277<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/> 1278enables data transfer between the recording 1279client and the X server just as 1280<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1281does. Unlike 1282<xref linkend='XRecordEnableContext' xrefstyle='select: title'/> 1283it does not wait for the context to be disabled 1284before returning; 1285<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/> 1286returns as soon as the 1287<function>XRecordStartOfData</function> 1288reply has been received and processed. 1289</para> 1290 1291<para> 1292<xref linkend='XRecordEnableContextAsync' xrefstyle='select: title'/> 1293returns zero if it could not allocate the 1294necessary memory and nonzero if it sent the request successfully to 1295the server. The context argument must specify a valid 1296<function>XRecordContext</function> 1297or a 1298<function>XRecordBadContext</function> 1299error results. The error 1300<function>BadMatch</function> 1301results when data transfer is already enabled. 1302</para> 1303 1304<para> 1305Each time it reads data from the server connection, Xlib will check 1306for incoming replies and call <emphasis remap='I'>callback</emphasis> 1307as necessary. The application may direct Xlib explicitly to check 1308for Record data with the 1309<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/> 1310function. 1311</para> 1312 1313<funcsynopsis id='XRecordProcessReplies'> 1314<funcprototype> 1315 <funcdef>void <function>XRecordProcessReplies</function></funcdef> 1316 <paramdef>Display<parameter> *display</parameter></paramdef> 1317</funcprototype> 1318</funcsynopsis> 1319 1320<variablelist remap='IP'> 1321 <varlistentry> 1322 <term><emphasis remap='I'>display</emphasis></term> 1323 <listitem><para>Specifies the connection to the X server.</para></listitem> 1324 </varlistentry> 1325</variablelist> 1326 1327<para> 1328<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/> 1329will check for any replies that have not yet 1330been processed by the application. The asynchronous callback will be called 1331as appropriate. 1332<xref linkend='XRecordProcessReplies' xrefstyle='select: title'/> 1333returns when all immediately 1334available replies have been processed. It does not block. 1335</para> 1336 1337<para>To free the data passed to the 1338<function>XRecordInterceptProc</function> 1339callback, use 1340<xref linkend='XRecordFreeData' xrefstyle='select: title'/></para> 1341 1342<funcsynopsis id='XRecordFreeData'> 1343<funcprototype> 1344 <funcdef>void <function>XRecordFreeData</function></funcdef> 1345 <paramdef>XRecordInterceptData<parameter> *data</parameter></paramdef> 1346</funcprototype> 1347</funcsynopsis> 1348 1349<variablelist remap='IP'> 1350 <varlistentry> 1351 <term><emphasis remap='I'>data</emphasis></term> 1352 <listitem><para>Specifies the structure that is to be freed.</para></listitem> 1353 </varlistentry> 1354</variablelist> 1355 1356 1357<para> 1358<xref linkend='XRecordFreeData' xrefstyle='select: title'/> 1359frees the data pointed to by data. If the argument does not match an 1360<function>XRecordInterceptData</function> 1361pointer earlier passed to an 1362<function>XRecordInterceptProc</function> 1363callback or if 1364<xref linkend='XRecordFreeData' xrefstyle='select: title'/> 1365has already been called with it, the behavior is undefined. 1366</para> 1367</sect2> 1368 1369<sect2 id='Disable_Context'> 1370<title>Disable Context</title> 1371 1372<para> 1373To direct the X server to halt the reporting of recorded protocol, the 1374program executes 1375<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 1376typically over its control connection to the X server. 1377</para> 1378 1379<funcsynopsis id='XRecordDisableContext'> 1380<funcprototype> 1381 <funcdef>Status <function>XRecordDisableContext</function></funcdef> 1382 <paramdef>Display<parameter> *display</parameter></paramdef> 1383 <paramdef>XRecordContext<parameter> context</parameter></paramdef> 1384</funcprototype> 1385</funcsynopsis> 1386 1387<variablelist remap='IP'> 1388 <varlistentry> 1389 <term><emphasis remap='I'>display</emphasis></term> 1390 <listitem><para>Specifies the connection to the X server.</para></listitem> 1391 </varlistentry> 1392 <varlistentry> 1393 <term><emphasis remap='I'>context</emphasis></term> 1394 <listitem><para>Specifies the record context to disable.</para></listitem> 1395 </varlistentry> 1396</variablelist> 1397 1398 1399<para> 1400The 1401<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 1402function disables context, stopping all recording over its data connection. 1403Any complete protocol elements for context that were buffered in the 1404server will be sent to the recording client rather than being discarded. 1405If a program attempts to disable an 1406<function>XRecordContext</function> 1407that has not been enabled, no action will take place. 1408</para> 1409 1410<para> 1411<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 1412returns zero if the request failed; otherwise, it 1413returns nonzero. The context argument must specify a valid 1414<function>XRecordContext</function> 1415or an 1416<function>XRecordBadContext</function> 1417error results. 1418</para> 1419</sect2> 1420</sect1> 1421 1422<sect1 id='ID_Base_Mask'> 1423<title>ID Base Mask</title> 1424 1425<para> 1426To determine the mask the server uses for the client ID base, use 1427<xref linkend='XRecordIdBaseMask' xrefstyle='select: title'/></para> 1428 1429<funcsynopsis id='XRecordIdBaseMask'> 1430<funcprototype> 1431 <funcdef>XID <function>XRecordIdBaseMask</function></funcdef> 1432 <paramdef>Display<parameter> *display</parameter></paramdef> 1433</funcprototype> 1434</funcsynopsis> 1435 1436<variablelist remap='IP'> 1437 <varlistentry> 1438 <term><emphasis remap='I'>display</emphasis></term> 1439 <listitem><para>Specifies the connection to the X server.</para></listitem> 1440 </varlistentry> 1441</variablelist> 1442 1443<para> 1444The 1445<xref linkend='XRecordIdBaseMask' xrefstyle='select: title'/> 1446function returns the resource ID mask passed to the client by the 1447server at connection setup. 1448</para> 1449 1450</sect1> 1451 1452<sect1 id='Free_Context'> 1453<title>Free Context</title> 1454 1455<para> 1456Before terminating, the program should request that the server 1457free the record context. This is done with the 1458<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> 1459function, typically over the record client's control connection 1460to the X server. 1461</para> 1462 1463<funcsynopsis id='XRecordFreeContext'> 1464<funcprototype> 1465 <funcdef>Status <function>XRecordFreeContext</function></funcdef> 1466 <paramdef>Display<parameter> *display</parameter></paramdef> 1467 <paramdef>XRecordContext<parameter> context</parameter></paramdef> 1468</funcprototype> 1469</funcsynopsis> 1470 1471<variablelist remap='IP'> 1472 <varlistentry> 1473 <term><emphasis remap='I'>display</emphasis></term> 1474 <listitem><para>Specifies the connection to the X server.</para></listitem> 1475 </varlistentry> 1476 <varlistentry> 1477 <term><emphasis remap='I'>context</emphasis></term> 1478 <listitem><para>Specifies the record context to free.</para></listitem> 1479 </varlistentry> 1480</variablelist> 1481 1482<para> 1483The 1484<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> 1485function frees the given context for the 1486requesting client. Freeing a record context releases the clients 1487targeted for recording and their respective protocol ranges to 1488record. If protocol data is being reported to the recording client, 1489generally over the data connection to the X server, the reporting 1490ceases as if 1491<xref linkend='XRecordDisableContext' xrefstyle='select: title'/> 1492had been called on the given context. When a program terminates 1493without freeing its record context, the X server will automatically 1494free that context on behalf of the client. 1495</para> 1496 1497<para> 1498<xref linkend='XRecordFreeContext' xrefstyle='select: title'/> 1499returns zero if the request failed; otherwise,it 1500returns nonzero. The context argument must specify a valid 1501<function>XRecordContext</function> 1502or a 1503<function>XRecordBadContext</function> 1504error results. 1505</para> 1506 1507</sect1> 1508</chapter> 1509</book> 1510