1mRecord Extension Protocol Specification0m 1mVersion 1.130m 1mX Consortium Standard0m 1mX Version 11, Release 6.40m 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 documen- tation is provided "as is" without express or implied war- ranty. Copyright © 1994, 1995 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documenta- tion 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 PUR- POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR- TIUM 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 Con- sortium 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. 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m 1m1. Introduction0m Several proposals have been written over the past few years that address some of the issues surrounding the recording and playback of user actions in the X Window System1: · 4mSome24m 4mProposals24m 4mfor24m 4ma24m 4mMinimal24m 4mX1124m 4mTesting24m 4mExtension24m, Kieron Drake, UniSoft Ltd., April 1991 · 4mX1124m 4mInput24m 4mSynthesis24m 4mExtension24m 4mProposal24m, Larry Woestman, Hewlett Packard, November 1991 · 4mXTrap24m 4mArchitecture24m, Dick Annicchiario, et al, Digital Equip- ment Corporation, July 1991 · 4mXTest24m 4mExtension24m 4mRecording24m 4mSpecification24m, Yochanan Slonim, Mer- cury Interactive, December 1992 This document both unifies and extends the previous diverse approaches to generate a proposal for an X extension that pro- vides support for the recording of all core X protocol and arbi- trary extension protocol. Input synthesis, or playback, has already been implemented in the XTest extension, an X Consortium standard. Therefore, this extension is limited to recording. In order to provide both record and playback functionality, a hypothetical record application could use this extension to cap- ture both user actions and their consequences. For example, a button press (a user action) may cause a window to be mapped and a corresponding 4mMapNotify24m event to be sent (a consequence). This information could be stored for later use by a playback applica- tion. The playback application could use the recorded actions as input for the XTest extension's 4mXTestFakeInput24m operation to synthesize the appropriate input events. The "consequence" or synchroniza- tion information is then used as a synchronization point during playback. That is, the playback application does not generate specific synthesized events until their matching synchronization condition occurs. When the condition occurs the processing of synthesized events continues. Determination that the condition has occurred may be made by capturing the consequences of the synthesized events and comparing them to the previously recorded synchronization information. For example, if a button press was followed by a 4mMapNotify24m event on a particular window in the recorded data, the playback application might synthesize the but- ton press then wait for the 4mMapNotify24m event on the appropriate window before proceeding with subsequent synthesized input. Because it is impossible to predict what synchronization informa- tion will be required by a particular application, the extension provides facilities to record any subset of core X protocol and ----------- 1 4mX24m 4mWindow24m 4mSystem24m is a trademark of X Consortium, Inc. 1m10m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m arbitrary extension protocol. As such, this extension does not enforce a specific synchronization methodology; any method based on information in the X protocol stream (e.g., watching for win- dow mapping/unmapping, cursor changes, drawing of certain text strings, etc.) can capture the information it needs using RECORD facilities. 1m1.1. Acknowledgements0m The document represents the culmination of two years of debate and experiments done under the auspices of the X Consortium xtest working group. Although this was a group effort, the author remains responsible for any errors or omissions. Two years ago, Robert Chesler of Absol-puter, Kieron Drake of UniSoft Ltd., Marc Evans of Synergytics and Ken Miller of Digitial shared the vision of a standard extension for recording and were all instrumental in the early protocol development. During the last two years, Bob Scheifler of the X Consortium and Jim Fulton of NCD continu- ously provided input to the protocol design, as well as encour- agement to the author. In the last few months, Stephen Gildea and Dave Wiggins, both X Consortium staff, have spent consider- able time fine tuning the protocol design and reviewing the pro- tocol specifications. Most recently, Amnon Cohen of Mercury Interactive has assisted in clarification of the recorded event policy, and Kent Siefkes of Performance Awareness has assisted in clarification of the timestamp policy. 1m1.2. Goals0m · To provide a standard for recording, whereby both device events and synchronization information in the form of device event consequences are recorded. · To record contextual information used in synchronized playback without prior knowledge of the application that is being recorded. · To provide the ability to record arbitrary X protocol extensions. 1m1.3. Requirements0m The extension should function as follows: · It should not be dependent on other clients or extensions for its operation. · It should not significantly impact performance. · It should support the recording of all device input (core devices and XInput devices). 1m20m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m · It should be extendible. · It should support the recording of synchronization infor- mation for user events. 1m2. Design0m This section gives an overview of the RECORD extension and dis- cusses its overall operation and data types. 1m2.1. Overview0m The mechanism used by this extension for recording is to inter- cept core X protocol and arbitrary X extension protocol entirely within the X server itself. When the extension has been requested to intercept specific protocol by one or more clients, the protocol data are formatted and returned to the recording clients. The extension provides a mechanism for capturing all events, including input device events that go to no clients, that is analogous to a client expressing "interest" in all events in all windows, including the root window. Event filtering in the extension provides a mechanism for feeding device events to recording clients; it does not provide a mechanism for in-place, synchronous event substitution, modification, or withholding. In addition, the extension does not provide data compression before intercepted protocol is returned to the recording clients. 1m2.1.1. Data Delivery0m Because events are limited in size to 32 bytes, using events to return intercepted protocol data to recording clients is prohibi- tive in terms of performance. Therefore, intercepted protocol data are returned to recording clients through multiple replies to the extension request to begin protocol interception and reporting. This utilization is consistent with 4mListFontsWith-0m 4mInfo24m, for example, where a single request has multiple replies. Individual requests, replies, events or errors intercepted by the extension on behalf of recording clients cannot be split across reply packets. In order to reduce overhead, multiple intercepted requests, replies, events and errors might be collected into a single reply. Nevertheless, all data are returned to the client in a timely manner. 1m2.1.2. Record Context0m The extension adds a record context resource (RC) to the set of resources managed by the server. All the extension operations take an RC as an argument. Although the protocol permits sharing of RCs between clients, it is expected that clients will use 1m30m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m their own RCs. The attributes used in extension operations are stored in the RCs, and these attributes include the protocol and clients to intercept. The terms "register" and "unregister" are used to describe the relationship between clients to intercept and the RC. To regis- ter a client with an RC means the client is added to the list of clients to intercept; to unregister a client means the client is deleted from the list of clients to intercept. When the server is requested to register or unregister clients from an RC, it is required to do so immediately. That is, it is not permissible for the server to wait until recording is enabled to register clients or recording is disabled to unregister clients. 1m2.1.3. Record Client Connections0m The typical communication model for a recording client is to open two connections to the server and use one for RC control and the other for reading protocol data. The "control" connection can execute requests to obtain informa- tion about the supported protocol version, create and destroy RCs, specify protocol types to intercept and clients to be recorded, query the current state of an RC, and to stop intercep- tion and reporting of protocol data. The "data" connection can execute a request to enable interception and reporting of speci- fied protocol for a particular RC. When the "enable" request is issued, intercepted protocol is sent back on the same connection, generally in more than one reply packet. Until the last reply to the "enable" request is sent by the server, signifying that the request execution is complete, no other requests will be executed by the server on that connection. That is, the connection that data are being reported on cannot issue the "disable" request until the last reply to the "enable" request is sent by the server. Therefore, unless a recording client never has the need to disable the interception and reporting of protocol data, two client connections are necessary. 1m2.1.4. Events0m The terms "delivered events" and "device events" are used to describe the two event classes recording clients may select for interception. These event classes are handled differently by the extension. Delivered events are core X events or X extension events the server actually delivers to one or more clients. Device events are events generated by core X devices or extension input devices that the server may or may not deliver to any clients. When device events are selected for interception by a recording client, the extension guarantees each device event is recorded and will be forwarded to the recording client in the same order it is generated by the device. The recording of selected device events is not affected by server grabs. Delivered events, on the other hand, can be affected by 1m40m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m server grabs. If a recording client selects both a device event and delivered events that result from that device event, the delivered events are recorded after the device event. In the absence of grabs, the delivered events for a device event precede later device events. Requests that have side effects on devices, such as 4mWarpPointer0m and 4mGrabPointer24m with a confine-to window, will cause RECORD to record an associated device event. The XTEST extension request 4mXTestFakeInput24m causes a device event to be recorded; the device events are recorded in the same order that the 4mXTestFakeInput0m requests are received by the server. If a key autorepeats, multiple 4mKeyPress24m and 4mKeyRelease24m device events are reported. 1m2.1.5. Timing0m Requests are recorded just before they are executed; the time associated with a request is the server time when it is recorded. 1m2.2. Types0m The following new types are used in the request definitions that appear in section 3. RC: CARD32 The 4mRC24m type is a resource identifier for a server record context. RANGE8: [4mfirst24m, 4mlast24m: CARD8] RANGE16: [4mfirst24m, 4mlast24m: CARD16] EXTRANGE: [4mmajor24m: RANGE8 4mminor24m: RANGE16] RECORDRANGE: [4mcore-requests24m: RANGE8 4mcore-replies24m: RANGE8 4mext-requests24m: EXTRANGE 4mext-replies24m: EXTRANGE 4mdelivered-events24m: RANGE8 4mdevice-events24m: RANGE8 4merrors24m: RANGE8 4mclient-started24m: BOOL 4mclient-died24m: BOOL] 1m50m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m The 4mRECORDRANGE24m structure contains the protocol values to inter- cept. Typically, this structure is sent by recording clients over the control connection when creating or modifying an RC. 4mcore-requests0m Specifies core X protocol requests with an opcode field between 4mfirst24m and 4mlast24m inclusive. If 4mfirst24m is equal to 0 and 4mlast24m is equal to 0, no core requests are specified by this RECORDRANGE. If 4mfirst24m is greater than 4mlast24m, a 4mValue0m error results. 4mcore-replies0m Specifies replies resulting from core X protocol requests with an opcode field between 4mfirst24m and 4mlast24m inclusive. If 4mfirst24m is equal to 0 and 4mlast24m is equal to 0, no core replies are specified by this RECORDRANGE. If 4mfirst24m is greater than 4mlast24m, a 4mValue24m error results. 4mext-requests0m Specifies extension protocol requests with a major opcode field between 4mmajor.first24m and 4mmajor.last24m and a minor opcode field between 4mminor.first24m and 4mminor.last24m inclusive. If 4mmajor.first24m and 4mmajor.last24m are equal to 0, no extension pro- tocol requests are specified by this RECORDRANGE. If 4mmajor.first24m or 4mmajor.last24m is less than 128 and greater than 0, if 4mmajor.first24m is greater than 4mmajor.last24m, or if 4mminor.first24m is greater than 4mminor.last24m, a 4mValue24m error results. 4mext-replies0m Specifies replies resulting from extension protocol requests with a major opcode field between 4mmajor.first24m and 4mmajor.last0m and a minor opcode field between 4mminor.first24m and 4mminor.last0m inclusive. If 4mmajor.first24m and 4mmajor.last24m are equal to 0, no extension protocol replies are specified by this RECORD- RANGE. If 4mmajor.first24m or 4mmajor.last24m is less than 128 and greater than 0, if 4mmajor.first24m is greater than 4mmajor.last24m, or if 4mminor.first24m is greater than 4mminor.last24m, a 4mValue24m error results. 4mdelivered-events0m This is used for both core X protocol events and arbitrary extension events. Specifies events that are delivered to at least one client that have a code field between 4mfirst24m and 4mlast24m inclusive. If 4mfirst24m is equal to 0 and 4mlast24m is equal to 0, no events are specified by this RECORDRANGE. Otherwise, if 4mfirst24m is less than 2 or 4mlast24m is less than 2, or if 4mfirst0m is greater than 4mlast24m, a 4mValue24m error results. 4mdevice-events0m This is used for both core X device events and X extension device events that may or may not be delivered to a client. Specifies device events that have a code field between 4mfirst0m and 4mlast24m inclusive. If 4mfirst24m is equal to 0 and 4mlast24m is 1m60m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m equal to 0, no device events are specified by this RECORD- RANGE. Otherwise, if 4mfirst24m is less than 2 or 4mlast24m is less than 2, or if 4mfirst24m is greater than 4mlast24m, a 4mValue24m error results. Because the generated device event may or may not be associ- ated with a client, unlike other RECORDRANGE components, which select protocol for a specific client, selecting for device events in any RECORDRANGE in an RC causes the record- ing client to receive one instance for each device event generated that is in the range specified. 4merrors0m This is used for both core X protocol errors and arbitrary extension errors. Specifies errors that have a code field between 4mfirst24m and 4mlast24m inclusive. If 4mfirst24m is equal to 0 and 4mlast24m is equal to 0, no errors are specified by this RECORDRANGE. If 4mfirst24m is greater than 4mlast24m, a 4mValue24m error results. 4mclient-started0m Specifies the connection setup reply. If 4mFalse24m, the connec- tion setup reply is not specified by this RECORDRANGE. 4mclient-died0m Specifies notification when a client disconnects. If 4mFalse24m, notification when a client disconnects is not specified by this RECORDRANGE. ELEMENT_HEADER: [4mfrom-server-time24m: BOOL 4mfrom-client-time24m: BOOL 4mfrom-client-sequence24m: BOOL] The 4mELEMENT_HEADER24m structure specifies additional data that pre- cedes each protocol element in the 4mdata24m field of a 4mRecordEnable-0m 4mContext24m reply. · If 4mfrom-server-time24m is 4mTrue24m, each intercepted protocol element with category 4mFromServer24m is preceded by the server time when the protocol was recorded. · If 4mfrom-client-time24m is 4mTrue24m, each intercepted protocol element with category 4mFromClient24m is preceded by the server time when the protocol was recorded. · If 4mfrom-client-sequence24m is 4mTrue24m, each intercepted protocol element with category 4mFromClient24m or 4mClientDied24m is preceded by the 32-bit sequence number of the recorded client's most recent request processed by the server at that time. For 4mFromClient24m, this will be one less than the sequence number of the following request. For 4mClientDied24m, the sequence number will be the only data, because no protocol is recorded. 1m70m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m Note that a reply containing device events is treated the same as other replies with category 4mFromServer24m for purposes of these flags. Protocol with category 4mFromServer24m is never preceded by a sequence number because almost all such protocol has a sequence number in it anyway. If both a server time and a sequence number have been requested for a reply, each protocol request is preceded first by the time and second by the sequence number. XIDBASE: CARD32 The XIDBASE type is used to identify a particular client. Valid values are any existing resource identifier of any connected client, in which case the client that created the resource is specified, or the resource identifier base sent to the target client from the server in the connection setup reply. A value of 0 (zero) is valid when the XIDBASE is associated with device events that may not have been delivered to a client. CLIENTSPEC: XIDBASE or {1mCurrentClients22m, 1mFutureClients22m, 1mAllClients22m} The CLIENTSPEC type defines the set of clients the RC attributes are associated with. This type is used by recording clients when creating an RC or when changing RC attributes. XIDBASE specifies that the RC attributes apply to a single client only. 4mCurrent-0m 4mClients24m specifies that the RC attributes apply to current client connections; 4mFutureClients24m specifies future client connections; 4mAllClients24m specifies all client connections, which includes cur- rent and future. The numeric values for 4mCurrentClients24m, 4mFutureClients24m and 4mAll-0m 4mClients24m are defined such that there will be no intersection with valid XIDBASEs. When the context is enabled, the data connection is unregistered if it was registered. If the context is enabled, 4mCurrentClients0m and 4mAllClients24m silently exclude the recording data connection. It is an error to explicitly register the data connection. CLIENT_INFO: [4mclient-resource24m: CLIENTSPEC 4mintercepted-protocol24m: LISTofRECORDRANGE] This structure specifies an intercepted client and the protocol to be intercepted for the client. The 4mclient-resource24m field is a resource base that identifies the intercepted client. The 4minter-0m 4mcepted-protocol24m field specifies the protocol to intercept for the 4mclient-resource24m. 1m80m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m 1m2.3. Errors0m 1mRecordContext0m This error is returned if the value for an RC argument in a request does not name a defined record context. 1m3. Protocol Requests0m 4mRecordQueryVersion0m 4mmajor-version24m, 4mminor-version24m: CARD16 -> 4mmajor-version24m, 4mminor-version24m: CARD16 This request specifies the RECORD extension protocol version the client would like to use. When the specified protocol version is supported by the extension, the protocol version the server expects from the client is returned. Clients must use this request before other RECORD extension requests. This request also determines whether or not the RECORD extension protocol version specified by the client is supported by the extension. If the extension supports the version specified by the client, this version number should be returned. If the client has requested a higher version than is supported by the server, the server's highest version should be returned. Other- wise, if the client has requested a lower version than is sup- ported by the server, the server's lowest version should be returned. This document defines major version one (1), minor version thirteen (13). 4mRecordCreateContext0m 4mcontext24m: RC 4melement-header24m: ELEMENT_HEADER 4mclient-specifiers24m: LISTofCLIENTSPEC 4mranges24m: LISTofRECORDRANGE Errors: 4mMatch24m, 4mValue24m, 4mIDChoice24m, 4mAlloc0m This request creates a new record context within the server and assigns the identifier 4mcontext24m to it. After the 4mcontext24m is cre- ated, this request registers the set of clients in 4mclient-speci-0m 4mfiers24m with the 4mcontext24m and specifies the protocol to intercept for those clients. The recorded protocol elements will be pre- ceded by data as specified by 4melement-header24m. Typically, this 1m90m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m request is used by a recording client over the control connec- tion. Multiple RC objects can exist simultaneously, containing overlapping sets of protocol and clients to intercept. If any of the values in 4melement-header24m or 4mranges24m is invalid, a 4mValue24m error results. Duplicate items in the list of 4mclient-spec-0m 4mifiers24m are ignored. If any item in the 4mclient-specifiers24m list is not a valid CLIENTSPEC, a 4mMatch24m error results. Otherwise, each item in the 4mclient-specifiers24m list is processed as follows: · If the item is an XIDBASE identifying a particular client, the specified client is registered with the 4mcontext24m and the proto- col to intercept for the client is then set to 4mranges24m. · If the item is 4mCurrentClients24m, all existing clients are regis- tered with the 4mcontext24m at this time. The protocol to inter- cept for all clients registered with the 4mcontext24m is then set to 4mranges24m. · If the item is 4mFutureClients24m, all clients that connect to the server after this request executes will be automatically reg- istered with the 4mcontext24m. The protocol to intercept for such clients will be set to 4mranges24m in the 4mcontext24m. · If the item is 4mAllClients24m, the effect is as if the actions described for 4mFutureClients24m are performed, followed by the actions for 4mCurrentClients24m. The 4mAlloc24m error results when the server is unable to allocate the necessary resources. 4mRecordRegisterClients0m 4mcontext24m: RC 4melement-header24m: ELEMENT_HEADER 4mclient-specifiers24m: LISTofCLIENTSPEC 4mranges24m: LISTofRECORDRANGE Errors: 4mMatch24m, 4mValue24m, 4mRecordContext24m, 4mAlloc0m This request registers the set of clients in 4mclient-specifiers0m with the given 4mcontext24m and specifies the protocol to intercept for those clients. The header preceding each recorded protocol element is set as specified by 4melement-header24m. These flags affect the entire context; their effect is not limited to the clients registered by this request. Typically, this request is used by a recording client over the control connection. If 4mcontext24m does not name a valid RC, a 4mRecordContext24m error results. If any of the values in 4melement-header24m or 4mranges24m is 1m100m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m invalid, a 4mValue24m error results. Duplicate items in the list of 4mclient-specifiers24m are ignored. If any item in the list of 4mclient-specifiers24m is not a valid CLIENTSPEC, a 4mMatch24m error results. If the 4mcontext24m is enabled and the XID of the enabling connection is specified, a 4mMatch24m error results. Otherwise, each item in the 4mclient-specifiers24m list is processed as follows: · If the item is an XIDBASE identifying a particular client, the specified client is registered with the 4mcontext24m if it is not already registered. The protocol to intercept for the client is then set to 4mranges24m. · If the item is 4mCurrentClients24m, all existing clients that are not already registered with the specified 4mcontext24m, except the enabling connection if the 4mcontext24m is enabled, are registered at this time. The protocol to intercept for all clients reg- istered with the 4mcontext24m is then set to 4mranges24m. · If the item is 4mFutureClients24m, all clients that connect to the server after this request executes will be automatically reg- istered with the 4mcontext24m. The protocol to intercept for such clients will be set to 4mranges24m in the 4mcontext24m. The set of clients that are registered with the 4mcontext24m and their corre- sponding sets of protocol to intercept are left intact. · If the item is 4mAllClients24m, the effect is as if the actions described for 4mFutureClients24m are performed, followed by the actions for 4mCurrentClients24m. The 4mAlloc24m error results when the server is unable to allocate the necessary resources. 4mRecordUnregisterClients0m 4mcontext24m: RC 4mclient-specifiers24m: LISTofCLIENTSPEC Errors: 4mMatch24m, 4mRecordContext0m This request removes the set of clients in 4mclient-specifiers24m from the given 4mcontext24m's set of registered clients. Typically, this request is used by a recording client over the control connec- tion. If 4mcontext24m does not name a valid RC, a 4mRecordContext24m error results. Duplicate items in the list of 4mclient-specifiers24m are ignored. If any item in the list is not a valid CLIENTSPEC, a 4mMatch24m error results. Otherwise, each item in the 4mclient-speci-0m 4mfiers24m list is processed as follows: · If the item is an XIDBASE identifying a particular client, and the specified client is currently registered with the 4mcontext24m, 1m110m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m it is unregistered, and the set of protocol to intercept for the client is deleted from the 4mcontext24m. If the specified client is not registered with the 4mcontext24m, the item has no effect. · If the item is 4mCurrentClients24m, all clients currently regis- tered with the 4mcontext24m are unregistered from it, and their corresponding sets of protocol to intercept are deleted from the 4mcontext24m. · If the item is 4mFutureClients24m, clients that connect to the server after this request executes will not automatically be registered with the 4mcontext24m. The set of clients that are reg- istered with this context and their corresponding sets of pro- tocol that will be intercepted are left intact. · If the item is 4mAllClients24m, the effect is as if the actions described for 4mFutureClients24m are performed, followed by the actions for 4mCurrentClients24m. A client is unregistered automatically when it disconnects. 4mRecordGetContext0m 4mcontext24m: RC -> 4menabled24m: BOOL 4melement-header24m: ELEMENT_HEADER 4mintercepted-clients24m: LISTofCLIENT_INFO Errors: 4mRecordContext0m This request queries the current state of the specified 4mcontext0m and is typically used by a recording client over the control con- nection. The 4menabled24m field specifies the state of data transfer between the extension and the recording client, and is either enabled (4mTrue24m) or disabled (4mFalse24m). The initial state is dis- abled. When enabled, all core X protocol and extension protocol received from (requests) or sent to (replies, errors, events) a particular client, and requested to be intercepted by the record- ing client, is reported to the recording client over the data connection. The 4melement-header24m specifies the header that pre- cedes each recorded protocol element. The 4mintercepted-clients0m field specifies the list of clients currently being recorded and the protocol associated with each client. If future clients will be automatically registered with the context, one of the returned CLIENT_INFO structures has a 4mclient-resource24m value of Future- Clients and an 4mintercepted-protocol24m giving the protocol to inter- cept for future clients. Protocol ranges may be decomposed, 1m120m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m coalesced, or otherwise modified by the server from how they were specified by the client. All CLIENTSPECs registered with the server are returned, even if the RECORDRANGE(s) associated with them specify no protocol to record. When the 4mcontext24m argument is not valid, a 4mRecordContext24m error results. 4mRecordEnableContext0m 4mcontext24m: RC ->+ 4mcategory24m: {1mFromServer22m, 1mFromClient22m, 1mClientStarted22m, 1mClient-0m 1mDied22m, 1mStartOfData22m, 1mEndOfData22m} 4melement-header24m: ELEMENT_HEADER 4mclient-swapped24m: BOOL 4mid-base24m: XIDBASE 4mserver-time24m: TIMESTAMP 4mrecorded-sequence-number24m: CARD32 4mdata24m: LISTofBYTE Errors: 4mMatch24m, 4mRecordContext0m This request enables data transfer between the recording client and the extension and returns the protocol data the recording client has previously expressed interest in. Typically, this request is executed by the recording client over the data connec- tion. If the client is registered on the 4mcontext24m, it is unregistered before any recording begins. Once the server receives this request, it begins intercepting and reporting to the recording client all core and extension protocol received from or sent to clients registered with the RC that the recording client has expressed interest in. All intercepted pro- tocol data is returned in the byte-order of the recorded client. Therefore, recording clients are responsible for all byte swap- ping, if required. More than one recording client cannot enable data transfer on the same RC at the same time. Multiple inter- cepted requests, replies, events and errors might be packaged into a single reply before being returned to the recording clients. 1m130m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m The 4mcategory24m field determines the possible types of the data. When a context is enabled, the server will immediately send a reply of category 4mStartOfData24m to notify the client that recording is enabled. A category of 4mFromClient24m means the data are from the client (requests); 4mFromServer24m means data are from the server (replies, errors, events, or device events). For a new client, the category is 4mClientStarted24m and the data are the connection setup reply. When the recorded client connection is closed, 4mcat-0m 4megory24m is set to the value 4mClientDied24m and no protocol is included in this reply. When the disable request is made over the control connection, a final reply is sent over the data connection with category 4mEndOfData24m and no protocol. The 4melement-header24m field returns the value currently set for the context, which tells what header information precedes each recorded protocol element in this reply. The 4mclient-swapped24m field is 4mTrue24m if the byte order of the proto- col being recorded is swapped relative to the recording client; otherwise, 4mclient-swapped24m is 4mFalse24m. The recorded protocol is in the byte order of the client being recorded; device events are in the byte order of the recording client. For replies of category 4mStartOfData24m and 4mEndOfData24m the 4mclient-swapped24m bit is set according to the byte order of the server relative to the recording client. The 4mid-base24m field is the resource identifier base sent to the client from the server in the connection setup reply, and hence, identifies the client being recorded. The 4mid-base24m field is 0 (zero) when the protocol data being returned are device events. The 4mserver-time24m field is set to the time of the server when the first protocol element in this reply was intercepted. The 4mserver-time24m of reply N+1 is greater than or equal to the 4mserver-0m 4mtime24m of reply N, and is greater than or equal to the time of the last protocol element in reply N. The 4mrecorded-sequence-number24m field is set to the sequence number of the recorded client's most recent request processed by the server. The 4mdata24m field contains the raw protocol data being returned to the recording client. If requested by the 4melement-header24m of this record context, each protocol element may be preceded by a 32-bit timestamp and/or a 32-bit sequence number. If present, both the timestamp and sequence number are always in the byte order of the recording client. For the core X events 4mKeyPress24m, 4mKeyRelease24m, 4mButtonPress24m, and 4mButtonRelease24m, the fields of a device event that contain valid information are 4mtime24m and 4mdetail24m. For the core X event 4mMotion-0m 4mNotify24m, the fields of a device event that contain valid informa- tion are 4mtime24m, 4mroot24m, 4mroot-x24m and 4mroot-y24m. The 4mtime24m field refers to the time the event was generated by the device. For the extension input device events 4mDeviceKeyPress24m, 4mDeviceKeyRelease24m, 4mDeviceButtonPress24m, and 4mDeviceButtonRelease24m, the 1m140m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m fields of a device event that contain valid information are 4mdevice24m, 4mtime24m and 4mdetail24m. For 4mDeviceMotionNotify24m, the valid device event fields are 4mdevice24m and 4mtime24m. For the extension input device events 4mProximityIn24m and 4mProximityOut24m, the fields of a device event that contain valid information are 4mdevice24m and 4mtime24m. For the extension input device event 4mDeviceValuator24m, the fields of a device event that contain valid information are 4mdevice24m, 4mnum_valuators24m, 4mfirst_valuator24m, and 4mvaluators24m. The 4mtime24m field refers to the time the event was generated by the device. The error 4mMatch24m is returned when data transfer is already enabled. When the 4mcontext24m argument is not valid, a 4mRecordContext0m error results. 4mRecordDisableContext0m 4mcontext24m: RC Errors: 4mRecordContext0m This request is typically executed by the recording client over the control connection. This request directs the extension to immediately send any complete protocol elements currently buffered, to send a final reply with category 4mEndOfData24m, and to discontinue data transfer between the extension and the recording client. Protocol reporting is disabled on the data connection that is currently enabled for the given 4mcontext24m. Once the exten- sion completes processing this request, no additional recorded protocol will be reported to the recording client. If a data connection is not currently enabled when this request is exe- cuted, then this request has no affect on the state of data transfer. An RC is disabled automatically when the connection to the enabling client is closed down. When the 4mcontext24m argument is not valid, a 4mRecordContext24m error results. 4mRecordFreeContext0m 4mcontext24m : RC Errors: 4mRecordContext0m This request deletes the association between the resource ID and the RC and destroys the RC. If a client has enabled data trans- fer on this 4mcontext24m, the actions described in 4mRecordDisable-0m 4mContext24m are performed before the 4mcontext24m is freed. An RC is destroyed automatically when the connection to the cre- ating client is closed down and the close-down mode is 1mDestroy-0m 1mAll22m. When the 4mcontext24m argument is not valid, a 4mRecordContext0m error results. 1m150m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m 1m4. Encoding0m Please refer to the X11 Protocol Encoding document as this docu- ment uses conventions established there. The name of this extension is "RECORD". 1m4.1. Types0m RC: CARD32 RANGE8 1 CARD8 first 1 CARD8 last RANGE16 2 CARD16 first 2 CARD16 last EXTRANGE 2 RANGE8 major 4 RANGE16 minor RECORDRANGE 2 RANGE8 core-requests 2 RANGE8 core-replies 6 EXTRANGE ext-requests 6 EXTRANGE ext-replies 2 RANGE8 delivered-events 2 RANGE8 device-events 2 RANGE8 errors 1 BOOL client-started 1 BOOL client-died ELEMENT_HEADER 1 CARD8 0x01 from-server-time 0x02 from-client-time 0x04 from-client-sequence XIDBASE: CARD32 1m160m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m CLIENTSPEC 4 XIDBASE client-id-base 1 CurrentClients 2 FutureClients 3 AllClients CLIENT_INFO 4 CLIENTSPEC client-resource 4 CARD32 n, number of record ranges in intercepted-protocol 24n LISTofRECORDRANGE intercepted-protocol 1m4.2. Errors0m 4mRecordContext0m 1 0 Error 1 CARD8 extension's base error code + 0 2 CARD16 sequence number 4 CARD32 invalid record context 24 unused 1m4.3. Requests0m 4mRecordQueryVersion0m 1 CARD8 major opcode 1 0 minor opcode 2 2 request length 2 CARD16 major version 2 CARD16 minor version => 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 2 CARD16 major version 2 CARD16 minor version 20 unused 1m170m 1mRecord Extension Protocol, Version 1.13 X11, Release 6.40m 4mRecordCreateContext0m 1 CARD8 major opcode 1 1 minor opcode 2 5+m+6n request length 4 RC context 1 ELEMENT_HEADER element-header 3 unused 4 CARD32 m, number of client-specifiers 4 CARD32 n, number of ranges 4m LISTofCLIENTSPEC client-specifiers 24n LISTofRECORDRANGE ranges 4mRecordRegisterClients0m 1 CARD8 major opcode 1 2 minor opcode 2 5+m+6n request length 4 RC context 1 ELEMENT_HEADER element-header 3 unused 4 CARD32 m, number of client-specifiers 4 CARD32 n, number of ranges 4m LISTofCLIENTSPEC client-specifiers 24n LISTofRECORDRANGE ranges 4mRecordUnregisterClients0m 1 CARD8 major opcode 1 3 minor opcode 2 3+m request length 4 RC context 4 CARD32 m, number of client-specifiers 4m LISTofCLIENTSPEC client-specifiers 4mRecordGetContext0m 1 CARD8 major opcode 1 4 minor opcode 2 2 request length 4 RC context => 1 1 Reply 1 BOOL enabled 2 CARD16 sequence number 4 j reply length 1 ELEMENT_HEADER element-header 3 unused 4 CARD32 n, number of intercepted-clients 16 unused 4j LISTofCLIENT_INFO intercepted-clients 1m180m 1mX11, Release 6.4 Record Extension Protocol, Version 1.130m 4mRecordEnableContext0m 1 CARD8 major opcode 1 5 minor opcode 2 2 request length 4 RC context =>+ 1 1 Reply 1 category 0 FromServer 1 FromClient 2 ClientStarted 3 ClientDied 4 StartOfData 5 EndOfData 2 CARD16 sequence number 4 n reply length 1 ELEMENT_HEADER element-header 1 BOOL client-swapped 2 unused 4 XIDBASE id-base 4 TIMESTAMP server-time 4 CARD32 recorded-sequence-number 8 unused 4n BYTE data 4mRecordDisableContext0m 1 CARD8 major opcode 1 6 minor opcode 2 2 request length 4 RC context 4mRecordFreeContext0m 1 CARD8 major opcode 1 7 minor opcode 2 2 request length 4 RC context 1m190m