File: API.txt

package info (click to toggle)
fcitx 1%3A4.2.9.9-2
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 19,800 kB
  • sloc: ansic: 134,151; cpp: 7,280; sh: 2,778; python: 800; xml: 345; makefile: 42
file content (928 lines) | stat: -rw-r--r-- 33,214 bytes parent folder | download | duplicates (4)
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
            IM Server Developers Kit - C Language Interface

                            Hidetoshi Tajima

                    X11R6 Xi18n Implementation Group

                              May 15, 1994

1.   Functions List

1.1.   Open IM Servive

XIMS IMOpenIM(Display display,...)

display                specifies the connection to the X server.
...                specifies the variable length argument list to set
                IMValues. For further information, see the Section 2
                "IMValues".

   IMOpenIM initializes the connection for the Input Method Service, and
also sets one or more IMValues which are specified by a variable length
argument list programming interface, and when succeeding to open the
connection, IMOpenIM allocates a new XIMS structure and returns it,
otherwise IMOpenIM returns NULL. XIMS is an opaque data structure to
abstract the Input Method Service.

   First, IMOpenIM initializes a preconnection method by which clients
can search for the IMserver. The convention of the preconnection varies
with the IMProtocol model as below, however, you don't have to pay much
attention to such difference, because IMOpenIM encapsulates it.

    Preconnection for R5 Ximp
        IMserver must create the selection owner window of the ATOM for
        the string, such as "_XIMP_%locale" or something, which are used
        by clients to search for the IMserver.
    Preconnection for R6 IMProtocol
        IMserver must create the selection owner window of the ATOM for
        the string, such as "@server=%im_name", and registers the ATOM
        with the list of "XIM_SERVERS" property of the default root
        window, which contains a list of ATOMs, each of which represents
        each available IMservers on the display.

   Second, IMOpenIM initialize a transport connection on which clients
and the IMserver can send and receive IMProtocols with each other. The
procedures to initialize the transport connection varies with the
transport mechanism as below, however, you don't have to pay any
attention to such difference, either, because IMOpenIM also encapsulates
it.

    Transport connection for X
        IMserver must intern a number of ATOMs for the properties which
        are used to set some IMserver specific feature and
        characteristic.
    Transport connection for TCP/IP
        IMserver must open a listening socket to wait for connection
        request from clients.

1.2.   Set IM Attributes

char *IMSetIMValues(XIMS ims,...)

ims                specifies the input method service.
...                specifies the variable length argument list to set
                IMValues.

   IMSetIMValues registers one or more IMValues, which are specified by
a variable length argument list programming interface, with the XIMS
structure. Note that IMOpenIM is also used to set all IMValues, and some
IMValues must be set when IMOpenIM is called.
   IMSetIMValues returns NULL if it succeeds to set all the IMValues,
otherwise, it returns the name of the first argument whose value could
not be registered.

1.3.   Get IM Attributes

char *IMGetIMValues(XIMS ims,...)

ims                specifies the input method service.
...                specifies the variable length argument list to get
                IMValues.

   IMGetIMValues gets one or more IMValues, which are specified by a
variable length argument list programming interface, from the XIMS
structure.
   IMGetIMValues returns NULL if it succeeds to get all the IMValues,
otherwise, it returns the name of the first argument whose value could
not be obtained.

1.4.   Close IM Service

void IMCloseIM(XIMS ims)

ims                specifies the input method service to be closed.

   IMCloseIM closes the connection which was opened by IMOpenIM.
IMCloseIM frees all the allocated data in the XIMS structure, then frees
the XIMS itself.

1.5.   Start Preediting

int IMPreeditStart(XIMS ims, XPointer im_protocol)

ims                specifies the input method service.
im_protocol        specifies the Input Protocol data.

   IMPreeditStart is used to start preeditting in case of Dynamic Event
Flow.

The structure for im_protocol varies with the IMProtocol models:

/* R5 Ximp */
typedef struct {
    INT32        type;
    CARD32        icid;
    Window        focus_win;
    long        fwin_sel_mask;
    CARD32        ximp_type_mask;
    Window        client_win;
} XIMPPreeditStateStruct;

/* R6 IMProtocol */
typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
    CARD16        icid;
} IMPreeditStateStruct;

1.6.   Stop Preediting

int IMPreeditEnd(XIMS ims, XPointer im_protocol)

ims                specifies the input method service.
im_protocol        specifies the Input Protocol data.

   IMPreeditEnd is used to stop preeditting in case of Dynamic Event
Flow. However, if you registered off-keys list using IMOffKeysList
IMValue, you might not need to use IMPreeditEnd, because IMdkit calls
IMPreeditEnd internally when it receives a key event matching one of
the registered off-keys. So, you are greatly encouraged to use
IMPreeditEnd only when you did *NOT* register any off-keys list.

1.7.   Forward back KeyEvent

void IMForwardEvent(XIMS ims, XPointer im_protocol)

ims                specifies the input method service.
im_protocol        specifies the Input Protocol data.

   IMForwardEvent is used to send back a non-filtered
KeyPress/KeyRelease Event.
   The structure for im_protocol varies with the IMProtocol models:

/* R5 Ximp */
typedef struct {
    INT32        type;
    CARD32        icid;
    Window        focus_win;
    long        fwin_sel_mask;
    CARD32        ximp_type_mask;
    Window        client_win;
    CARD32        keycode;
    CARD32        state;
    CARD32        time;
} XIMPKeyEventStruct;

/* R6 IMProtocol */
typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
    CARD16        icid;                /* input context ID */
    BITMASK16        sync_bit;        /* precessed synchronously or not */
    CARD16        serial_number;
    XEvent        event;                /* X event to be filtered */
} IMForwardEventStruct;

1.8.   Commit Conversion String

void IMCommitString(XIMS ims, XPointer im_protocol)

ims                specifies the input method service.
im_protocol        specifies the Input Protocol data.

   IMCommitString is used to send a committed string, which may contain
a localized text converted by the IMserver.
   The structure for im_protocol varies with the IMProtocol models:

/* R5 Ximp */
typedef struct {
    INT32        type;
    CARD32        icid;
    Window        focus_win;
    long        fwin_sel_mask;
    CARD32        ximp_type_mask;
    Window        client_win;
    char        *ctext;
} XIMPCommitStringStruct;

/* R6 IMProtocol */
typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
    CARD16        icid;                /* input context ID */
    CARD16        flag;
        /* bit combination to tell the receiver what to do */
                #0001        : process it synchroously, return XIM_SYNC_REPLY
                #0002        : Lookup Chars
                #0004        : Lookup KeySym
                #0006        : Lookup Both = Lookup Chars and KeySym
         */
    KeySym        keysym;                /* returned keysym */
    char        *commit_string;        /* string to commit to XIM client */
} IMCommitStruct;

1.9.   Call Callback

int IMCallCallback(XIMS ims, XPointer im_protocol)

ims                specifies the input method service.
im_protocol        specifies the Input Protocol data.

   IMCallCallback is used for your IMserver to send a callback request
asynchronously with the previous IMProtocol request. The type of the
callback request must be set in the proper members of the im_protocol
data structure by your IMserver. In addition, it's up to you to declare
a new IMProtocol structure before you begin the callback requests.
   The structures for im_protocol varies with the IMProtocol models:

/* R6 IMProtocol */
   The type of the callback request must be set in major_code and
minor_code members in the IMProtocol structure, e.g., you can start
geometry management callback as follows;

        IMGeometryCBStruct geometry;
        ...
        geometry.major_code = XIM_GEOMETRY;
        geometry.connect_id = previous_request->any.connect_id;
        ...
        IMCallCallback(ims, (IMProtocol)&geometry);

   The structures for R6 IMProtocol callbacks contain:

/* for Geometry Callback */
typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
    CARD16        icid;
} IMGeometryCBStruct;

/* for Preedit Callback */
typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
    CARD16        icid;
    union {
        int        return_value;                        /* PreeditStart */
        XIMPreeditDrawCallbackStruct draw;        /* PreeditDraw */
        XIMPreeditCaretCallbackStruct caret;         /* PreeditCaret */
    } todo;
} IMPreeditCBStruct;

/* for Status Callback */
typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
    CARD16        icid;
    union {
        XIMStatusDrawCallbackStruct draw;
    } todo;
} IMStatusCBStruct;

   The structures for R5 Ximp callbacks contain:

/* for Geometry Callback */
typedef struct {
    INT32        type;
    CARD32        icid;
    Window        focus_win;
    long        fwin_sel_mask;
    CARD32        ximp_type_mask;
    Window        client_win;
} XIMPAnyStruct;

/* for Preedit Callback */
typedef struct {
    INT32        type;
    CARD32        icid;
    Window        focus_win;
    long        fwin_sel_mask;
    CARD32        ximp_type_mask;
    Window        client_win;
    union {
        int        return_value;                        /* PreeditStart */
        XIMPreeditDrawCallbackStruct draw;        /* PreeditDraw */
        XIMPreeditCaretCallbackStruct caret;         /* PreeditCaret */
    } todo;
} XIMPPreeditCBStruct;

/* for Status Callback */
typedef struct {
    INT32        type;
    CARD32        icid;
    Window        focus_win;
    long        fwin_sel_mask;
    CARD32        ximp_type_mask;
    Window        client_win;
    union {
        XIMStatusDrawCallbackStruct draw;        /* StatusDraw */
    } todo;
} XIMPStatusCBStruct;

2.   IMValues

2.1.   IMModifiers

   The IMModifiers argument, of type string, specifies the name of the
IMProtocol model. At the current release, only three names are accepted
by IMdkit.
        "Xi18n"                specifies the R6 standard IMProtocol model
        "XIMP"                specifies the R5 Ximp model.

   The IMModifiers argument must be set only once when IMOpenIM is
called, and never be changed on the fly.

2.2.   IMServerWindow

   The IMServerWindow argument, of type Window, specifies the window
which identifies a method of preconnection with XIM clients. In addition
to this primary purpose, the IMServerWindow might be used for any other
purposes, which depends on the IMProtocol model to be used.
   If this argument is unspecified, a default window might be provided
by IMdkit, which depends on the IMProtocol model to be used, and if it
is specified, it must be done only once by either IMOpenIM or
IMSetIMValues, and never be changed on the fly.

2.3.   IMServerName

   The IMServerName argument, of type string, specifies the name of the
IMserver. This argument might be a part of the IMserver identifiers
by which XIM clients will search for the IMserver.
   The IMServerName argument must be set only once when IMOpenIM is
called, and never be changed on the fly.

2.4.   IMLocale

   The IMLocale argument, of type string, specifies a list of locales
the IMserver supports. This argument might be a part of the IMserver
identifiers which is used for XIM clients to search for the IMserver.
   The IMLocale argument must be set only once when IMOpenIM is called,
and never be changed on the fly.

2.5.   IMServerTransport

   The IMServerTransport argument, of type string, specifies the name
for the transport connection mechanism the IMserver uses. This argument
might be a part of the IMserver identifiers which is used for XIM
clients to search for the IMserver.
   The preregistered formats for this argument are as follows.(*1)

(*1) Reter to "The Input Method Protocol", Appendix B:
  The list of transport specific IM Server address format registered

TCP/IP Names
------------
   Syntax for Internet domain names:

        <TCP name> ::= "tcp/"<hostname>":"<ipportnumber>

           where <hostname> is either symbolic or numeric decimal form of
        the host machine name, and <ipportnumber> is the port on which
        the IMserver is listening for connections.

   Syntax for system internal domain names:

        <local name> ::= "locale/"<hostname>":"<pathname>

        where <pathname> is a path name of socket address.

DECnet Names
------------
   Syntax for DECnet names:

        <DECnet name> ::= "decnet/"<nodename>"::IMSERVER$"<objname>

        where <nodename> is either symbolic or numeric decimal form of
        the DECnet address, and <objname> is normal, case-insensitive
        DECnet object name.

X Names
-------
   Syntax for X names:

        <X name> ::= "X/"

   The IMServerTransport argument must be set only once when IMOpenIM is
called, and never be changed on the fly.

2.6.   IMInputStyles

   The IMInputStyles argument, of type XIMStyles, specifies a list of
the input styles the IMserver supports.
   If this argument is unspecified, a default list might be provided by
IMdkit, which depends on the IMProtocol model to be used, and it can be
set by either IMOpenIM or IMSetIMValues, but should not be changed on
the fly.

2.7.   IMProtocolHandler

   The IMProtocolHandler argument, of type IMProtoHandler, specifies the
callback function which is called each time when IMMainLoop receives an
IMProtocol input from XIM clients. The generic prototype of the
IMProtocolHandler function is;

typedef int (*IMProtoHandler)();

int ProtocolHandlerProc(ims, call_data)
XIMS ims;
XPointer call_data;

call_data        points to a IMProtocol structure.

2.8.   IMOnKeysList

   The IMOnKeysList argument, of type XIMTriggerKeys, specifies the list
of preediting start-keys for Dynamic Event Flow model. The IMOnKeysList
IMValue is mandatary for IMserver to support Dynamic Event Flow Model,
so that the IMlibrary can send the IMserver a request to start
preediting with the appearance of one of these registered on-keys.
   If the IMOnKeysList is left unspecified, no default will be provided,
and Static Event Flow model will be used.
   XIMTriggerKeys structure is defined by IMdkit as follows:

typedef struct {
    CARD32        keysym;
    CARD32        modifier;
    CARD32        modifier_mask;
} XIMTriggerKey;

typedef struct {
    unsigned short count_keys;
    XIMTriggerKey *keylist;
} XIMTriggerKeys;

2.9.   IMOffKeysList

   The IMOnKeysList argument, of type XIMTriggerKeys, specifies the list
of preediing end-keys for Dynamic Event Flow model. The IMOffKeysList
IMValue is optional for IMserver to support Dynamic Event Flow Model.
   When it is specified, the IMlibrary can send the IMserver a request
to stop preediting with the appearance of one of these registered
off-keys, while it's unspecified, the IMserver calls IMPreeditEnd to
notify the IMlibrary to stop preeditting when the IMserver would like to
stop preeditring.
   If the IMOffKeysList is left unspecified, no default will be
provided.

2.10.   IMEncodingList

   The IMEncodingList argument, of type XIMEncodings, specifies the list
of encodings the IMserver supports. XIM client will be notified of this
argument immediately after it makes a connection with the IMserver.
   The IMEncdoingList argument is used to specify which encodings can be
used to exchange localized-text between the IMserver and XIM clients.
   If it's left unspecified, only "COMPOUND_TEXT" encoding will be used
as a fallback default.
   XIMEncodings structure is defined by IMdkit as follows:

typedef char *XIMEncoding;

typedef struct {
    unsigned short count_encodings;
    XIMEncoding *supported_encodings;
} XIMEncodings;

2.11.   IMFilterEventMask

   The IMFilterEventMask argument, of type long, specifies the events
which should be filtered by the IMserver during the preeditting is on
going.
   If it's left unspecified, KeyPressMask (1L<<0) will be fallback
default.

2.12.   IMProtocolDepend

   The IMProtocolDepend argument is used to specify special IM values
for each IMProtocol model, if any. This attribute is passed to
IMOpenIM, IMSetIMValues or IMGetIMValues as a nested variable length
list generated with XVaCreateNestedList(). At this release, the
names in the IMProtocolDepend list are defined only for R5 Ximp model,
as below.

2.12.1.   R5 Ximp dependent IM Values

XIMPVersion

   The XIMPVersion argument, of type string, specifies the version of R5
Ximp model.
        value                meaning
        ---------------------------------------------
        "3.5"                supports Ximp version 3.5 model
        "4.0"                supports Ximp version 4.0 model

XIMPType

   The XIMPVersion argument, pointer to a list of type unsigned long,
specifies a list of bitmask combinations, each of which indicates the
event flow model your IMserver supports. All possible values to be
appeared in the list are defined as follows.(*)

(*) Refer to "Protocol Specification for the Distributes Input System on
the X Window System, Version 11", which contains in X11R5 contribuion.

  XIMP_BE_TYPE1
        back-end type, which IMlibrary recognizes registered keys and
        notifies a server to start processing key events.
  XIMP_FE_TYPE1
        front-end type, which IMlibrary recognizes registered keys and
        notifies a server to start processing key events.
  XIMP_BE_TYPE2
        back-end type, which IMlibrary does not recognize any registered
        keys and. IMserver will always the first to process key events.
  XIMP_FE_TYPE2
        front-end type, which IMlibrary does not recognize any
        registered keys and. IMserver will always the first to process
        key events.
  XIMP_FE_TYPE3
        front-end type, which key events are always passed to both
        IMserver and IMlibrary. Both of them recognize registered keys.
  XIMP_SYNC_BE_TYPE1
        XIMP_BE_TYPE1 & KeyPress is transferred synchronously.
  XIMP_SYNC_BE_TYPE2
        XIMP_BE_TYPE2 & KeyPress is transferred synchronously.

XIMPExtension

   The XIMPExtension argument is used to set/unset the pre-registered
extensions to be valid. This list is also a nested variable length list
generated with XVaCreateNestedList(). At this release, the
pre-registered extensins appeared in the XIMPExtension list are defined
as below.

  XIMPExtStatusWin
        If it is appeared in the list, the XNExtXimp_StatusWindow input
        context        attribute is valid to set the status window. The
        attribute value        isn't evaluated.
  XIMPExtBackFront
        If it is appeared in the list, the XNExtXimp_Backfront input
        context is valid to select the front-end method or back-end
        method. The attribute value isn't evaluated.
  XIMPExtConversion
        If it is appeared in the list, the XNExtXimp_Conversion input
        context is valid to set the input mode. The attribute value
        isn't evaluated.

3.   X IMProtocol Strucutures

   For each X IMProtocol input, a corresponding structure is defined in
public header files of IMdkit. <X11/Ximd/Xi18n.h> defines all IMProtocol
structures for R6 standard IMProtocol model, and <X11/Ximd/Ximp.h>
defines all for R5 Ximp model.

3.1.   R6 IMProtocol

3.1.1. IMProtocol union data structure
   In R6 standard IMProtocol model, all the event structures have the
following common members:

typedef struct {
    int major_code;        /* major code of last IMProtocol */
    int minor_code;        /* minor code of last IMProtocol */
    CARD16 connect_id;        /* client connection ID */
} IMAnyStruct;

   The major_code and minor_code specify the IMProtocol type constant
name that uniquely identifies itself.
   In addition to the individual structures declared for each IMProtocol
type, the IMProtocol structure is a union of the individual structures
declared for each IMProtocol type. Depending on the type, you should
access members of each IMProtocol by using the IMProtocol union.

typedef union _IMProtocol {
    int        major_code;
    IMAnyStruct any;
    IMConnectStruct imconnect;
    IMDisConnectStruct imdisconnect;
    IMOpenStruct imopen;
    IMCloseStruct imclose;
    IMQueryExtensionStruct queryext;
    IMGetIMValuesStruct getim;
    IMEncodingNegotiationStruct encodingnego;
    IMExtSetEventMaskStruct extsetevent;
    IMExtForwardKeyEventStruct extforward;
    IMExtMoveStruct extmove;
    IMSetEventMaskStruct setevent;
    IMChangeICStruct changeic;
    IMDestroyICStruct destroyic;
    IMResetICStruct resetic;
    IMChangeFocusStruct changefocus;
    IMCommitStruct commitstring;
    IMForwardEventStruct forwardevent;
    IMTriggerNotifyStruct triggernotify;
    IMErrorStruct imerror;
    IMGeometryCBStruct geometry_callback;
    IMPreeditCBStruct preedit_callback;
    IMStatusCBStruct status_callback;
    long pad[32];
} IMProtocol;

   The first two entries of any IMProtocol structure are always the
major_code and minor_code members, which specifies the IMProtocol type.
The third member is the connect_id member, just provided for IMdkit
internal use to distinguish a client from each other.

3.1.2. Protocol Processing

   Some of IMProtocol requests sent by the IMlibrary are processed
internally by IMdkit without passing them to your IMservers, because
IMdkit can determin the answer to such IMProtocol requests only by
using the IMValues which you have set in the XIMS structure.
   At this release, the following four IMProtocol requests is processed
in IMdkit itself, and wouldn't forward to your IMserver:
        o XIM_CONNECT                -> XIM_CONNECT_REPLY
        o XIM_DISCONNECT        -> XIM_DISCONNECT_REPLY
        o XIM_QUERY_EXTENSION        -> XIM_QUERY_EXTENSION_REPLY
        o XIM_GET_IM_VALUES        -> XIM_GET_IM_VALUES_REPLY
   So, you don't have to know the details of the corresponding
IMProtocol structures for these IMProtocol requests.

   On the other hand, you will need to deal with the following requests
for yourselves:
        o XIM_OPEN
        o XIM_CLOSE
        o XIM_SET_IC_FOCUS and XIM_UNSET_IC_FOCUS
        o XIM_DESTROY_IC
        o XIM_RESET_IC
        o XIM_CREATE_IC, XIM_SET_IC_VALUES and XIM_GET_IC_VALUES
        o XIM_TRIGGER_NOTIFY
        o XIM_FORWARD_EVENT
   However, you don't have to receive any raw packets, but can receive
the corresponding IMProtocol structures in your IMProtocolHandler
callback function. Further, you don't have to send a reply for
yourselves, but IMdkit will send a reply soon after your
IMProtocolHandler returns. If your IMProtocolHandler returns True,
IMdkit will send the proper reply to the previous request, and if it
returns False, IMdkit will send XIM_ERROR reply to the XIM client.
   The following IMProtocol structures are what you will actually
receive instead of IMProtocol requests in your IMProtocolHandler
function.

IMOpenStruct
------------
   The IMOpenStruct structure is used for XIM_OPEN and XIM_OPEN_REPLY
requests. The structure contains:

typedef struct {
    int length;
    char *name;
} XIMStr;

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    XIMStr lang;
} IMOpenStruct;

   Your IMserver should check lang field to know which language service
is required by the new client, which is identified with connect_id
member.

IMCloseStruct
-------------
   The IMCloseStruct structure is used for XIM_CLOSE and XIM_CLOSE_REPLY
requests. The structure contains:

typedef struct {
    int                major_code;
    int                minor_code;
    CARD16        connect_id;
} IMCloseStruct;

   Your IMserver should check connect_id member to know which input
method connection should be closed.

IMChangeFocusStruct
-------------------
   The IMChangeFocusStruct structure is used for XIM_SET_IC_FOCUS and
XIM_UNSET_IC_FOCUS requests. The structure contains:

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    CARD16 icid;        /* input context ID to change focus */
} IMChangeFocusStruct;

   Your IMserver should check icid member to know which input context
should be focusd or unfocusd.

IMDestroyICStruct
-----------------
   The IMDestroyICStruct structure is used for XIM_DESTROY_IC and
request. The structure contains:

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    CARD16 icid;        /* input context ID to destroy */
} IMDestroyICStruct;

   Your IMserver should check icid member to know which input context
should be destroyed.

IMResetICStruct
---------------
   The IMResetICStruct structure is used for XIM_RESET_IC request. The
structure contains:

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    CARD16 icid;        /* input context ID to reset */
    CARD16 length;        /* length of committed string below */
    char *commit_string; /* string to commit to XIM client */
} IMResetICStruct;

   Your IMserver should check icid member to know which input context
should be reset.

IMChangeICStruct
----------------
   The IMChangeICStruct structure is used for XIM_CREATE_IC,
XIM_SET_IC_VALUES and XIM_GET_IC_VALUES requests. The structures
contain:

/*
 *  value type for IC defined in XimProto.h
 */
#define        XimType_SeparatorOfNestedList         0
#define        XimType_CARD8                         1
#define        XimType_CARD16                         2
#define        XimType_CARD32                         3
#define        XimType_STRING8                         4
#define        XimType_Window                         5
#define        XimType_XIMStyles                10
#define        XimType_XRectangle                11
#define        XimType_XPoint                        12
#define XimType_XFontSet                13
#define XimType_XIMOptions                14
#define XimType_XIMHotKeyTriggers        15
#define XimType_XIMHotKeyState                16
#define XimType_XIMStringConversion        17
#define        XimType_NEST                        0x7fff

typedef struct {
    int attribute_id;        /* ID for this IC */
    CARD16 name_length;        /* length of IC name below */
    char *name;                /* IC name */
    int value_length;        /* length of IC value below */
    void *value;        /* IC value */
    int type;                /* value type for IC, see above */
} XICAttribute;

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    CARD16 icid;
        /* input context ID:
           for each CREATE, different ID is expected to be returned.
           for each SET, it shows the ID to set.
           for each GET, it shows the ID to get.
         */
    CARD16 preedit_attr_num;        /* number of preedit_attr list below */
    CARD16 status_attr_num;        /* number of preedit_attr list below */
    CARD16 ic_attr_num;                /* number of ic_attr list below */
    XICAttribute *preedit_attr;        /* IC values for preedit attribute */
    XICAttribute *status_attr;        /* IC values for status attribute */
    XICAttribute *ic_attr;        /* IC values for other attributes */
} IMChangeICStruct;

   When XIM_SET_IC_VALUES or XIM_GET_IC_VALUES, your IMserver should
check icid member to know which input context should be specified. When
XIM_CREATE_IC, your IMserver should set icid member to identify the
input context newly created.

IMTriggerNotifyStruct
---------------------
   The IMTriggerNotifyStruct structure is used for XIM_TRIGGER_NOTIFY
request. The structure contains:

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    CARD16 icid;
    CARD32 flag;
    CARD32 key_index;
    CARD32 event_mask;
} IMTriggerNotifyStruct;

IMForwardEventStruct
--------------------
   The IMForwardEventStruct structure is used for XIM_FORWARD_EVENT
request. The structure contains:

typedef struct {
    int major_code;
    int minor_code;
    CARD16 connect_id;
    CARD16 icid;        /* input context ID */
    BITMASK16 sync_bit;        /* precessed synchronously or not */
    CARD16 serial_number;
    XEvent event;        /* X event to be filtered */
} IMForwardEventStruct;

3.2.   R5 Ximp IMProtocol

3.2.1. XIMProtocol union data structure

   In R5 Ximp IMProtocol model, all the event structures have the
following common members:

typedef struct {
    INT32 type;                /* message type */
    CARD32 icid;        /* input context ID */
    Window focus_win;        /* focus window */
    long fwin_sel_mask; /* focus window select-mask */
    CARD32 ximp_type_mask; /* Ximp event flow type */
    Window client_win;        /* client window */
} XIMPAnyStruct;

   The type member specifies the Ximp IMProtocol type constant name that
uniquely identies itself.
   In addition to the individual structures declared for each Ximp
XIMProtocol type, the Ximp IMProtocol structure is a union of the
individual structures declared for each Ximp IMProtocol type. Depending
on the type, you should access members of each Ximp IMProtocol by using
the XIMProtocol union.

typedef union _IMPProtocol {
    int                                type;
    XIMPAnyStruct                any;
    XIMPKeyEventStruct                keyevent;
    XIMPICValuesStruct                create;
    XIMPICValuesStruct                setvalue;
    XIMPICValuesStruct                getvalue;
    XIMPAnyStruct                destroy;
    XIMPAnyStruct                regkey;
    XIMPAnyStruct                setfocus;
    XIMPAnyStruct                unsetfocus;
    XIMPClientWindowStruct        clientwin;
    XIMPFocusWindowStruct        focuswin;
    XIMPMoveStruct                move;
    XIMPEventMaskNotifyStruct        evmasknotify;
    XIMPExtensionStruct                extension;
    XIMPReadPropStruct                readprop;
    XIMPResetStruct                reset;
    XIMPCommitStringStruct        commitstring;
    XIMPErrorStruct                error;
    XIMPAnyStruct                geometry_cb;
    XIMPPreeditCBStruct                preedit_cb;
    XIMPStatusCBStruct                status_cb;
    long                        pad[24];
} IMPProtocol;

   The first entry of any XIMProtocol structure is always the
type member, which specifies the Ximp IMProtocol type.

4.   Writing IMservers

When writing an IMserver that uses the IMdkit, you should make sure that
your IMserver performs the following:

   1. Include <X11/Xlib.h> in your IMserver programs.

   2. Include <X11/Ximd/IMdkit.h>. This header file defines all the
   necessary data types and IMdkit functions that you need to use.

   3. Include <X11/Ximd/Xi18n.h> for R6 standard IMProtocol, or
   <X11/Ximd/Ximp.h> for R5 Ximp IMProtocol, respectively.

   4. Call the IMOpenIM function with all the necessary IMValues to
   initialize the connection. The names of each IMValues have a global
   symbol that begins with IM to help catch spelling errors. For
   example, IMModifiers is defined for the XIMProtocol model, and
   IMLocale is defined for the locale resource. For further information,
   see "Section 1.1 Open IM Service" and Section 2 "IMValues"

   5. To set additional IMValues or override the existing IMValues you
   set by IMOpenIM, use IMSetIMValues. You can also use IMGetIMValues to
   look up at existing IMValues. Note that some of IMValues must be set
   at the IM service creation time, and never be changed by
   IMSetIMValues.

   6. You must set the IMProtocol callback routine by the
   IMProtocolHandler argument with IMOpenIM or IMSetIMValues functions.
   This callback is called whenever the IMProtocol is delivered by XIM
   clients.

   7. Now you should select all the necessary X events for your windows
   with XSelectInput function, and map the windows with XMapWindow
   function, then sit in a loop processing events as follows.

    for (;;) {
        XEvent event;
        XNextEvent(your_display, &event);
        if (XFilterEvent(&event, NULL) == True)
          continue;
        YourXEventHandler(&event);
    }

   Here, all the IMProtocols you need are passed to your IMProtocol
   callback routine by X Filtering mechanism of XFilterEvent function,
   and all unfiltered X events you want are passed to YourXEventHandler
   function above.

   8. Link your IMserver with libXimd (the IMdkit library) and libX11
   (the core X library). The following provides a sample command line:

        cc -o sampleIM sampleIM.c -lXimd -lX11