X Record Extension Library

Version 1.13

X Consortium Standard

X Version 11, Release 6.4

Martha Zimet Network Computing Devices, Inc.

edited by Stephen Gildea X Consortium

Copyright © 1994 Network Computing Devices, Inc.

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.

Copyright © 1995 X Consortium

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 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.

Except as contained in this notice, the name of the X Consortium and 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.

X11, Release 6.4 X Record Extension Library, Version 1.13

1. Record Extension OverviewThe purpose of this extension is to support the recording andreporting of all core X protocol and arbitrary X extensionprotocol. This first section gives an overview of the Recordextension. The following sections describe how to use the Recordextension library.1.1. Synchronous PlaybackEnvironment information is generally provided to an X-basedplayback mechanism, which might use the XTest extension tosynthesize input events. This synchronization informationdefines the X state prior to event synthesis (for example,location of the cursor, window locations and sizes, installedcolormap, window manager running, and so on) and the consequencesthat occur after the playback mechanism synthesizes the event.If the user moves the mouse into the icon window and presses andreleases a mouse button, the device events MotionNotify,ButtonPress, and ButtonRelease are generated by the X server.Because X follows an event-driven model, there are consequencesthat follow from the user actions, or device events, that are inthe form of X protocol. As a result of the previous useractions, the client could generate requests such as ImageText8and PolyLine to the X server, or the X server could sendnon-device events such as Expose and MapNotify to the clientwindow. Both the requests and non-device events that result fromuser actions are known as consequences, which can be used as asynchronization, or control point, during playback. That is, theplayback mechanism does not generate a specific synthesized eventuntil its matching synchronization condition occurs (for example,the window is mapped or unmapped, the cursor changes, a textstring displays, and so on)Because it cannot be predicted what synchronization informationis required during playback, the Record extension makes noassumptions about the intended use of the recorded data.Facilities exist to record any core X protocol or X extensionprotocol. Therefore, Record does not enforce a specificsynchronization methodology.1.2. Design ApproachThe design approach of the extension is to record core X protocoland arbitrary X extension protocol entirely within the X serveritself. When the extension has been requested to record specificprotocol by one or more recording clients, the protocol data isformatted and returned to the recording clients. The extensionprovides a mechanism for capturing all events, including inputdevice events that do not go to any clients.1.3. Record ClientsThe recommended communication model for a Record application isto open two connections to the server--one connection forrecording control and one connection for reading recordedprotocol data.Information about recording (for example, what clients to record,what protocol to record for each client, and so on) is stored inresources called record contexts (type XRecordContext). MostRecord extension functions take a record context as an argument.Although in theory it is possible to share record contextsbetween applications, it is expected that applications will usetheir own context when performing recording operations.A client that wishes to record X protocol does so through thelibrary functions defined in section 3 "Library ExtensionRequests". A typical sequence of requests that a client wouldmake is as follows:• XRecordQueryVersion − query the extension protocol version.• XRecordCreateContext − request that the server create arecord context for access by this client, and expressinterest in clients and protocol to be recorded. Thisrequest returns an XRecordContext, which is an XID that isused by most other extension requests to identify thespecified context.• XRecordEnableContext − begin the recording and reporting ofprotocol data.• XRecordDisableContext − end the recording and reporting ofprotocol data.• XRecordFreeContext − free the record context.The header for this library is <X11/extensions/record.h>. Allidentifiers defined in the interface are supplied by this headerand are prefixed with "XRecord". The Xtst library contains theXRecord functions.2. Common ArgumentsThe Record extension functions XRecordCreateContext andXRecordRegisterClients allow applications to specify thefollowing:• Individual clients or sets of clients to record• Ranges of core X protocol and X extension protocol to recordfor each clientProtocol in the ranges specified by the recording client will berecorded by the server. The device_events protocol type can bespecified by a recording client although it may not be sent to arecorded client. The device_events type differs fromdelivered_events, which also can be specified by a recordingclient; delivered_events are actually delivered to one or moreclients. These event types are discussed in section 2.3"Protocol Ranges".The Record extension functions XRecordCreateContext andXRecordRegisterClients have the common arguments datum_flags,clients, and ranges, which specify whether server time and/orclient sequence number should precede protocol elements, theclients or client set to record, and the protocol ranges torecord, respectively. These are discussed in the followingsections.2.1. Datum Flags

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.

The XRecordFromServerTime flag specifies that XRecordInterceptData structures with a category of XRecordFromServer will have a server_time field specific to each protocol element.

The XRecordFromClientTime flag specifies that XRecordInterceptData structures with a category of XRecordFromClient will have a server_time field specific to each protocol element.

The XRecordFromClientSequence flag specifies that XRecordInterceptData structures with a category of XRecordFromClient or XRecordClientDied will have a valid client_seq field.

2.2. Selecting Clients

The clients argument is a pointer to an array of XRecordClientSpec. XRecordClientSpec is an integral type that holds a resource ID, a client resource ID base, or one of the client set constants defined below.

Duplicate elements in the array are ignored by the functions, and if any element in the array is not valid, a BadMatch error results. A resource ID references the client that created that resource. The client set may be one of the following constants: XRecordCurrentClients, XRecordFutureClients, or XRecordAllClients.

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 section 3.4 "Data Transfer".

If the element is XRecordCurrentClients, the protocol ranges specified by the ranges argument, except for device_events, are associated with each current client connection. If the element is XRecordFutureClients, the protocol ranges specified by the ranges argument are associated with each new client connection. If the element is XRecordAllClients, 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, XRecordCurrentClients and XRecordAllClients silently exclude the recording data connection. It is an error to explicitly register the data connection.

2.3. Protocol Ranges

The functions XRecordCreateContext and XRecordRegisterClients have another common argument, ranges, which is an array of pointers to XRecordRange 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 XRecordRange structure must be allocated by the Record library using the XRecordAllocRange function.

The XRecordRange typedef is a structure with the following members: __ │

XRecordRange:

The types used in XRecordRange members are defined as follows. The XRecordRange8 typedef is a structure with the following members: __ │

XRecordRange8:

The XRecordRange16 typedef is a structure with the following members: __ │

XRecordRange16:

The XRecordExtRange typedef is a structure with the following members: __ │

XRecordExtRange:

If any of the values specified in XRecordRange is invalid, a BadValue error results.

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 BadValue 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.

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 BadValue 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.

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 BadValue 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.

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 BadValue 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.

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 BadValue 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.

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 BadValue error results if the value of first is greater than the value of last. A BadValue 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.

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 BadValue 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.

A value of True for the client_started member specifies the connection setup reply from the server to new clients. If False, the connection setup reply is not specified by this XRecordRange.

A value of True for the client_died member specifies notification when a client disconnects. If False, notification when a client disconnects is not specified by this XRecordRange.

3. Library Extension RequestsRecording operations are accessed by programs through the use ofnew protocol requests. The following functions are provided asextensions to Xlib. An Xlib error results if an extensionrequest is made to an X server that does not support the Recordextension. Note that any of the extension protocol requests maygenerate BadAlloc or BadLength errors.3.1. Query Extension VersionAn application uses the XRecordQueryVersion function to determinethe version of the Record extension protocol supported by an Xserver.__│ StatusXRecordQueryVersion(Display *display, int *cmajor_return, int *cminor_return)display Specifies the connection to the X server.cmajor_returnReturns the extension protocol major version in use.cminor_returnReturns the extension protocol minor version in use.│__ The XRecordQueryVersion function returns the major and minorprotocol version numbers supported by the server.XRecordQueryVersion returns nonzero (success) only if thereturned version numbers are common to both the library and theserver; otherwise, it returns zero.3.2. Create and Modify ContextAn application uses the XRecordCreateContext function to create arecord context. At the time the record context is created by therecording client, the clients to be recorded and the protocol torecord for each client may be specified.__│ XRecordContextXRecordCreateContext(Display *display, int datum_flags, XRecordClientSpec *clients, int nclients,XRecordRange **ranges, int nranges)display Specifies the connection to the X server.datum_flagsSpecifies whether detailed time or sequence info shouldbe sent.clients Specifies the clients to record.nclients Specifies the number of clients.ranges Specifies the protocol ranges to record.nranges Specifies the number of protocol ranges.│__ The XRecordCreateContext function creates a record context andreturns an XRecordContext, which is then used in the other Recordlibrary calls. This request is typically executed by therecording client over its control connection to the X server.The datum_flags specifies whether server time and/or clientsequence number should precede protocol elements recorded bycontext (see section 2.1). When a clients element identifies aparticular client, the client is added to the context and theprotocol to record for that client is set to the union of allranges. When a clients element is XRecordCurrentClients,XRecordFutureClients, or XRecordAllClients, the actions describedin section 2.2 "Selecting Clients" are performed.XRecordCreateContext returns zero if the request failed.XRecordCreateContext can generate BadIDChoice, BadMatch, andBadValue errors.The ranges argument is an XRecordRange* array, that is, an arrayof pointers. The structures the elements point to shall beallocated by calling XRecordAllocRange.__│ XRecordRange *XRecordAllocRange(void)│__ The XRecordAllocRange function allocates and returns anXRecordRange structure. The structure is initialized to specifyno protocol. The function returns NULL if the structureallocation fails. The application can free the structure bycalling XFree.3.2.1. Additions

An application uses the XRecordRegisterClients 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. __ │

Status
XRecordRegisterClients(Display *display, XRecordContext context, int datum_flags,
XRecordClientSpec *clients, int nclients, XRecordRange **ranges, int nranges)

datum_flags

│__

The datum_flags specifies whether server time and/or client sequence number should precede protocol elements for all clients recorded by context (see section 2.1). 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 XRecordCurrentClients, XRecordFutureClients, or XRecordAllClients, the actions described in section 2.2 "Selecting Clients" are performed.

XRecordRegisterClients returns zero if the request failed; otherwise, it returns nonzero.

XRecordRegisterClients can generate XRecordBadContext, BadMatch, and BadValue errors.

3.2.2. Deletions

An application uses the XRecordUnregisterClients function to delete clients from a previously created record context, typically over its control connection to the X server. __ │

Status
XRecordUnregisterClients(Display *display, XRecordContext context, RecordClientSpec *clients,
int nclients)

│__

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.

When the element is XRecordCurrentClients, all clients currently targeted for recording in context and their corresponding sets of protocol to record are deleted from context.

When the item is XRecordFutureClients, any future client connections will not automatically be targeted for recording in context.

When the element is XRecordAllClients, 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.

XRecordUnregisterClients returns zero if the request failed; otherwise, it returns nonzero.

XRecordUnregisterClients can generate XRecordBadContext, BadMatch, and BadValue errors.

3.3. Query Context StateAn application uses the XRecordGetContext function to query thecurrent state of a record context, typically over its controlconnection to the X server.__│ StatusXRecordGetContext(Display *display, XRecordContext context, XRecordState **state_return)display Specifies the connection to the X server.context Specifies the record context to query.state_returnSpecifies the address of a variable into which thefunction stores a pointer to the current state of therecord context.│__ The XRecordState typedef returned by XRecordGetContext is astructure with the following members:__│ XRecordState:Bool enabledint datum_flagsunsigned long nclientsXRecordClientInfo **client_info│__ The enabled member is set to the state of data transfer and isTrue when the recording client has asked that recorded data besent; otherwise it is False. The datum_flags member is set tothe value of these flags for this context. The nclients memberis set to the number of XRecordClientInfo structures returned.The client_info member is an array of pointers toXRecordClientInfo structures that contain the protocol to recordfor each targeted client. The XRecordClientInfo typedef is astructure with the following members:__│ XRecordClientInfo:XRecordClientSpec clientunsigned long nrangesXRecordRange **ranges│__ The client member either identifies a client targeted forrecording or is set to XRecordFutureClients to describe howfuture clients will be automatically targeted for recording. Thenranges member is set to the number of protocol ranges to berecorded for the specified client. The ranges member is an arrayof pointers to XRecordRange structures, which specify theprotocol ranges to record.XRecordGetContext returns zero if the request failed; otherwise,it returns nonzero. The context argument must specify a validXRecordContext or a XRecordBadContext error results.Recording clients should use the XRecordFreeState function tofree the state data returned by XRecordGetContext.__│ voidXRecordFreeState(XRecordState *state)state Specifies the structure that is to be freed.│__ XRecordFreeState frees the data pointed to by state. If theargument does not match an XRecordState pointer returned from asuccessful call to XRecordGetContext, or if XRecordFreeState hasalready been called with it, the behavior is undefined.3.4. Data TransferAn application uses the XRecordEnableContext andXRecordDisableContext functions to change the state of datatransfer between the X server and the recording client. Thesefunctions allow the application to start recording and reportingof protocol data and to stop recording and reporting of protocoldata, respectively.3.4.1. Enable ContextTo direct the X server to record and report protocol, a programuses XRecordEnableContext, typically over its data connection tothe X server. The reporting of recorded protocol back to therecording client is handled by the following data structures andprocedure definitions. Each recorded protocol element isreported to the recording client through an XRecordInterceptDatatypedef, a structure with the following members:__│ XRecordInterceptData:XID id_baseTime server_timeunsigned long client_seqint categoryBool client_swappedunsigned char *dataunsigned long data_len│__ The id_base member is set to the resource identifier base sent tothe client in the connection setup reply and therefore identifiesthe client being recorded, except when the recorded protocol datais 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 isset to the time of the server when the protocol was recorded. Itis the time that was attached to this protocol element in thereply, if so specified by datum_flags, or else the time from theheader of the reply that contained this protocol element. Theclient_seq member is the sequence number of the recorded client’smost recent request processed by the server at the time thisprotocol element was recorded, if this information were includedin the recorded data; otherwise client_seq is 0. The categorymember is set to one of the following values: XRecordStartOfData,XRecordFromServer, XRecordFromClient, XRecordClientStarted,XRecordClientDied, or XRecordEndOfData. XRecordStartOfData isimmediately sent as the first reply to confirm that the contextis enabled. XRecordFromClient indicates the protocol data isfrom the recorded client to the server (requests).XRecordFromServer indicates the protocol data is from the serverto the recorded client (replies, errors, events, or deviceevents). XRecordClientStarted indicates that the protocol datais the connection setup reply from the server. XRecordClientDiedindicates that the recorded client has closed its connection tothe X server; there is no protocol data. XRecordEndOfDataindicates that the context has been disabled and that this is thelast datum. It does not correspond to any protocol or statechange in a recorded client. There is no protocol data.The client_swapped member is set to True if the byte order of theclient being recorded is swapped relative to the recordingclient; otherwise, it is set to False. All recorded protocoldata is returned in the byte order of the recorded client.Therefore, recording clients are responsible for all byteswapping, if required. Device events are in the byte order ofthe recording client. For replies of category XRecordStartOfDataand XRecordEndOfData, client_swapped is set according to the byteorder of the server relative to the recording client.The data member contains the actual recorded protocol data. Whencategory is set to XRecordStartOfData, XRecordClientDied, orXRecordEndOfData, no protocol data are contained in data.For the core X events KeyPress, KeyRelease, ButtonPress, andButtonRelease, the fields of a device event that contain validinformation are time and detail. For the core X eventMotionNotify, the fields of a device event that contain validinformation are time, root, root-x and root-y. The time fieldrefers to the time the event was generated by the device.For the extension input device events DeviceKeyPress,DeviceKeyRelease, DeviceButtonPress, and DeviceButtonRelease, thefields of a device event that contain valid information aredevice, time, and detail. For DeviceMotionNotify, the validdevice event fields are device and time. For the extension inputdevice events ProximityIn and ProximityOut, the fields of adevice event that contain valid information are device and time.For the extension input device event DeviceValuator, the fieldsof a device event that contain valid information are device,num_valuators, first_valuator, and valuators. The time fieldrefers to the time the event was generated by the device.The data_len member is set to the length of the actual recordedprotocol data in 4-byte units.When the context has been enabled, protocol data the recordingclient has previously expressed interest in is recorded andreturned to the recording client via multiple replies. Becausethe X server batches the recorded data, more than one protocolelement may be contained in the same reply packet. When a replyis received, a procedure of type XRecordInterceptProc is calledfor each protocol element in the reply.__│ typedef void(*XRecordInterceptProc)(XPointer closure, XRecordInterceptData *recorded_data)closure Pointer that was passed in when the context wasenabled.recorded_dataA protocol element recorded by the server extension.│__ This callback may use the control display connection (or anydisplay connection other than the data connection).Recording clients should use the XRecordFreeData function to freethe XRecordInterceptData structure.__│ StatusXRecordEnableContext(Display *display, XRecordContext context, XRecordInterceptProc callback,XPointer closure)display Specifies the connection to the X server.context Specifies the record context to enable.callback Specifies the function to be called for each protocolelement received.closure Specifies data passed to callback.│__ XRecordEnableContext enables data transfer between the recordingclient and the X server. All core and extension protocolreceived from or sent to targeted clients that the recordingclient has expressed interest in will be recorded and reported tothe recording client.XRecordEnableContext returns zero if the request failed;otherwise, it returns nonzero. The context argument must specifya valid XRecordContext or a XRecordBadContext error results. Theerror BadMatch results when data transfer is already enabled onthe given context.3.4.2. Enable Context AsynchronouslyBecause XRecordEnableContext does not return untilXRecordDisableContext is executed on the control connection, anonblocking interface in addition to XRecordEnableContext isprovided. This interface also enables data transfer; however, itdoes not block.This interface is defined as follows:__│ StatusXRecordEnableContextAsync(Display *display, XRecordContext context,XRecordInterceptProc callback, XPointer closure)display Specifies the connection to the X server.context Specifies the record context to enable.callback Specifies the function to be called for each protocolelement received.closure Data passed to callback.│__ XRecordEnableContextAsync enables data transfer between therecording client and the X server just as XRecordEnableContextdoes. Unlike XRecordEnableContext, it does not wait for thecontext to be disabled before returning;XRecordEnableContextAsync returns as soon as theXRecordStartOfData reply has been received and processed.XRecordEnableContextAsync returns zero if it could not allocatethe necessary memory and nonzero if it sent the requestsuccessfully to the server. The context argument must specify avalid XRecordContext or a XRecordBadContext error results. Theerror BadMatch results when data transfer is already enabled.Each time it reads data from the server connection, Xlib willcheck for incoming replies and call callback as necessary. Theapplication may direct Xlib explicitly to check for Record datawith the XRecordProcessReplies function.__│ voidXRecordProcessReplies(Display *display)display Specifies the connection to the X server.│__ XRecordProcessReplies will check for any replies that have notyet been processed by the application. The asynchronous callbackwill be called as appropriate. XRecordProcessReplies returnswhen all immediately available replies have been processed. Itdoes not block.To free the data passed to the XRecordInterceptProc callback, useXRecordFreeData.__│ voidXRecordFreeData(XRecordInterceptData *data)data Specifies the structure that is to be freed.│__ XRecordFreeData frees the data pointed to by data. If theargument does not match an XRecordInterceptData pointer earlierpassed to an XRecordInterceptProc callback or if XRecordFreeDatahas already been called with it, the behavior is undefined.3.4.3. Disable ContextTo direct the X server to halt the reporting of recordedprotocol, the program executes XRecordDisableContext, typicallyover its control connection to the X server.__│ StatusXRecordDisableContext(Display *display, XRecordContext context)display Specifies the connection to the X server.context Specifies the record context to disable.│__ The XRecordDisableContext function disables context, stopping allrecording over its data connection. Any complete protocolelements for context that were buffered in the server will besent to the recording client rather than being discarded. If aprogram attempts to disable an XRecordContext that has not beenenabled, no action will take place.XRecordDisableContext returns zero if the request failed;otherwise, it returns nonzero. The context argument must specifya valid XRecordContext or an XRecordBadContext error results.3.5. ID Base MaskTo determine the mask the server uses for the client ID base, useXRecordIdBaseMask.__│ XIDXRecordIdBaseMask(Display *display)display Specifies the connection to the X server.│__ The XRecordIdBaseMask function returns the resource ID maskpassed to the client by the server at connection setup.3.6. Free ContextBefore terminating, the program should request that the serverfree the record context. This is done with theXRecordFreeContext function, typically over the record client’scontrol connection to the X server.__│ StatusXRecordFreeContext(Display *display, XRecordContext context)display Specifies the connection to the X server.context Specifies the record context to free.│__ The XRecordFreeContext function frees the given context for therequesting client. Freeing a record context releases the clientstargeted for recording and their respective protocol ranges torecord. If protocol data is being reported to the recordingclient, generally over the data connection to the X server, thereporting ceases as if XRecordDisableContext had been called onthe given context. When a program terminates without freeing itsrecord context, the X server will automatically free that contexton behalf of the client.XRecordFreeContext returns zero if the request failed;otherwise,it returns nonzero. The context argument must specifya valid XRecordContext or a XRecordBadContext error results.1