specs: convert protocol xtest.ms from xorg-docs to DocBook XML

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

2 files changed, 724 insertions, 1 deletions

diff --git a/specs/Makefile.am b/specs/Makefile.am
index 1ca8f35..a1acb2e 100644
--- a/specs/Makefile.am
+++ b/specs/Makefile.am
@@ -32,7 +32,8 @@ doc_sources =		\
 	shape.xml	\
 	shm.xml		\
 	sync.xml	\
-	tog-cup.xml
+	tog-cup.xml	\
+	xtest.xml
 
 dist_doc_DATA = $(doc_sources) geproto.txt
 
diff --git a/specs/xtest.xml b/specs/xtest.xml
new file mode 100644
index 0000000..6da29f1
--- /dev/null
+++ b/specs/xtest.xml
@@ -0,0 +1,722 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<book id="xtest">
+
+<bookinfo>
+   <title>XTEST Extension Protocol</title>
+   <subtitle>X Consortium Standard</subtitle>
+   <releaseinfo>Version 2.2</releaseinfo>
+   <authorgroup>
+      <author>
+         <firstname>Kieron</firstname><surname>Drake</surname>
+         <affiliation><orgname>UniSoft Ltd.</orgname></affiliation>
+      </author>
+   </authorgroup>
+   <copyright><year>1992</year><holder>UniSoft Group Ltd.</holder></copyright>
+   <copyright><year>1992,1994</year><holder>X Consortium</holder></copyright>
+
+<legalnotice>
+<para>
+Permission to use, copy, modify, and distribute this documentation for any
+purpose and without fee is hereby granted, provided that the above copyright
+notice and this permission notice appear in all copies.  UniSoft 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.
+</para>
+
+<para>
+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:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+Except as contained in this notice, the name of the X Consortium 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.
+</para>
+</legalnotice>
+</bookinfo>
+
+
+<chapter>
+<title>TITLE</title>
+
+<sect1 id="Overview">
+<title>Overview</title>
+<para>
+This extension is a minimal set of client and server extensions
+required to completely test the X11 server with no user intervention.
+</para>
+
+<para>
+This extension is not intended to support general journaling and
+playback of user actions.  This is a difficult area [XTrap, 89] as it attempts
+to synchronize synthetic user interactions with their effects; it is at the
+higher level of dialogue recording/playback rather than at the strictly lexical
+level.  We are interested only in the latter, simpler, case.  A more detailed
+discussion and justification of the extension functionality is given in
+[Drake, 91].
+</para>
+
+<para>
+We are aiming only to provide a minimum set of facilities that
+solve immediate testing and validation problems.  The testing extension
+itself needs testing, where possible, and so should be as simple as possible.
+</para>
+
+<para>
+We have also tried to:
+</para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+Confine the extension to an appropriate high level within the server
+to minimize portability problems.  In practice this means that the extension
+should be at the DIX level or use the DIX/DDX interface, or both.  This
+has effects, in particular, on the level at which "input synthesis"
+can occur.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Minimize the changes required in the rest of the server.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Minimize performance penalties on normal server operation.
+    </para>
+  </listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="Description">
+<title>Description</title>
+<para>
+The functions provided by this extension fall into two groups:
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term>Client Operations</term>
+    <listitem>
+      <para>
+These routines manipulate otherwise hidden client-side behavior.  The
+actual implementation will depend on the details of the actual language
+binding and what degree of request buffering, GContext caching, and so on, is
+provided.
+In the C binding, defined in "XTEST Extension Library", routines are
+provided to access the internals of two opaque data structures
+-- <function>GC</function>s
+and
+<function>Visual</function>s --
+and to discard any requests pending within the
+output buffer of a connection.  The exact details can be expected to differ for
+other language bindings.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Server Requests</term>
+    <listitem>
+      <para>
+The first of these requests is similar to that provided in most
+extensions: it allows a client to specify a major and minor version
+number to the server and for the server to respond with major and minor
+versions of its own.  The remaining two requests allow the following:
+<!-- .RS -->
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+Access to an otherwise "write-only" server resource: the cursor
+associated with a given window
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+Perhaps most importantly, limited synthesis of input device events,
+almost as if a cooperative user had moved the pointing device
+or pressed a key or button.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="Types">
+<title>Types</title>
+<para>
+The following types are used in the request and event definitions in
+subsequent sections:
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='2' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <colspec colname='c2' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry namest="c1" nameend="c2">
+FAKE_EVENT_TYPE
+{ <function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>MotionNotify</function>,
+<function>ButtonPress</function>,
+<function>ButtonRelease</function> }
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry></entry>
+    </row>
+    <row>
+      <entry>FAKE_EVENT</entry>
+      <entry>[type: FAKE_EVENT_TYPE,</entry>
+    </row>
+    <row rowsep="0">
+      <entry></entry>
+      <entry>detail: BYTE,</entry>
+    </row>
+    <row rowsep="0">
+      <entry></entry>
+      <entry>time: TIME,</entry>
+    </row>
+    <row rowsep="0">
+      <entry></entry>
+      <entry>root: WINDOW,</entry>
+    </row>
+    <row rowsep="0">
+      <entry></entry>
+      <entry>rootX, rootY: INT16]</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+CURSOR { <function>CurrentCursor</function>, <function> None</function> }
+or a cursor as defined by the X11 Protocol.
+</para>
+
+</sect1>
+
+<sect1 id="Client_Operations">
+<title>Client Operations</title>
+
+<para>
+These are abstract definitions of functionality.  They refer to client-side
+objects such as "GC" and "VISUAL" that are quoted to
+denote their abstract nature.  Concrete versions of these functions are
+defined only for particular language bindings.  In some circumstances
+a particular language binding may not implement the relevant abstract
+type or may provide it as a transparent, rather than opaque, type, with
+the result that the corresponding function does not make sense or is
+not required, respectively.
+</para>
+
+<para>
+<function>XTestSetGContextOfGC</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>gc</emphasis>: "GC"
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>gid</emphasis>: GCONTEXT
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+Sets the GCONTEXT within the "GC" gc to have
+the value specified by gid.
+</para>
+
+<para>
+<function>XTestSetVisualIDOfVisual</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>visual</emphasis>: "VISUAL"
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>visualid</emphasis>: VISUALID
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+Sets the VISUALID within the "VISUAL" visual to have
+the value specified by visualid.
+</para>
+
+<para>
+<function>XTestDiscard</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>dpy</emphasis>: "CONNECTION"
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+=&gt;
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+status: BOOL
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+Discards any requests that are present in the request buffer associated with
+the "CONNECTION" dpy.
+The status returned is
+<function>True</function>
+if there were one or more requests
+in the buffer and
+<function>False</function>
+otherwise.
+</para>
+</sect1>
+
+<sect1 id="Server_Requests">
+<title>Server Requests</title>
+<para>
+<function>XTestGetVersion</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>clientMajorVersion</emphasis>: CARD16
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>clientMinorVersion</emphasis>: CARD16
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+   =&gt;
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+serverMajorVersion: CARD16
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+serverMinorVersion: CARD16
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+Errors: <function>Length</function>
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+
+<para>
+This request can be used to ensure that the server version of the XTEST
+extension is usable by the client.  This document defines major version two
+(2), minor version one (1).
+</para>
+
+<para>
+<function>XTestCompareCursor</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>window</emphasis>: WINDOW
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>cursor-id</emphasis>: CURSOR or
+<function>CurrentCursor</function>
+or
+<function>None</function>
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+=&gt;
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+same: BOOL
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+Errors:
+<function>Window</function>,
+<function>Length</function>,
+<function>Cursor</function>
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+This request looks up the cursor associated with the window and
+compares it with either the null cursor if cursor-id is
+<function>None ,</function>
+or the current cursor (that is, the one being displayed),
+or the cursor whose ID is cursor-id, and returns
+the result of the comparison in same.
+</para>
+
+<para>
+<function>XTestFakeInput</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>events</emphasis>: LISTofFAKE_EVENT
+      </entry>
+    </row>
+    <row rowsep="0">
+      <entry>
+Errors:
+<function>Window</function>,
+<function>Length</function>,
+<function>Alloc</function>,
+<function>Value</function>
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+This request simulates the limited set of core protocol
+events within the set FAKE_EVENT_TYPE.  Only the following event fields,
+defined in FAKE_EVENT, are interpreted:
+</para>
+
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>type</emphasis>
+    </term>
+    <listitem>
+      <para>
+This must be one of
+<function>KeyPress</function>,
+<function>KeyRelease</function>,
+<function>MotionNotify</function>,
+<function>ButtonPress</function>,
+or
+<function>ButtonRelease</function>,
+or else a
+<function>Value</function>
+error occurs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>detail</emphasis>
+    </term>
+    <listitem>
+      <para>
+For key events, this field is interpreted as the physical keycode.
+If the keycode is less than min-keycode or greater than max-keycode,
+as returned in the connection setup, then a
+<function>Value</function>
+error occurs.
+For button events, this field is interpreted as the physical (or core) button,
+meaning it will be mapped to the corresponding logical button according to
+the most recent
+<function>SetPointerMapping</function>
+request.
+If the button number is less than one or greater than the number of physical
+buttons, then a
+<function>Value</function>
+error occurs.
+For motion events, if this field is
+<function>True ,</function>
+then rootX and rootY
+are relative distances from the current pointer location; if this field is
+<function>False,</function>
+then they are absolute positions.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+This is either
+<function>CurrentTime</function>
+(meaning no delay)
+or the delay in milliseconds that the server should wait before
+simulating this event.  No other requests from this client will be
+processed until this delay, if any, has expired and subsequent processing
+of the simulated event has been completed.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>root</emphasis>
+    </term>
+    <listitem>
+      <para>
+In the case of motion events this field is the ID of the root window on
+which the new motion is to take place.  If
+<function>None</function>
+is specified, the root window of the screen the pointer is currently on
+is used instead.
+If this field is not a valid window, then a
+<function>Window</function>
+error occurs.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>rootX</emphasis> &amp;
+      <emphasis remap='I'>rootY</emphasis>
+    </term>
+    <listitem>
+      <para>
+In the case of motion events these fields indicate relative distance or
+absolute pointer coordinates, according to the setting of detail.
+If the specified coordinates are off-screen, the closest on-screen
+coordinates will be substituted.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+When the simulated event(s) are processed, they cause event propagation,
+passive grab activation, and so on, just as if the corresponding input device
+action had occurred.  However, motion events might not be recorded in the
+motion history buffer.
+</para>
+
+<para>
+For the currently supported event types, the event list must have length one,
+otherwise a
+<function>BadLength</function>
+error occurs.
+</para>
+
+<para>
+<function>XTestGrabControl</function>
+</para>
+
+<informaltable frame="none">
+  <tgroup cols='1' align='left'>
+  <colspec colname='c1' colsep="0" colwidth="1*"/>
+  <tbody>
+    <row rowsep="0">
+      <entry>
+<emphasis remap='I'>impervious</emphasis>: BOOL
+      </entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<para>
+If impervious is
+<function>True</function>,
+then the executing client becomes impervious to server grabs;
+that is, it can continue executing requests even if another client
+grabs the server.
+If impervious is
+<function>False</function>,
+then the executing client returns to the normal state of being
+susceptible to server grabs.
+</para>
+</sect1>
+
+<sect1 id="Encoding">
+<title>Encoding</title>
+<para>
+Please refer to the X11 Protocol Encoding document as this document uses
+conventions established there.
+</para>
+
+<para>
+The name of this extension is "XTEST".
+</para>
+
+<sect2 id="New_Types">
+<title>New Types</title>
+<literallayout class="monospaced">
+FAKE_EVENT_TYPE
+     2     KeyPress
+     3     KeyRelease
+     4     ButtonPress
+     5     ButtonRelease
+     6     MotionNotify
+</literallayout>
+
+<para>
+NOTE that the above values are defined to be the same as those for
+the corresponding core protocol event types.
+</para>
+</sect2>
+
+<sect2 id="Requests">
+<title>Requests</title>
+
+<literallayout class="monospaced">
+<function>XTestGetVersion</function>
+     1     CARD8               opcode
+     1     0                   xtest opcode
+     2     2                   request length
+     1     CARD8               client major version
+     1                         unused
+     2     CARD16              client minor version
+=&gt;
+     1     1                   Reply
+     1     CARD8               server major version
+     2     CARD16              sequence number
+     4     0                   reply length
+     2     CARD16              server minor version
+     22                        unused
+</literallayout>
+
+<literallayout class="monospaced">
+<function>XTestCompareCursor</function>
+     1     CARD8               opcode
+     1     1                   xtest opcode
+     2     3                   request length
+     4     WINDOW              window
+     4     CURSOR              cursor-id
+           0     None
+           1     CurrentCursor
+=&gt;
+     1     1                   Reply
+     1     BOOL                cursors are the same
+     2     CARD16              sequence number
+     4     0                   reply length
+     24                        unused
+</literallayout>
+
+<literallayout class="monospaced">
+<function>XTestFakeInput</function>
+     1     CARD8               opcode
+     1     2                   xtest opcode
+     2     1+(1*8)             request length
+     1     FAKE_EVENT_TYPE     fake device event type
+     1     BYTE                detail: button or keycode
+     2                         unused
+     4     TIME                delay (milliseconds)
+           0     CurrentTime
+     4     WINDOW              root window for MotionNotify
+           0     None
+     8                         unused
+     2     INT16               x position for MotionNotify
+     2     INT16               y position for MotionNotify
+     8                         unused
+</literallayout>
+
+<literallayout class="monospaced">
+<function>XTestGrabControl</function>
+     1     CARD8               opcode
+     1     3                   xtest opcode
+     2     2                   request length
+     1     BOOL                impervious
+     3                         unused
+</literallayout>
+</sect2>
+</sect1>
+
+<sect1 id="References">
+<title>References</title>
+<para>
+Annicchiarico, D., et al.,
+<emphasis remap='I'>XTrap: The XTrap Architecture</emphasis>.
+Digital Equipment Corporation, July 1991.
+</para>
+
+<para>
+Drake, K. J.,
+<emphasis remap='I'>Some Proposals for a
+Minimum X11 Testing Extension</emphasis>.
+UniSoft Ltd., June 1991.
+</para>
+</sect1>
+</chapter>
+</book>