diff options
Diffstat (limited to 'specs/recordlib.ms')
| -rw-r--r-- | specs/recordlib.ms | 1409 |
1 files changed, 1409 insertions, 0 deletions
diff --git a/specs/recordlib.ms b/specs/recordlib.ms new file mode 100644 index 0000000..c9fe8e0 --- /dev/null +++ b/specs/recordlib.ms @@ -0,0 +1,1409 @@ +.\" Record Extension Library, v1.13 +.\" Use -ms and macros.t +.\" edited for DP edits and code consistency w/ core protocol/xlib 4/1/96 +.\" $Xorg: recordlib.ms,v 1.3 2000/08/17 19:42:36 cpqbld Exp $ +.\" $XdotOrg: xc/doc/specs/Xext/recordlib.ms,v 1.2 2004/04/23 18:42:18 eich Exp $ +.\" ----------------------------------------------- +.de Ip +.IP \(bu 5 +.. +.de sC \" start change (gildea). arg is issue number +.mc \s+5\(br\s0\" \" make tall enough to span paragraph skip +.if !^\\$1^^ \{\ +'sp -1 +.lt +\w'000'u+\w'\s-2\&\\$1\s0'u +.tl !!!\v'\n(.vu'\s-2\&\\$1\s0! +.lt -\w'000'u+\w'\s-2\&\\$1\s0'u +.\} +.. +.de eC \" end change +.if \\n(.u .mc \s+5\(br\s0\" ensure it appears on the last line +.mc +.. +.\" +.hw XRecord-Register-Clients XRecord-Unregister-Clients +.hw XRecord-Intercept-Data XRecord-Query-Version XRecord-Process-Replies +.hw XRecord-EndOfData +.hw XButton-Released-Event XMotion-Event +.hw XRecord-Context +.EH '''' +.OH '''' +.EF '''' +.OF '''' +.fi +.ps 11 +.nr PS 11 +\& +.sp 8 +.ce 50 +\s+3\fBX Record Extension Library\fP\s0 +.sp +\fBVersion 1.13\fP +.sp +\fBX Consortium Standard\fP +.sp +\fBX Version 11, Release 6.8\fP +.sp 6 +Martha Zimet +Network Computing Devices, Inc. +.sp 6 +edited by +Stephen Gildea +X Consortium +.ce 0 +.bp +.br +\& +.sp 13 +.ps 9 +.nr PS 9 +.fi +.LP +Copyright \(co 1994 Network Computing Devices, Inc. +.LP +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 \*Qas is\*U without express or implied warranty. +.LP +Copyright \(co 1995 X Consortium +.LP +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +\*QSoftware\*U), 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: +.LP +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. +.LP +THE SOFTWARE IS PROVIDED \*QAS IS\*U, 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. +.LP +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. +.ps 11 +.nr PS 11 +.P1 +.nr LL 6.5i +.nr LT 6.5i +.nr FL 6.5i +.ll 6.5i +.EH '\fBX Record Extension Library, Version 1.13\fP''\fBX11, Release 6.8\fP' +.OH '\fBX11, Release 6.8\fP''\fBX Record Extension Library, Version 1.13\fP' +.bp 1 +.EF ''\fB\\\\n(PN\fP'' +.OF ''\fB\\\\n(PN\fP'' +.hy 14 + +.NH 1 +Record Extension Overview +.XS +\*(SN Record Extension Overview +.XE +.LP +The purpose +of this extension is to support the recording and reporting of all +core X protocol and arbitrary X extension protocol. This first section +gives an overview of the Record extension. The following sections +describe how to use the Record extension library. +.NH 2 +Synchronous Playback +.XS +\*(SN Synchronous Playback +.XE +.LP +Environment information is generally provided to an X-based playback +mechanism, which might use the XTest extension to synthesize input events. +This synchronization information defines the X state prior to +event synthesis (for example, location of the cursor, window locations and +sizes, installed colormap, window manager running, and so on) and the +consequences that occur after the playback mechanism synthesizes +the event. If the user moves the mouse into the icon window and +presses and releases a mouse button, the device events +.PN MotionNotify , +.PN ButtonPress , +and +.PN ButtonRelease +are generated by the X server. +Because +X follows an event-driven model, there are consequences that +follow from +the user actions, or device events, that are in the form of X protocol. +As a result of the previous user actions, the client could +generate requests such as +.PN ImageText8 +and +.PN PolyLine +to the X server, +or the X server could send non-device events such as +.PN Expose +and +.PN MapNotify +to the client window. Both the requests and non-device events that +result from user actions are known as \fIconsequences\fP, which +can be used as a synchronization, or control point, during playback. +That is, the playback mechanism does not generate a specific synthesized +event until its matching synchronization condition occurs (for example, +the window is mapped or unmapped, the cursor changes, a text string +displays, and so on) +.LP +Because +it cannot be predicted what synchronization information is +required during playback, the Record extension makes no assumptions +about the intended use of the recorded data. Facilities exist to +record any core X protocol or X extension protocol. +Therefore, Record does not enforce a specific synchronization +methodology. +.NH 2 +Design Approach +.XS +\*(SN Design Approach +.XE +.LP +The design approach of the extension is to record core X protocol +and arbitrary X extension protocol entirely within the X server +itself. When the extension has been requested to record specific +protocol by one or more recording clients, the protocol data is formatted +and returned to the recording clients. The extension provides a mechanism +for capturing all events, including input device events that do not go to any +clients. +.NH 2 +Record Clients +.XS +\*(SN Record Clients +.XE +.LP +The recommended +communication model for a Record application is to open two +connections to the server\*-one connection for recording control +and one connection for reading recorded protocol data. +.LP +Information about recording (for example, what clients to record, +what protocol to record for each client, and so on) is stored in +resources called \fIrecord contexts\fP\^ +(type +.PN XRecordContext ). +Most Record extension functions take a record context as an argument. +Although in theory it is possible +to share record contexts between applications, +it is expected that +applications will use their own context when performing recording +operations. +.LP +A client that wishes to record X protocol does so through the library +functions defined in +section 3 \*QLibrary Extension Requests\*U. A typical sequence +of requests that a client would make is as follows: +.Ip +.PN XRecordQueryVersion +\- query the extension protocol version. +.Ip +.PN XRecordCreateContext +\- request that the server create a record context +for access by this client, and express interest in clients and protocol +to be recorded. This request returns an +.PN XRecordContext , +which is an XID that is used +by most other extension requests to identify the specified context. +.Ip +.PN XRecordEnableContext +\- begin the recording and reporting of protocol +data. +.Ip +.PN XRecordDisableContext +\- end the recording and reporting of protocol data. +.Ip +.PN XRecordFreeContext +\- free the record context. +.LP +The header for this library is +.Pn < X11/extensions/record.h >. +All identifiers defined in the interface are supplied by this header +and are prefixed with \*QXRecord\*U. The +.PN Xtst +library contains the +.PN XRecord +functions. +.NH 1 +Common Arguments +.XS +\*(SN What Is Recorded +.XE +.LP +The Record extension functions +.PN XRecordCreateContext +and +.PN XRecordRegisterClients +allow applications to specify the following: +.Ip +Individual clients or sets of clients to record +.Ip +Ranges of core X protocol and X extension protocol to record for +each client +.LP +Protocol in the ranges specified by the recording client +will be recorded by the server. The device_events +protocol type can be specified by a recording +client although it may not be sent to a recorded client. +The device_events type differs from delivered_events, +which also can be specified by a recording client; +delivered_events are actually delivered to one or more clients. +These event types are discussed in section 2.3 \*QProtocol Ranges\*U. +.LP +The Record extension functions +.PN XRecordCreateContext +and +.PN XRecordRegisterClients +have the common arguments +datum_flags, +clients, and ranges, which specify +whether server time and/or client +sequence number should precede protocol elements, +the clients or client set to +record, and the protocol ranges to record, respectively. +These are discussed in the following sections. +.NH 2 +Datum Flags +.LP +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. +.LP +The +.PN XRecordFromServerTime +flag specifies that +.PN XRecordInterceptData +structures with a category of +.PN XRecordFromServer +will have a server_time field specific to each +protocol element. +.LP +The +.PN XRecordFromClientTime +flag specifies that +.PN XRecordInterceptData +structures with a category of +.PN XRecordFromClient +will have a server_time field specific to each protocol element. +.LP +The +.PN XRecordFromClientSequence +flag specifies that +.PN XRecordInterceptData +structures with a category of +.PN XRecordFromClient +or +.PN XRecordClientDied +will have a valid client_seq field. +.NH 2 +Selecting Clients +.LP +The clients argument is a pointer to an array of +.PN XRecordClientSpec . +.PN XRecordClientSpec +is an integral type that holds a resource ID, +a client resource ID base, or one +of the \fIclient set\fP constants defined below. +.LP +Duplicate +elements in the array are ignored by the functions, and if any element +in the array is not valid, a +.PN "BadMatch" +error results. +A resource ID references the client that created that resource. +The client set may be one of the following constants: +.PN XRecordCurrentClients , +.PN XRecordFutureClients , +or +.PN XRecordAllClients . +.LP +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 \*QData Transfer\*U. +.LP +If the element is +.PN XRecordCurrentClients , +the protocol ranges specified by the +ranges argument, except for device_events, are associated with +each current client connection. If the element is +.PN XRecordFutureClients , +the protocol ranges specified by the ranges argument are associated +with each new client connection. If the element is +.PN XRecordAllClients , +the protocol ranges specified by the ranges argument are associated +with each current client connection and with each new client connection. +.LP +When the context is enabled, the data connection is unregistered if it +was registered. +If the context is enabled, +.PN XRecordCurrentClients +and +.PN XRecordAllClients +silently exclude the recording data connection. +It is an error to explicitly register the data connection. +.NH 2 +Protocol Ranges +.LP +The functions +.PN XRecordCreateContext +and +.PN XRecordRegisterClients +have another common argument, ranges, +which is an array of pointers to +.PN 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 +.PN XRecordRange +structure must be allocated +by the Record library using the +.PN XRecordAllocRange +function. +.LP +The +.PN XRecordRange +typedef is a structure with the following members: +.LP +.sM +.Ds 0 +.TA .5i 3.0i +.ta .5i 3.0i +XRecordRange: + XRecordRange8 core_requests /* core X requests */ + XRecordRange8 core_replies /* core X replies */ + XRecordExtRange ext_requests /* extension requests */ + XRecordExtRange ext_replies /* extension replies */ + XRecordRange8 delivered_events /* delivered core and ext events */ + XRecordRange8 device_events /* all core and ext device events */ + XRecordRange8 errors /* core X and X ext errors */ + Bool client_started /* connection setup reply from server */ + Bool client_died /* notification of client disconnect */ +.De +.LP +.eM +The types used in +.PN XRecordRange +members are defined as follows. +The +.PN XRecordRange8 +typedef is a structure with the following members: +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +XRecordRange8: + unsigned char first + unsigned char last +.De +.LP +.eM +The +.PN XRecordRange16 +typedef is a structure with the following members: +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +XRecordRange16: + unsigned short first + unsigned short last +.De +.LP +.eM +The +.PN XRecordExtRange +typedef is a structure with the following members: +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +XRecordExtRange: + XRecordRange8 ext_major + XRecordRange16 ext_minor +.De +.LP +.eM +If any of the values specified in +.PN XRecordRange +is invalid, a +.PN "BadValue" +error results. +.LP +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 +.PN "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. +.LP +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 +.PN "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. +.LP +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 +.PN "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. +.LP +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 +.PN "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. +.LP +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 +.PN "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. +.LP +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 +.PN "BadValue" +error results +if the value of first +is greater than the value of last. A +.PN "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. +.LP +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 +.PN "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. +.LP +A value of +.PN True +for the client_started member specifies the +connection setup reply from the server to new clients. +If +.PN False , +the connection setup reply is +not specified by this +.PN XRecordRange . +.LP +A value of +.PN True +for the client_died member specifies +notification when a client disconnects. +If +.PN False , +notification when a client disconnects is +not specified by this +.PN XRecordRange . +.NH 1 +Library Extension Requests +.XS +\*(SN Library Extension Requests +.XE +.LP +Recording operations are accessed by programs through the use of +new protocol requests. The following functions are provided as extensions +to Xlib. An Xlib error results if +an extension request is made to an X server that does not support the +Record extension. Note that any of the extension protocol requests may generate +.PN BadAlloc +or +.PN BadLength +errors. +.NH 2 +Query Extension Version +.XS +\*(SN Query Extension Version +.XE +.LP +An application uses the +.PN XRecordQueryVersion +function to determine +the version of the Record extension protocol supported by an X server. +.sM +.FD 0 +Status +XRecordQueryVersion\^(Display *\fIdisplay\fP, int *\fIcmajor_return\fP, \ +int *\fIcminor_return\fP) +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP "\fIcmajor_return\fP" 1i +Returns the extension protocol major version in use. +.IP "\fIcminor_return\fP" 1i +Returns the extension protocol minor version in use. +.LP +.eM +The +.PN XRecordQueryVersion +function returns the major and minor +protocol version numbers supported by the server. +.PN XRecordQueryVersion +returns nonzero (success) only if the returned version numbers are +common to both the library and the +server; otherwise, it returns zero. +.NH 2 +Create and Modify Context +.XS +\*(SN Create and Modify Context +.XE +.LP +An application uses the +.PN XRecordCreateContext +function to create a +record context. At the time the record context is +created by the recording client, the clients to be recorded and the +protocol to record for each client may be specified. +.LP +.sM +.FD 0 +XRecordContext +XRecordCreateContext\^(Display *\fIdisplay\fP, int \fIdatum_flags\fP, \ +XRecordClientSpec *\fIclients\fP, int \fInclients\fP, +.br + XRecordRange **\fIranges\fP, int \fInranges\fP) +.FN +.IP "\fIdisplay\fP" 1i +Specifies the connection to the X server. +.IP \fIdatum_flags\fP 1i +Specifies whether detailed time or sequence info should be sent. +.IP "\fIclients\fP" 1i +Specifies the clients to record. +.IP "\fInclients\fP" 1i +Specifies the number of clients. +.IP "\fIranges\fP" 1i +Specifies the protocol ranges to record. +.IP "\fInranges\fP" 1i +Specifies the number of protocol ranges. +.LP +.eM +The +.PN XRecordCreateContext +function creates a record context and returns an +.PN XRecordContext , +which is then used +in the other Record library calls. This request is typically +executed by the recording client over its control connection to +the X server. +The datum_flags specifies whether server time and/or client +sequence number should precede protocol elements recorded by context +(see section 2.1). +When a clients element identifies +a particular client, the client is added to the context and +the protocol to record for that client is set to the union of +all ranges. When a clients element is +.PN XRecordCurrentClients , +.PN XRecordFutureClients , +or +.PN XRecordAllClients , +the actions described in section 2.2 \*QSelecting Clients\*U +are performed. +.LP +.PN XRecordCreateContext +returns zero if the request failed. +.PN XRecordCreateContext +can generate +.PN BadIDChoice , +.PN BadMatch , +and +.PN BadValue +errors. +.LP +The ranges argument is an +.PN XRecordRange * +array, that is, an array +of pointers. The structures the elements point to shall be allocated +by calling +.PN XRecordAllocRange . +.LP +.sM +.FD 0 +XRecordRange * +XRecordAllocRange\^(void) +.FN +.LP +.eM +The +.PN XRecordAllocRange +function +allocates and returns an +.PN XRecordRange +structure. +The structure is initialized to specify no protocol. +The function returns NULL if the structure allocation fails. +The application can free the structure by calling +.PN XFree . +.NH 3 +Additions +.LP +An application uses the +.PN 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. +.LP +.sM +.FD 0 +Status +XRecordRegisterClients\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP, \ +int \fIdatum_flags\fP, +.br + XRecordClientSpec *\fIclients\fP, int \fInclients\fP, \ +XRecordRange **\fIranges\fP, int \fInranges\fP) +.FN +.IP "\fIdisplay\fP " 1i +Specifies the connection to the X server. +.IP "\fIcontext\fP" 1i +Specifies the record context to modify. +.IP \fIdatum_flags\fP 1i +Specifies whether detailed time or sequence info should be sent. +.IP "\fIclients\fP" 1i +Specifies the clients to record. +.IP "\fInclients\fP" 1i +Specifies the number of clients. +.IP "\fIranges\fP" 1i +Specifies the protocol ranges to record. +.IP "\fInranges\fP" 1i +Specifies the number of protocol ranges. +.LP +.eM +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 +.PN XRecordCurrentClients , +.PN XRecordFutureClients , +or +.PN XRecordAllClients , +the actions described +in section 2.2 \*QSelecting Clients\*U +are performed. +.LP +.PN XRecordRegisterClients +returns zero if the request failed; otherwise, it +returns nonzero. +.LP +.PN XRecordRegisterClients +can generate +.PN XRecordBadContext , +.PN BadMatch , +and +.PN BadValue +errors. +.NH 3 +Deletions +.LP +An application uses +the +.PN XRecordUnregisterClients +function to delete clients from a +previously created +record context, typically over its control connection to the X server. +.LP +.sM +.FD 0 +Status +XRecordUnregisterClients\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP, \ +RecordClientSpec *\fIclients\fP, +.br + int \fInclients\fP\^) +.FN +.IP "\fIdisplay\fP " 1i +Specifies the connection to the X server. +.IP "\fIcontext\fP" 1i +Specifies the record context to modify. +.IP "\fIclients\fP" 1i +Specifies the clients to stop recording. +.IP "\fInclients\fP" 1i +Specifies the number of clients. +.LP +.eM +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. +.LP +When the element is +.PN XRecordCurrentClients , +all clients currently targeted +for recording in context and their corresponding sets of +protocol to record are deleted from context. +.LP +When the item is +.PN XRecordFutureClients , +any future client connections will +not automatically be targeted for recording in context. +.LP +When the element is +.PN 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. +.LP +.PN XRecordUnregisterClients +returns zero if the request failed; otherwise, +it returns nonzero. +.LP +.PN XRecordUnregisterClients +can generate +.PN XRecordBadContext , +.PN BadMatch , +and +.PN BadValue +errors. +.NH 2 +Query Context State +.XS +\*(SN Query Context State +.XE +.LP +An application uses the +.PN XRecordGetContext +function to query the +current state of a record context, typically over its control connection +to the X server. +.LP +.sM +.FD 0 +Status +XRecordGetContext\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP, \ + XRecordState **\fIstate_return\fP) +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP "\fIcontext\fP" 1i +Specifies the record context to query. +.IP "\fIstate_return\fP" 1i +Specifies the address of a variable into which the function stores a +pointer to the current state of the record context. +.LP +.eM +The +.PN XRecordState +typedef returned by +.PN XRecordGetContext +is a structure +with the following members: +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +XRecordState: + Bool enabled + int datum_flags + unsigned long nclients + XRecordClientInfo **client_info +.De +.LP +.eM +The enabled member is set to the state of data transfer and is +.PN True +when the recording client has asked that recorded data be sent; +otherwise it is +.PN False . +The datum_flags member is set to the value of these flags for +this context. +The nclients member is set to the +number of +.PN XRecordClientInfo +structures returned. The client_info member +is an array of pointers to +.PN XRecordClientInfo +structures that contain +the protocol +to record for each targeted client. +The +.PN XRecordClientInfo +typedef is a structure with the following members: +.LP +.sM +.Ds 0 +.TA .5i +.ta .5i +XRecordClientInfo: + XRecordClientSpec client + unsigned long nranges + XRecordRange **ranges +.De +.LP +.eM +The client member either identifies a client targeted for recording +or is set to +.PN XRecordFutureClients +to describe how future clients +will be automatically targeted for recording. +The nranges member is set to the number of protocol +ranges to be recorded for the specified client. The ranges member +is an array of pointers to +.PN XRecordRange +structures, which specify the +protocol ranges to record. +.LP +.PN XRecordGetContext +returns zero if the request failed; otherwise, it +returns nonzero. +The context argument must specify a valid +.PN XRecordContext +or a +.PN XRecordBadContext +error results. +.LP +Recording clients should use the +.PN XRecordFreeState +function to free the state data returned by +.PN XRecordGetContext . +.LP +.sM +.FD 0 +void +XRecordFreeState\^(XRecordState *\fIstate\fP) +.FN +.IP "\fIstate\fP" 1i +Specifies the structure that is to be freed. +.LP +.eM +.PN XRecordFreeState +frees the data pointed to by state. +If the argument does not match an +.PN XRecordState +pointer +returned from a successful call to +.PN XRecordGetContext , +or if +.PN XRecordFreeState +has already been +called with it, the behavior is undefined. +.NH 2 +Data Transfer +.XS +\*(SN Data Transfer +.XE +.LP +An application uses the +.PN XRecordEnableContext +and +.PN XRecordDisableContext +functions to change the state of data transfer +between the X server and the recording client. These functions allow +the application to start recording and reporting of protocol data +and to stop recording and reporting of protocol data, respectively. +.NH 3 +Enable Context +.XS +\*(SN Enable Context +.XE +.LP +To direct the X server to record and report protocol, a program +uses +.PN XRecordEnableContext , +typically over its data connection to the X +server. The reporting of recorded protocol back to the recording client +is handled by the following data structures and procedure definitions. +Each recorded protocol element is reported +to the recording client through an +.PN XRecordInterceptData +typedef, +a structure with the following members: +.LP +.sM +.Ds 0 +.TA .5i +.ta .25i +XRecordInterceptData: + XID id_base + Time server_time + unsigned long client_seq + int category + Bool client_swapped + unsigned char *data + unsigned long data_len +.De +.LP +.eM +The id_base member is set to the resource identifier base sent to the +client in the connection setup reply and therefore identifies the client +being recorded, except when the recorded protocol data is a device +event that may have not been delivered to a client. In this case, +id_base is set to zero. The server_time member +is set to the time of the server when the protocol was recorded. +It is the time that was attached to this protocol element in the reply, +if so specified by datum_flags, +or else the time from the header of the reply that contained +this protocol element. +The client_seq member is the sequence number of the recorded +client's most recent request processed by the server at the time this +protocol element was recorded, if this information were included in the +recorded data; otherwise client_seq is 0. +The category member is set to one of the following values: +.PN XRecordStartOfData , +.PN XRecordFromServer , +.PN XRecordFromClient , +.PN XRecordClientStarted , +.PN XRecordClientDied , +or +.PN XRecordEndOfData . +.PN XRecordStartOfData +is immediately sent as the first reply to confirm +that the context is enabled. +.PN XRecordFromClient +indicates the protocol +data is from the recorded client to the server (requests). +.PN XRecordFromServer +indicates the protocol data is from the server to the recorded client +(replies, errors, events, or device events). +.PN XRecordClientStarted +indicates that the protocol data is the +connection setup reply from the server. +.PN XRecordClientDied +indicates that the recorded +client has closed its connection +to the X server; there is no protocol data. +.PN XRecordEndOfData +indicates that the context has been disabled and that +this is the last datum. It does not correspond to any protocol or +state change in a recorded client. There is no protocol data. +.LP +The client_swapped member is set to +.PN True +if the byte order of the client being recorded is swapped relative to +the recording client; otherwise, it is set to +.PN False . +All +recorded protocol data is returned in the byte order of the recorded +client. Therefore, recording clients are responsible for all byte swapping, +if required. +Device events are in the byte order of the +recording client. +For replies of category +.PN XRecordStartOfData +and +.PN XRecordEndOfData , +client_swapped is set +according +to the byte order of the server relative to the recording client. +.LP +The data member contains the actual recorded +protocol data. +When category is set to +.PN XRecordStartOfData , +.PN XRecordClientDied , +or +.PN XRecordEndOfData , +no protocol +data are contained in data. +.\" +.LP +.\" copied exactly from the protocol document +For the core X events +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +and +.PN ButtonRelease , +the fields of a device event that contain +valid information are time and detail. +For the core X event +.PN MotionNotify , +the fields of a device event that contain +valid information are time, root, +root-x and root-y. +The time field refers to the time the event was generated by the +device. +.LP +For the extension input device events +.PN DeviceKeyPress , +.PN DeviceKeyRelease , +.PN DeviceButtonPress , +and +.PN DeviceButtonRelease , +the fields of a device event that contain valid information are +device, time, and detail. +For +.PN DeviceMotionNotify , +the valid device event fields are +device and time. +For the extension input device events +.PN ProximityIn +and +.PN ProximityOut , +the fields of a device event that contain valid +information are device and time. +For the extension input device event +.PN DeviceValuator , +the fields of a device event that contain valid information are +device, +num_valuators, first_valuator, and valuators. +The time field refers to the time the event was generated by the +device. +.\" +.LP +The data_len member is set to the +length of the actual recorded protocol data in 4-byte units. +.LP +When the context has been enabled, protocol data the recording client has +previously expressed interest in is recorded and returned to the +recording client via multiple replies. +Because +the X server batches +the recorded data, more than one protocol element may be contained +in the same reply packet. +When a reply is received, a procedure of type +.PN XRecordInterceptProc +is +called for each protocol +element in the reply. +.LP +.sM +.FD 0 +typedef void\^(*XRecordInterceptProc) +.br + (XPointer \fIclosure\fP, XRecordInterceptData *\fIrecorded_data\fP) +.FN +.IP "\fIclosure\fP" 1i +Pointer that was passed in when the context was enabled. +.IP "\fIrecorded_data\fP" 1i +A protocol element recorded by the server extension. +.LP +.eM +This callback +may use the control display connection (or any display connection +other than the data connection). +.LP +Recording clients should use the +.PN XRecordFreeData +function +to free the +.PN XRecordInterceptData +structure. +.LP +.sM +.FD 0 +Status +XRecordEnableContext\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP, \ +XRecordInterceptProc \fIcallback\fP, +.br + XPointer \fIclosure\fP) +.FN +.IP "\fIdisplay\fP" 1i +Specifies the connection to the X server. +.IP "\fIcontext\fP" 1i +Specifies the record context to enable. +.IP "\fIcallback\fP" 1i +Specifies the function to be called for each protocol element received. +.IP "\fIclosure\fP" 1i +Specifies data passed to \fIcallback.\fP +.LP +.eM +.PN XRecordEnableContext +enables data transfer between the recording client and +the X server. All core and extension protocol received from or sent to +targeted clients that the recording client has expressed +interest in will be recorded and reported to the recording client. +.LP +.PN XRecordEnableContext +returns zero if the request failed; otherwise, it +returns nonzero. The context argument must specify a valid +.PN XRecordContext +or a +.PN XRecordBadContext +error results. The error +.PN BadMatch +results when data transfer is already enabled +on the given context. +.NH 3 +Enable Context Asynchronously +.XS +\*(SN Enable Context Asynchronously +.XE +.LP +Because +.PN XRecordEnableContext +does not return until +.PN XRecordDisableContext +is executed on the control connection, a nonblocking interface in +addition to +.PN XRecordEnableContext +is provided. This interface also +enables data transfer; however, it does not block. +.LP +This interface is defined as follows: +.LP +.sM +.FD 0 +Status +XRecordEnableContextAsync\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP, +.br + XRecordInterceptProc \fIcallback\fP, XPointer \fIclosure\fP) +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIcontext\fP 1i +Specifies the record context to enable. +.IP \fIcallback\fP 1i +Specifies the function to be called for each protocol element received. +.IP \fIclosure\fP 1i +Data passed to \fIcallback\fP. +.LP +.eM +.PN XRecordEnableContextAsync +enables data transfer between the recording +client and the X server just as +.PN XRecordEnableContext +does. +Unlike +.PN XRecordEnableContext , +it does not wait for the context to be disabled +before returning; +.PN XRecordEnableContextAsync +returns as soon as the +.PN XRecordStartOfData +reply has been received and processed. +.LP +.PN XRecordEnableContextAsync +returns zero if it could not allocate the +necessary memory and nonzero if it sent the request successfully to +the server. The context argument must specify a valid +.PN XRecordContext +or a +.PN XRecordBadContext +error results. The error +.PN BadMatch +results when data transfer is already enabled. +.LP +Each time it reads data from the server connection, Xlib will check +for incoming replies and call \fIcallback\fP as necessary. The +application may direct Xlib explicitly to check for Record data with +the +.PN XRecordProcessReplies +function. +.LP +.sM +.FD 0 +void +XRecordProcessReplies\^(Display *\fIdisplay\fP) +.FN +.IP \fIdisplay\fP 11 +Specifies the connection to the X server. +.LP +.eM +.PN XRecordProcessReplies +will check for any replies that have not yet +been processed by the application. The asynchronous callback will be called +as appropriate. +.PN XRecordProcessReplies +returns when all immediately +available replies have been processed. It does not block. +.LP +.sp +To free the data passed to the +.PN XRecordInterceptProc +callback, +use +.PN XRecordFreeData . +.LP +.sM +.FD 0 +void +XRecordFreeData\^(XRecordInterceptData *\fIdata\fP) +.FN +.IP "\fIdata\fP" 1i +Specifies the structure that is to be freed. +.LP +.eM +.PN XRecordFreeData +frees the data pointed to by data. +If the argument does not match an +.PN XRecordInterceptData +pointer earlier +passed to an +.PN XRecordInterceptProc +callback or if +.PN XRecordFreeData +has +already been called with it, the behavior is undefined. +.NH 3 +Disable Context +.XS +\*(SN Disable Context +.XE +.LP +To direct the X server to halt the reporting of recorded protocol, the +program executes +.PN XRecordDisableContext , +typically over its +control connection to the X server. +.LP +.sM +.FD 0 +Status +XRecordDisableContext\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP) +.FN +.IP "\fIdisplay\fP" 1i +Specifies the connection to the X server. +.IP "\fIcontext\fP" 1i +Specifies the record context to disable. +.LP +.eM +The +.PN XRecordDisableContext +function disables context, stopping +all recording over its data connection. +Any complete protocol elements for context +that were buffered in the server will be sent to the +recording client rather than being discarded. +If a program attempts to disable an +.PN XRecordContext +that has not been enabled, no action will take place. +.LP +.PN XRecordDisableContext +returns zero if the request failed; otherwise, it +returns nonzero. The context argument must specify a valid +.PN XRecordContext +or an +.PN XRecordBadContext +error results. +.NH 2 +ID Base Mask +.XS +\*(SN ID Base Mask +.XE +.LP +To determine the mask the server uses for the client ID base, use +.PN XRecordIdBaseMask . +.LP +.sM +.FD 0 +XID +XRecordIdBaseMask\^(Display *\fIdisplay\fP) +.FN +.IP "\fIdisplay\fP" 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XRecordIdBaseMask +function returns the resource ID mask passed to the client by the +server at connection setup. +.NH 2 +Free Context +.XS +\*(SN Free Context +.XE +.LP +Before terminating, the program should request that the server +free the record context. This is done with the +.PN XRecordFreeContext +function, typically over the record client's control connection +to the X server. +.LP +.sM +.FD 0 +Status +XRecordFreeContext\^(Display *\fIdisplay\fP, XRecordContext \fIcontext\fP) +.FN +.IP "\fIdisplay\fP" 1i +Specifies the connection to the X server. +.IP "\fIcontext\fP" 1i +Specifies the record context to free. +.LP +.eM +The +.PN XRecordFreeContext +function frees the given context for the +requesting client. Freeing a record context releases the clients +targeted for recording and their respective protocol ranges to +record. If protocol data is being reported to the recording client, +generally over the data connection to the X server, the reporting +ceases as if +.PN XRecordDisableContext +had been called on the given context. +When a program terminates without freeing +its record context, the X server will automatically free that context +on behalf of the client. +.LP +.PN XRecordFreeContext +returns zero if the request failed; otherwise,it +returns nonzero. The context argument must specify a valid +.PN XRecordContext +or a +.PN XRecordBadContext +error results. +.\" +.\" Local Variables: +.\" time-stamp-start: "^\\.ds Ts " +.\" time-stamp-end: "\\\\\"" +.\" time-stamp-format: "%d %3b %y (%H:%02M)" +.\" End: |