aboutsummaryrefslogtreecommitdiff
path: root/libXext/specs/xtest1.xml
blob: 4652de72a8fb5bab652efbe4b94edde89efe024c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
<?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="xtest1">

<bookinfo>
   <title>X11 INPUT SYNTHESIS EXTENSION PROPOSAL</title>
   <subtitle>X Consortium Standard</subtitle>
   <releaseinfo>Version 1.0</releaseinfo>
   <authorgroup>
      <author>
         <firstname>Larry</firstname><surname>Woestman</surname>
         <affiliation><orgname>Hewlett Packard, Member of Technical Staff</orgname></affiliation>
      </author>
   </authorgroup>
   <corpname>X Consortium Standard</corpname>
   <copyright><year>1993</year><holder>X Consortium</holder></copyright>
   <affiliation><orgname>X Consortium</orgname></affiliation>
   <productnumber>X Version 11, Release 7</productnumber>

<abstract>
<para>
This is a proposal for an extension to the X11 server and Xlib.
</para>
</abstract>

</bookinfo>

<chapter>
<title>TITLE</title>
<sect1 id="introduction">
<title>Introduction</title>
<para>
This is a proposal for an extension to the X11 server and Xlib.
It provides two capabilities:
</para>

<itemizedlist>
  <listitem>
    <para>
It allows a client to generate user input actions in the server without
requiring a user to be present.
    </para>
  </listitem>
  <listitem>
    <para>
It also allows a client to control the
handling of user input actions by the server.
    </para>
  </listitem>
</itemizedlist>

<para>
The capability
to allow a client to generate user input actions in the server
will be used by some of the X Testing Consortium Xlib tests.
Both capabilities will be used by the X Testing Consortium client exerciser
program.
These capabilities may also be useful in other programs.
</para>

<para>
This extension requires modification to device-dependent code in the
server.  Therefore it is not a 'portable' extension as defined by the
X11 Server Extensions document.  However, the majority of the code
and functionality of this extension will be implementation-independent.
</para>

</sect1>

<sect1 id="conventions_used_in_this_document">
<title>Conventions Used In This Document</title>

<para>
The naming conventions used in the Xlib documentation are followed
with these additions:
</para>

<itemizedlist>
  <listitem>
    <para>
The names of all functions defined in this extension begin with 'XTest',
with the first letter of each additional word capitalized.
    </para>
  </listitem>
  <listitem>
    <para>
The names of the protocol request structures follow the Xlib convention
of 'x&lt;name&gt;Req'.
    </para>
  </listitem>
  <listitem>
    <para>
The names of the protocol request minor type codes follow the Xlib convention
of 'X_&lt;name&gt;'.
    </para>
  </listitem>
  <listitem>
    <para>
The names of all other constants defined in this extension begin with 'XTest',
with the rest of the name in upper case letters.
    </para>
  </listitem>
  <listitem>
    <para>
All constants and structures defined in this extension will have their
values specified in the 'xtestext1.h' file (listed in section 5).
    </para>
  </listitem>
</itemizedlist>

</sect1>
<sect1 id="definition_of_terms">
<title>Definition Of Terms</title>

<sect2 id="input_actions">
<title>Input Actions</title>
<para>
Input actions are pointer movements, button presses and releases,
and key presses and releases.  They can be generated by a user or by a client
(using functions in this extension).
</para>
</sect2>

<sect2 id="user_input_actions">
<title>User Input Actions</title>
<para>
User input actions are input actions that are generated by the user
moving a pointing device (typically a mouse), pressing and releasing buttons on
the pointing device, and pressing and releasing keys on the keyboard.
</para>
</sect2>

</sect1>

<sect1 id="what_does_this_extension_do">
<title>What Does This Extension Do?</title>
<para>
Without this extension, user input actions are processed by the server,
and are converted into normal X events that are sent to the
appropriate client or clients.
</para>

<para>
This extension adds the following capabilities:
</para>

<itemizedlist>
  <listitem>
    <para>
Input actions may be sent from a client to the server to be
processed just as if the user had physically performed them.
The input actions are provided to the server in the form of X protocol
requests defined by this extension.
The information provided to the server includes what action should be
performed, and how long to delay before processing the action in the server.
    </para>
  </listitem>
  <listitem>
    <para>
User input actions may be diverted to a client before being processed by the
server.
The effect on the server is as if the user had performed no input action.
The user input actions are provided to the client in the form of X events
defined by this extension.
The information provided to the client includes what user input action
occurred and the delay between this user input action and the previous user
input action.
The client may then do anything it wishes with this information.
    </para>
  </listitem>
  <listitem>
    <para>
User input actions may be copied, with one copy going to the server in the
normal way, and the other copy being sent to a client as described above.
    </para>
  </listitem>
</itemizedlist>

</sect1>
<sect1 id="functions_in_this_extension">
<title>Functions In This Extension</title>

<sect2 id="high_level_functions">
<title>High Level Functions</title>

<para>
These functions are built on top of the low level functions described later.
</para>

<sect3 id="xtestmovepointer">
<title>XTestMovePointer</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestMovePointer</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
    <paramdef>int <parameter>device_id</parameter></paramdef>
    <paramdef>unsigned long <parameter>delay</parameter></paramdef>
    <paramdef>int <parameter>x</parameter></paramdef>
    <paramdef>int <parameter>y</parameter></paramdef>
    <paramdef>unsigned int <parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>device_id</term>
    <listitem>
      <para>
Specifies which pointer device was supposed to have caused the input action.
This is a provision for future support of multiple (distinguishable) pointer
devices, and should always be set to 0 for now.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>delay</term>
    <listitem>
      <para>
Specifies the time (in milliseconds) to wait before each movement
of the pointer.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>x, y</term>
    <listitem>
      <para>
Specifies the x and y coordinates to move the pointer to relative to the
root window for the specified display.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>count</term>
    <listitem>
      <para>
Specifies the number of 'delay, x, y' triplets contained in the
<emphasis>delay</emphasis>,
<emphasis>x</emphasis> and
<emphasis>y</emphasis> arrays.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestMovePointer</function>
function creates input actions to be sent to the the server.
The input actions will be accumulated in a request defined by this extension
until the request is full or the XTestFlush function is called.
They will then be sent to the server.
When the input actions are sent to the server, the input actions will cause
the server to think that the pointer was moved to the specified position(s),
with the specified delay before each input action.
</para>
<para>
The
<function>XTestMovePointer</function>
function will return -1 if there is an error, and 0 otherwise.
</para>
</sect3>

<sect3 id="xtestpressbutton">
<title>XTestPressButton</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestPressButton</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
    <paramdef>int <parameter>device_id</parameter></paramdef>
    <paramdef>unsigned long <parameter>delay</parameter></paramdef>
    <paramdef>unsigned int <parameter>button_number</parameter></paramdef>
    <paramdef>unsigned int <parameter>button_action</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<!-- .VL 15 -->
<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>device_id</term>
    <listitem>
      <para>
Specifies which button device was supposed to have caused the input action.
This is a provision for future support of multiple (distinguishable) button
devices, and should always be set to 0 for now.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>delay</term>
    <listitem>
      <para>
Specifies the time (in milliseconds) to wait before the input action.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>button_number</term>
    <listitem>
      <para>
Specifies which button is being acted upon.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>button_action</term>
    <listitem>
      <para>
Specifies the action to be performed (one of
<emphasis>XTestPRESS</emphasis>,
<emphasis>XTestRELEASE</emphasis>, or
<emphasis>XTestSTROKE</emphasis>).
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestPressButton</function>
function creates input actions to be sent to the the server.
The input actions will be accumulated in a request defined by this extension
until the request is full or the XTestFlush function is called.
They will then be sent to the server.
When the input actions are sent to the server, the input actions will cause
the server to think that the specified button was moved as specified.
</para>
<para>
The
<function>XTestPressButton</function>
function will return -1 if there is an error, and 0 otherwise.
</para>
</sect3>

<sect3 id="xtestpresskey">
<title>XTestPressKey</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestPressKey</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
    <paramdef>int <parameter>device_id</parameter></paramdef>
    <paramdef>unsigned long <parameter>delay</parameter></paramdef>
    <paramdef>unsigned int <parameter>keycode</parameter></paramdef>
    <paramdef>unsigned int <parameter>key_action</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<!-- .VL 12 -->
<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>device_id</term>
    <listitem>
      <para>
Specifies which keyboard device was supposed to have caused the input action.
This is a provision for future support of multiple (distinguishable) keyboard
devices, and should always be set to 0 for now.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>delay</term>
    <listitem>
      <para>
Specifies the time (in milliseconds) to wait before the input action.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>keycode</term>
    <listitem>
      <para>
Specifies which keycode is being acted upon.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>key_action</term>
    <listitem>
      <para>
Specifies the action to be performed (one of
<emphasis>XTestPRESS</emphasis>,
<emphasis>XTestRELEASE</emphasis>, or
<emphasis>XTestSTROKE</emphasis>).
      </para>
    </listitem>
  </varlistentry>
</variablelist>


<para>
The
<function>XTestPressKey</function>
function creates input actions to be sent to the the server.
The input actions will be accumulated in a request defined by this extension
until the request is full or the XTestFlush function is called.
They will then be sent to the server.
When the input actions are sent to the server, the input actions will cause
the server to think that the specified key on the keyboard was moved as
specified.
</para>

<para>
The
<function>XTestPressKey</function>
function will return -1 if there is an error, and 0 otherwise.
</para>

</sect3>
<sect3 id="xtestflush">
<title>XTestFlush</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestFlush</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<!-- .VL 9 -->
<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestFlush</function>
will send any remaining input actions to the server.
</para>

<para>
The
<function>XTestFlush</function>
function will return -1 if there is an error, and 0 otherwise.
</para>

</sect3>
</sect2>

<!-- .H 2 Low~Level~Functions -->
<sect2 id="low_level_functions">
<title>Low Level Functions</title>

<!-- .H 3 XTestGetInput -->
<sect3 id="xtestgetinput">
<title>XTestGetInput</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestGetInput</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
    <paramdef>int <parameter>action_handling</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>action_handling</term>
    <listitem>
      <para>
Specifies to the server what to do with the user input actions.  (one of
0, <emphasis>XTestPACKED_MOTION</emphasis> or
<emphasis>XTestPACKED_ACTIONS</emphasis>; optionally 'or'ed
with <emphasis>XTestEXCLUSIVE</emphasis>).
      </para>
    </listitem>
  </varlistentry>
</variablelist>


<para>
The
<function>XTestGetInput</function>
function tells the server to begin putting information about user input actions
into events to be sent to the client that called this function.  These events
can be read via the Xlib <function>XNextEvent</function>fR function.
</para>

<para>
The server assigns an event type of
<emphasis>XTestInputActionType</emphasis> to these events
to distinguish them from other events.
Since the actual value of the event type may vary depending on how many
extensions are included with an X11 implementation,
<emphasis>XTestInputActionType</emphasis> is a variable that will be
contained in the Xlib
part of this extension.  It may be referenced as follows:
</para>

<para>
extern int XTestInputActionType;
</para>

<itemizedlist>
  <listitem>
    <para>
An <emphasis>action_handling</emphasis> value of 0 causes the server
to send one user input action in each
<emphasis>XTestInputActionType</emphasis> event.
This can sometimes cause performance problems.
    </para>
  </listitem>
  <listitem>
    <para>
An <emphasis>action_handling</emphasis> value of
<emphasis>XTestPACKED_ACTIONS</emphasis> causes the server
to pack as many user input actions as possible into a
<emphasis>XTestInputActionType</emphasis> event.
This is needed if user input actions are happening rapidly (such as
when the user moves the pointer) to keep performance at a reasonable level.
    </para>
  </listitem>
  <listitem>
    <para>
An <emphasis>action_handling</emphasis> value of
<emphasis>XTestPACKED_MOTION</emphasis> causes the server
to pack only user input actions associated with moving the pointer.
This allows the
client to receive button and key motions as they happen without waiting for the
event to fill up, while still keeping performance at a reasonable level.
    </para>
  </listitem>
  <listitem>
    <para>
An <emphasis>action_handling</emphasis> value with
<emphasis>XTestEXCLUSIVE</emphasis> 'or'ed in
causes the server to send user input actions only to the client.
The effect on the server is as if the user had performed no input actions.
    </para>
  </listitem>
  <listitem>
    <para>
An <emphasis>action_handling</emphasis> value without
<emphasis>XTestEXCLUSIVE</emphasis>
causes the server to copy user input actions, sending one copy to the
client, and handling the other copy normally (as it would if this extension
were not installed).
    </para>
  </listitem>
</itemizedlist>

<para>
There are four types of input actions that are passed from the server
to the client.  They are:
</para>

<variablelist>
  <varlistentry>
    <term>key/button~state~change</term>
    <listitem>
      <para>
This type of input action contains the keycode of the key or button that
changed state;
whether the key or button is up or down,
and the time delay between this input action and the previous input action.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>pointer~motions</term>
    <listitem>
      <para>
This type of input action contains information about the motion of the
pointer when the pointer has only moved a short distance.
If the pointer has moved a long distance,
the pointer jump input action is used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>pointer~jumps</term>
    <listitem>
      <para>
This type of input action contains information about the motion of the
pointer when the pointer has moved a long distance.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>delays</term>
    <listitem>
      <para>
This type of input action is used when the delay between input actions is too
large to be held in the other input actions.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestGetInput</function>
function will return -1 if there is an error, and 0 otherwise.
</para>
<para>
An error code of <emphasis>BadAccess</emphasis> means that another client
has already requested that user input actions be sent to it.
</para>

</sect3>

<!-- .H 3 XTestStopInput -->
<sect3 id="xteststopinput">
<title>XTestStopInput</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestStopInput</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
</funcprototype>
</funcsynopsis>



<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestStopInput</function>
function tells the server to stop putting information about user input actions
into events.
The server will process user input actions normally (as it would
if this extension were not in the server).
</para>

<para>
The
<function>XTestStopInput</function>
function will return -1 if there is an error, and 0 otherwise.
</para>

<para>
An error code of <emphasis>BadAccess</emphasis> means that a request
was made to stop input when input has never been started.
</para>

</sect3>

<!-- .H 3 XTestFakeInput -->
<sect3 id="xtestfakeinput">
<title>XTestFakeInput</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestFakeInput</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
    <paramdef>char <parameter>*action_list_addr</parameter></paramdef>
    <paramdef>int <parameter>action_list_size</parameter></paramdef>
    <paramdef>int <parameter>ack_flag</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<!-- .VL 18 -->

<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>action_list_addr</term>
    <listitem>
      <para>
Specifies the address of an list of input actions to be sent to the server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>action_list_size</term>
    <listitem>
      <para>
Specifies the size (in bytes) of the list of input actions.
It may be no larger than <emphasis>XTestMAX_ACTION_LIST_SIZE</emphasis> bytes.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>ack_flag</term>
    <listitem>
      <para>
Specifies whether the server needs to send an event to indicate that its
input action buffer is empty (one of
<emphasis>XTestFAKE_ACK_NOT_NEEDED</emphasis> or
<emphasis>XTestFAKE_ACK_REQUEST</emphasis>).
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestFakeInput</function>
function tells the server to take the specified user input actions and process
them as if the user had physically performed them.
</para>

<para>
The server can only accept a limited number of input actions at one
time.  This limit can be determined by the
<function>XTestQueryInputSize</function> function
in this extension.
</para>

<para>
The client should set <emphasis>ack_flag</emphasis> to
<emphasis>XTestFAKE_ACK_NOT_NEEDED</emphasis>
on calls to <emphasis>XTestFakeInput</emphasis> that do not reach this limit.
</para>

<para>
The client should set <emphasis>ack_flag</emphasis> to
<emphasis>XTestFAKE_ACK_REQUEST</emphasis>
on the call to <emphasis>XTestFakeInput</emphasis> that reaches this limit.
</para>

<para>
When the server sees an <emphasis>ack_flag</emphasis> value of
<emphasis>XTestFAKE_ACK_REQUEST</emphasis>
it finishes processing its input action buffer, then sends an event with
type <emphasis>XTestFakeAckType</emphasis> to the client.
When the client reads this event, it knows that it is safe to resume
sending input actions to the server.
</para>

<para>
Since the actual value of the event type may vary depending on how many
extensions are included with an X11 implementation,
<emphasis>XTestFakeAckType</emphasis> is a variable that is contained
in the Xlib part of this extension.  It may be referenced as follows:
</para>

<para>
extern int XTestFakeAckType;
</para>

<para>
There are four types of input actions that are passed from the client
to the server.  They are:
</para>

<variablelist>
  <varlistentry>
    <term>key/button~state~change</term>
    <listitem>
      <para>
This type of input action contains the keycode of the key or button that
is to change state;
whether the key or button is to be up or down,
and the time to delay before changing the state of the key or button.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>pointer~motions</term>
    <listitem>
      <para>
This type of input action contains information about the motion of the
pointer when the pointer is to be moved a short distance,
and the time to delay before moving the pointer.
If the pointer is to be moved a long distance,
the pointer jump input action must be used.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>pointer~jumps</term>
    <listitem>
      <para>
This type of input action contains information about the motion of the
pointer when the pointer is to be moved a long distance,
and the time to delay before moving the pointer.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>delays</term>
    <listitem>
      <para>
This type of input action is used when the delay between input actions is too
large to be held in the other input actions.
      </para>
    </listitem>
  </varlistentry>
</variablelist>


<para>
The
<function>XTestFakeInput</function>
function will return -1 if there is an error, and 0 otherwise.
</para>

<para>
An error code of \fIBadAccess\fR means that another client has already
sent user input actions to the server, and the server has not finished
processing the user input actions.
</para>

</sect3>

<!-- .H 3 XTestQueryInputSize -->
<sect3 id="xtestqueryinputsize">
<title>XTestQueryInputSize</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestQueryInputSize</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
    <paramdef>unsigned long <parameter>size_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>size_return</term>
    <listitem>
      <para>
Returns the number of input actions that the server's input action buffer can
hold.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestQueryInputSize</function>
function asks the server to return the number of input actions that it can hold
in its input action buffer in the unsigned long pointed to by \fIsize_return\fR.
</para>
<para>
The
<function>XTestQueryInputSize</function>
function will return -1 if there is an error, and 0 otherwise.
</para>
</sect3>

<!-- .H 3 XTestReset -->
<sect3 id="xtestreset">
<title>XTestReset</title>

<funcsynopsis>
<funcprototype>
  <funcdef>int <function>XTestReset</function></funcdef>
    <paramdef>Display <parameter>*display</parameter></paramdef>
</funcprototype>
</funcsynopsis>


<variablelist>
  <varlistentry>
    <term>display</term>
    <listitem>
      <para>
Specifies the connection to the X server.
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
The
<function>XTestReset</function>
function tells the server to set everything having to do with this extension
back to its initial state.  After this call the server will act as if this
extension were not installed until one of the extension functions is called by
a client.  This function is not normally needed, but is included in case a
client wishes to clean up the server state, such as after a serious error.
</para>

<para>
The
<function>XTestReset</function>
function will return -1 if there is an error, and 0 otherwise.
</para>

</sect3>
</sect2>
</sect1>

<!-- .H 1 'xtestext1.h'~File~Listing -->
<!-- .so xtestext1.h -->
<!-- .TC 1 1 4 -->
</chapter>
</book>