1 2 IM Server Developers Kit - C Language Interface 3 4 Hidetoshi Tajima 5 6 X11R6 Xi18n Implementation Group 7 8 May 15, 1994 9 101. Functions List 11 121.1. Open IM Servive 13 14XIMS IMOpenIM(Display display,...) 15 16display specifies the connection to the X server. 17... specifies the variable length argument list to set 18 IMValues. For further information, see the Section 2 19 "IMValues". 20 21 IMOpenIM initializes the connection for the Input Method Service, and 22also sets one or more IMValues which are specified by a variable length 23argument list programming interface, and when succeeding to open the 24connection, IMOpenIM allocates a new XIMS structure and returns it, 25otherwise IMOpenIM returns NULL. XIMS is an opaque data structure to 26abstract the Input Method Service. 27 28 First, IMOpenIM initializes a preconnection method by which clients 29can search for the IMserver. The convention of the preconnection varies 30with the IMProtocol model as below, however, you don't have to pay much 31attention to such difference, because IMOpenIM encapsulates it. 32 33 Preconnection for R5 Ximp 34 IMserver must create the selection owner window of the ATOM for 35 the string, such as "_XIMP_%locale" or something, which are used 36 by clients to search for the IMserver. 37 Preconnection for R6 IMProtocol 38 IMserver must create the selection owner window of the ATOM for 39 the string, such as "@server=%im_name", and registers the ATOM 40 with the list of "XIM_SERVERS" property of the default root 41 window, which contains a list of ATOMs, each of which represents 42 each available IMservers on the display. 43 44 Second, IMOpenIM initialize a transport connection on which clients 45and the IMserver can send and receive IMProtocols with each other. The 46procedures to initialize the transport connection varies with the 47transport mechanism as below, however, you don't have to pay any 48attention to such difference, either, because IMOpenIM also encapsulates 49it. 50 51 Transport connection for X 52 IMserver must intern a number of ATOMs for the properties which 53 are used to set some IMserver specific feature and 54 characteristic. 55 Transport connection for TCP/IP 56 IMserver must open a listening socket to wait for connection 57 request from clients. 58 591.2. Set IM Attributes 60 61char *IMSetIMValues(XIMS ims,...) 62 63ims specifies the input method service. 64... specifies the variable length argument list to set 65 IMValues. 66 67 IMSetIMValues registers one or more IMValues, which are specified by 68a variable length argument list programming interface, with the XIMS 69structure. Note that IMOpenIM is also used to set all IMValues, and some 70IMValues must be set when IMOpenIM is called. 71 IMSetIMValues returns NULL if it succeeds to set all the IMValues, 72otherwise, it returns the name of the first argument whose value could 73not be registered. 74 751.3. Get IM Attributes 76 77char *IMGetIMValues(XIMS ims,...) 78 79ims specifies the input method service. 80... specifies the variable length argument list to get 81 IMValues. 82 83 IMGetIMValues gets one or more IMValues, which are specified by a 84variable length argument list programming interface, from the XIMS 85structure. 86 IMGetIMValues returns NULL if it succeeds to get all the IMValues, 87otherwise, it returns the name of the first argument whose value could 88not be obtained. 89 901.4. Close IM Service 91 92void IMCloseIM(XIMS ims) 93 94ims specifies the input method service to be closed. 95 96 IMCloseIM closes the connection which was opened by IMOpenIM. 97IMCloseIM frees all the allocated data in the XIMS structure, then frees 98the XIMS itself. 99 1001.5. Start Preediting 101 102int IMPreeditStart(XIMS ims, XPointer im_protocol) 103 104ims specifies the input method service. 105im_protocol specifies the Input Protocol data. 106 107 IMPreeditStart is used to start preeditting in case of Dynamic Event 108Flow. 109 110The structure for im_protocol varies with the IMProtocol models: 111 112/* R5 Ximp */ 113typedef struct { 114 INT32 type; 115 CARD32 icid; 116 Window focus_win; 117 long fwin_sel_mask; 118 CARD32 ximp_type_mask; 119 Window client_win; 120} XIMPPreeditStateStruct; 121 122/* R6 IMProtocol */ 123typedef struct { 124 int major_code; 125 int minor_code; 126 CARD16 connect_id; 127 CARD16 icid; 128} IMPreeditStateStruct; 129 1301.6. Stop Preediting 131 132int IMPreeditEnd(XIMS ims, XPointer im_protocol) 133 134ims specifies the input method service. 135im_protocol specifies the Input Protocol data. 136 137 IMPreeditEnd is used to stop preeditting in case of Dynamic Event 138Flow. However, if you registered off-keys list using IMOffKeysList 139IMValue, you might not need to use IMPreeditEnd, because IMdkit calls 140IMPreeditEnd internally when it receives a key event matching one of 141the registered off-keys. So, you are greatly encouraged to use 142IMPreeditEnd only when you did *NOT* register any off-keys list. 143 1441.7. Forward back KeyEvent 145 146void IMForwardEvent(XIMS ims, XPointer im_protocol) 147 148ims specifies the input method service. 149im_protocol specifies the Input Protocol data. 150 151 IMForwardEvent is used to send back a non-filtered 152KeyPress/KeyRelease Event. 153 The structure for im_protocol varies with the IMProtocol models: 154 155/* R5 Ximp */ 156typedef struct { 157 INT32 type; 158 CARD32 icid; 159 Window focus_win; 160 long fwin_sel_mask; 161 CARD32 ximp_type_mask; 162 Window client_win; 163 CARD32 keycode; 164 CARD32 state; 165 CARD32 time; 166} XIMPKeyEventStruct; 167 168/* R6 IMProtocol */ 169typedef struct { 170 int major_code; 171 int minor_code; 172 CARD16 connect_id; 173 CARD16 icid; /* input context ID */ 174 BITMASK16 sync_bit; /* precessed synchronously or not */ 175 CARD16 serial_number; 176 XEvent event; /* X event to be filtered */ 177} IMForwardEventStruct; 178 1791.8. Commit Conversion String 180 181void IMCommitString(XIMS ims, XPointer im_protocol) 182 183ims specifies the input method service. 184im_protocol specifies the Input Protocol data. 185 186 IMCommitString is used to send a committed string, which may contain 187a localized text converted by the IMserver. 188 The structure for im_protocol varies with the IMProtocol models: 189 190/* R5 Ximp */ 191typedef struct { 192 INT32 type; 193 CARD32 icid; 194 Window focus_win; 195 long fwin_sel_mask; 196 CARD32 ximp_type_mask; 197 Window client_win; 198 char *ctext; 199} XIMPCommitStringStruct; 200 201/* R6 IMProtocol */ 202typedef struct { 203 int major_code; 204 int minor_code; 205 CARD16 connect_id; 206 CARD16 icid; /* input context ID */ 207 CARD16 flag; 208 /* bit combination to tell the receiver what to do */ 209 #0001 : process it synchroously, return XIM_SYNC_REPLY 210 #0002 : Lookup Chars 211 #0004 : Lookup KeySym 212 #0006 : Lookup Both = Lookup Chars and KeySym 213 */ 214 KeySym keysym; /* returned keysym */ 215 char *commit_string; /* string to commit to XIM client */ 216} IMCommitStruct; 217 2181.9. Call Callback 219 220int IMCallCallback(XIMS ims, XPointer im_protocol) 221 222ims specifies the input method service. 223im_protocol specifies the Input Protocol data. 224 225 IMCallCallback is used for your IMserver to send a callback request 226asynchronously with the previous IMProtocol request. The type of the 227callback request must be set in the proper members of the im_protocol 228data structure by your IMserver. In addition, it's up to you to declare 229a new IMProtocol structure before you begin the callback requests. 230 The structures for im_protocol varies with the IMProtocol models: 231 232/* R6 IMProtocol */ 233 The type of the callback request must be set in major_code and 234minor_code members in the IMProtocol structure, e.g., you can start 235geometry management callback as follows; 236 237 IMGeometryCBStruct geometry; 238 ... 239 geometry.major_code = XIM_GEOMETRY; 240 geometry.connect_id = previous_request->any.connect_id; 241 ... 242 IMCallCallback(ims, (IMProtocol)&geometry); 243 244 The structures for R6 IMProtocol callbacks contain: 245 246/* for Geometry Callback */ 247typedef struct { 248 int major_code; 249 int minor_code; 250 CARD16 connect_id; 251 CARD16 icid; 252} IMGeometryCBStruct; 253 254/* for Preedit Callback */ 255typedef struct { 256 int major_code; 257 int minor_code; 258 CARD16 connect_id; 259 CARD16 icid; 260 union { 261 int return_value; /* PreeditStart */ 262 XIMPreeditDrawCallbackStruct draw; /* PreeditDraw */ 263 XIMPreeditCaretCallbackStruct caret; /* PreeditCaret */ 264 } todo; 265} IMPreeditCBStruct; 266 267/* for Status Callback */ 268typedef struct { 269 int major_code; 270 int minor_code; 271 CARD16 connect_id; 272 CARD16 icid; 273 union { 274 XIMStatusDrawCallbackStruct draw; 275 } todo; 276} IMStatusCBStruct; 277 278 The structures for R5 Ximp callbacks contain: 279 280/* for Geometry Callback */ 281typedef struct { 282 INT32 type; 283 CARD32 icid; 284 Window focus_win; 285 long fwin_sel_mask; 286 CARD32 ximp_type_mask; 287 Window client_win; 288} XIMPAnyStruct; 289 290/* for Preedit Callback */ 291typedef struct { 292 INT32 type; 293 CARD32 icid; 294 Window focus_win; 295 long fwin_sel_mask; 296 CARD32 ximp_type_mask; 297 Window client_win; 298 union { 299 int return_value; /* PreeditStart */ 300 XIMPreeditDrawCallbackStruct draw; /* PreeditDraw */ 301 XIMPreeditCaretCallbackStruct caret; /* PreeditCaret */ 302 } todo; 303} XIMPPreeditCBStruct; 304 305/* for Status Callback */ 306typedef struct { 307 INT32 type; 308 CARD32 icid; 309 Window focus_win; 310 long fwin_sel_mask; 311 CARD32 ximp_type_mask; 312 Window client_win; 313 union { 314 XIMStatusDrawCallbackStruct draw; /* StatusDraw */ 315 } todo; 316} XIMPStatusCBStruct; 317 3182. IMValues 319 3202.1. IMModifiers 321 322 The IMModifiers argument, of type string, specifies the name of the 323IMProtocol model. At the current release, only three names are accepted 324by IMdkit. 325 "Xi18n" specifies the R6 standard IMProtocol model 326 "XIMP" specifies the R5 Ximp model. 327 328 The IMModifiers argument must be set only once when IMOpenIM is 329called, and never be changed on the fly. 330 3312.2. IMServerWindow 332 333 The IMServerWindow argument, of type Window, specifies the window 334which identifies a method of preconnection with XIM clients. In addition 335to this primary purpose, the IMServerWindow might be used for any other 336purposes, which depends on the IMProtocol model to be used. 337 If this argument is unspecified, a default window might be provided 338by IMdkit, which depends on the IMProtocol model to be used, and if it 339is specified, it must be done only once by either IMOpenIM or 340IMSetIMValues, and never be changed on the fly. 341 3422.3. IMServerName 343 344 The IMServerName argument, of type string, specifies the name of the 345IMserver. This argument might be a part of the IMserver identifiers 346by which XIM clients will search for the IMserver. 347 The IMServerName argument must be set only once when IMOpenIM is 348called, and never be changed on the fly. 349 3502.4. IMLocale 351 352 The IMLocale argument, of type string, specifies a list of locales 353the IMserver supports. This argument might be a part of the IMserver 354identifiers which is used for XIM clients to search for the IMserver. 355 The IMLocale argument must be set only once when IMOpenIM is called, 356and never be changed on the fly. 357 3582.5. IMServerTransport 359 360 The IMServerTransport argument, of type string, specifies the name 361for the transport connection mechanism the IMserver uses. This argument 362might be a part of the IMserver identifiers which is used for XIM 363clients to search for the IMserver. 364 The preregistered formats for this argument are as follows.(*1) 365 366(*1) Reter to "The Input Method Protocol", Appendix B: 367 The list of transport specific IM Server address format registered 368 369TCP/IP Names 370------------ 371 Syntax for Internet domain names: 372 373 <TCP name> ::= "tcp/"<hostname>":"<ipportnumber> 374 375 where <hostname> is either symbolic or numeric decimal form of 376 the host machine name, and <ipportnumber> is the port on which 377 the IMserver is listening for connections. 378 379 Syntax for system internal domain names: 380 381 <local name> ::= "locale/"<hostname>":"<pathname> 382 383 where <pathname> is a path name of socket address. 384 385DECnet Names 386------------ 387 Syntax for DECnet names: 388 389 <DECnet name> ::= "decnet/"<nodename>"::IMSERVER$"<objname> 390 391 where <nodename> is either symbolic or numeric decimal form of 392 the DECnet address, and <objname> is normal, case-insensitive 393 DECnet object name. 394 395X Names 396------- 397 Syntax for X names: 398 399 <X name> ::= "X/" 400 401 The IMServerTransport argument must be set only once when IMOpenIM is 402called, and never be changed on the fly. 403 4042.6. IMInputStyles 405 406 The IMInputStyles argument, of type XIMStyles, specifies a list of 407the input styles the IMserver supports. 408 If this argument is unspecified, a default list might be provided by 409IMdkit, which depends on the IMProtocol model to be used, and it can be 410set by either IMOpenIM or IMSetIMValues, but should not be changed on 411the fly. 412 4132.7. IMProtocolHandler 414 415 The IMProtocolHandler argument, of type IMProtoHandler, specifies the 416callback function which is called each time when IMMainLoop receives an 417IMProtocol input from XIM clients. The generic prototype of the 418IMProtocolHandler function is; 419 420typedef int (*IMProtoHandler)(); 421 422int ProtocolHandlerProc(ims, call_data) 423XIMS ims; 424XPointer call_data; 425 426call_data points to a IMProtocol structure. 427 4282.8. IMOnKeysList 429 430 The IMOnKeysList argument, of type XIMTriggerKeys, specifies the list 431of preediting start-keys for Dynamic Event Flow model. The IMOnKeysList 432IMValue is mandatary for IMserver to support Dynamic Event Flow Model, 433so that the IMlibrary can send the IMserver a request to start 434preediting with the apperance of one of these registered on-keys. 435 If the IMOnKeysList is left unspecified, no default will be provided, 436and Static Event Flow model will be used. 437 XIMTriggerKeys structure is defined by IMdkit as follows: 438 439typedef struct { 440 CARD32 keysym; 441 CARD32 modifier; 442 CARD32 modifier_mask; 443} XIMTriggerKey; 444 445typedef struct { 446 unsigned short count_keys; 447 XIMTriggerKey *keylist; 448} XIMTriggerKeys; 449 4502.9. IMOffKeysList 451 452 The IMOnKeysList argument, of type XIMTriggerKeys, specifies the list 453of preediing end-keys for Dynamic Event Flow model. The IMOffKeysList 454IMValue is optional for IMserver to support Dynamic Event Flow Model. 455 When it is specified, the IMlibrary can send the IMserver a request 456to stop preediting with the apperance of one of these registered 457off-keys, while it's unspecified, the IMserver calls IMPreeditEnd to 458notify the IMlibrary to stop preeditting when the IMserver would like to 459stop preeditring. 460 If the IMOffKeysList is left unspecified, no default will be 461provided. 462 4632.10. IMEncodingList 464 465 The IMEncodingList argument, of type XIMEncodings, specifies the list 466of encodings the IMserver supports. XIM client will be notified of this 467argument immediately after it makes a connection with the IMserver. 468 The IMEncdoingList argument is used to specify which encodings can be 469used to exchange localized-text between the IMserver and XIM clients. 470 If it's left unspecified, only "COMPOUND_TEXT" encoding will be used 471as a fallback default. 472 XIMEncodings structure is defined by IMdkit as follows: 473 474typedef char *XIMEncoding; 475 476typedef struct { 477 unsigned short count_encodings; 478 XIMEncoding *supported_encodings; 479} XIMEncodings; 480 4812.11. IMFilterEventMask 482 483 The IMFilterEventMask argument, of type long, specifies the events 484which should be filtered by the IMserver during the preeditting is on 485going. 486 If it's left unspecified, KeyPressMask (1L<<0) will be fallback 487default. 488 4892.12. IMProtocolDepend 490 491 The IMProtocolDepend argument is used to specify special IM values 492for each IMProtocol model, if any. This attribute is passed to 493IMOpenIM, IMSetIMValues or IMGetIMValues as a nested variable length 494list generated with XVaCreateNestedList(). At this release, the 495names in the IMProtocolDepend list are defined only for R5 Ximp model, 496as below. 497 4982.12.1. R5 Ximp dependent IM Values 499 500XIMPVersion 501 502 The XIMPVersion argument, of type string, specifies the version of R5 503Ximp model. 504 value meaning 505 --------------------------------------------- 506 "3.5" supports Ximp version 3.5 model 507 "4.0" supports Ximp version 4.0 model 508 509XIMPType 510 511 The XIMPVersion argument, pointer to a list of type unsigned long, 512specifies a list of bitmask combinations, each of which indicates the 513event flow model your IMserver supports. All possible values to be 514appeared in the list are defined as follows.(*) 515 516(*) Refer to "Protocol Specification for the Distributes Input System on 517the X Window System, Version 11", which contains in X11R5 contribuion. 518 519 XIMP_BE_TYPE1 520 back-end type, which IMlibrary recognizes registered keys and 521 notifies a server to start processing key events. 522 XIMP_FE_TYPE1 523 front-end type, which IMlibrary recognizes registered keys and 524 notifies a server to start processing key events. 525 XIMP_BE_TYPE2 526 back-end type, which IMlibrary does not recognize any registered 527 keys and. IMserver will always the first to process key events. 528 XIMP_FE_TYPE2 529 front-end type, which IMlibrary does not recognize any 530 registered keys and. IMserver will always the first to process 531 key events. 532 XIMP_FE_TYPE3 533 front-end type, which key events are always passed to both 534 IMserver and IMlibrary. Both of them recognize registered keys. 535 XIMP_SYNC_BE_TYPE1 536 XIMP_BE_TYPE1 & KeyPress is transfered synchronously. 537 XIMP_SYNC_BE_TYPE2 538 XIMP_BE_TYPE2 & KeyPress is transfered synchronously. 539 540XIMPExtension 541 542 The XIMPExtension argument is used to set/unset the pre-registered 543extensions to be valid. This list is also a nested variable length list 544generated with XVaCreateNestedList(). At this release, the 545pre-registered extensins appeared in the XIMPExtension list are defined 546as below. 547 548 XIMPExtStatusWin 549 If it is appeared in the list, the XNExtXimp_StatusWindow input 550 context attribute is valid to set the status window. The 551 attribute value isn't evaluated. 552 XIMPExtBackFront 553 If it is appeared in the list, the XNExtXimp_Backfront input 554 context is valid to select the front-end method or back-end 555 method. The attribute value isn't evaluated. 556 XIMPExtConversion 557 If it is appeared in the list, the XNExtXimp_Conversion input 558 context is valid to set the input mode. The attribute value 559 isn't evaluated. 560 5613. X IMProtocol Strucutures 562 563 For each X IMProtocol input, a corresponding structure is defined in 564public header files of IMdkit. <X11/Ximd/Xi18n.h> defines all IMProtocol 565structures for R6 standard IMProtocol model, and <X11/Ximd/Ximp.h> 566defines all for R5 Ximp model. 567 5683.1. R6 IMProtocol 569 5703.1.1. IMProtocol union data structure 571 In R6 standard IMProtocol model, all the event structures have the 572following common members: 573 574typedef struct { 575 int major_code; /* major code of last IMProtocol */ 576 int minor_code; /* minor code of last IMProtocol */ 577 CARD16 connect_id; /* client connection ID */ 578} IMAnyStruct; 579 580 The major_code and minor_code specify the IMProtocol type constant 581name that uniquely identifies itself. 582 In addition to the individual structures declared for each IMProtocol 583type, the IMProtocol structure is a union of the individual structures 584declared for each IMProtocol type. Depending on the type, you should 585access members of each IMProtocol by using the IMProtocol union. 586 587typedef union _IMProtocol { 588 int major_code; 589 IMAnyStruct any; 590 IMConnectStruct imconnect; 591 IMDisConnectStruct imdisconnect; 592 IMOpenStruct imopen; 593 IMCloseStruct imclose; 594 IMQueryExtensionStruct queryext; 595 IMGetIMValuesStruct getim; 596 IMEncodingNegotiationStruct encodingnego; 597 IMExtSetEventMaskStruct extsetevent; 598 IMExtForwardKeyEventStruct extforward; 599 IMExtMoveStruct extmove; 600 IMSetEventMaskStruct setevent; 601 IMChangeICStruct changeic; 602 IMDestroyICStruct destroyic; 603 IMResetICStruct resetic; 604 IMChangeFocusStruct changefocus; 605 IMCommitStruct commitstring; 606 IMForwardEventStruct forwardevent; 607 IMTriggerNotifyStruct triggernotify; 608 IMErrorStruct imerror; 609 IMGeometryCBStruct geometry_callback; 610 IMPreeditCBStruct preedit_callback; 611 IMStatusCBStruct status_callback; 612 long pad[32]; 613} IMProtocol; 614 615 The first two entries of any IMProtocol structure are always the 616major_code and minor_code members, which specifies the IMProtocol type. 617The third member is the connect_id member, just provided for IMdkit 618internal use to distinguish a client from each other. 619 6203.1.2. Protocol Processing 621 622 Some of IMProtocol requests sent by the IMlibrary are processed 623internally by IMdkit without passing them to your IMservers, because 624IMdkit can determin the answer to such IMProtocol requests only by 625using the IMValues which you have set in the XIMS structure. 626 At this release, the following four IMProtocol requests is processed 627in IMdkit itself, and wouldn't forward to your IMserver: 628 o XIM_CONNECT -> XIM_CONNECT_REPLY 629 o XIM_DISCONNECT -> XIM_DISCONNECT_REPLY 630 o XIM_QUERY_EXTENSION -> XIM_QUERY_EXTENSION_REPLY 631 o XIM_GET_IM_VALUES -> XIM_GET_IM_VALUES_REPLY 632 So, you don't have to know the details of the corresponding 633IMProtocol structures for these IMProtocol requests. 634 635 On the other hand, you will need to deal with the following requests 636for yourselves: 637 o XIM_OPEN 638 o XIM_CLOSE 639 o XIM_SET_IC_FOCUS and XIM_UNSET_IC_FOCUS 640 o XIM_DESTROY_IC 641 o XIM_RESET_IC 642 o XIM_CREATE_IC, XIM_SET_IC_VALUES and XIM_GET_IC_VALUES 643 o XIM_TRIGGER_NOTIFY 644 o XIM_FORWARD_EVENT 645 However, you don't have to receive any raw packets, but can receive 646the corresponding IMProtocol structures in your IMProtocolHandler 647callback function. Further, you don't have to send a reply for 648yourselves, but IMdkit will send a reply soon after your 649IMProtocolHandler returns. If your IMProtocolHandler returns True, 650IMdkit will send the proper reply to the previous request, and if it 651returns False, IMdkit will send XIM_ERROR reply to the XIM client. 652 The following IMProtocol structures are what you will actually 653receive instead of IMProtocol requests in your IMProtocolHandler 654function. 655 656IMOpenStruct 657------------ 658 The IMOpenStruct structure is used for XIM_OPEN and XIM_OPEN_REPLY 659requests. The structure contains: 660 661typedef struct { 662 int length; 663 char *name; 664} XIMStr; 665 666typedef struct { 667 int major_code; 668 int minor_code; 669 CARD16 connect_id; 670 XIMStr lang; 671} IMOpenStruct; 672 673 Your IMserver should check lang field to know which language service 674is required by the new client, which is identified with connect_id 675member. 676 677IMCloseStruct 678------------- 679 The IMCloseStruct structure is used for XIM_CLOSE and XIM_CLOSE_REPLY 680requests. The structure contains: 681 682typedef struct { 683 int major_code; 684 int minor_code; 685 CARD16 connect_id; 686} IMCloseStruct; 687 688 Your IMserver should check connect_id member to know which input 689method connection should be closed. 690 691IMChangeFocusStruct 692------------------- 693 The IMChangeFocusStruct structure is used for XIM_SET_IC_FOCUS and 694XIM_UNSET_IC_FOCUS requests. The structure contains: 695 696typedef struct { 697 int major_code; 698 int minor_code; 699 CARD16 connect_id; 700 CARD16 icid; /* input context ID to change focus */ 701} IMChangeFocusStruct; 702 703 Your IMserver should check icid member to know which input context 704should be focusd or unfocusd. 705 706IMDestroyICStruct 707----------------- 708 The IMDestroyICStruct structure is used for XIM_DESTROY_IC and 709request. The structure contains: 710 711typedef struct { 712 int major_code; 713 int minor_code; 714 CARD16 connect_id; 715 CARD16 icid; /* input context ID to destroy */ 716} IMDestroyICStruct; 717 718 Your IMserver should check icid member to know which input context 719should be destroyed. 720 721IMResetICStruct 722--------------- 723 The IMResetICStruct structure is used for XIM_RESET_IC request. The 724structure contains: 725 726typedef struct { 727 int major_code; 728 int minor_code; 729 CARD16 connect_id; 730 CARD16 icid; /* input context ID to reset */ 731 CARD16 length; /* length of committed string below */ 732 char *commit_string; /* string to commit to XIM client */ 733} IMResetICStruct; 734 735 Your IMserver should check icid member to know which input context 736should be reset. 737 738IMChangeICStruct 739---------------- 740 The IMChangeICStruct structure is used for XIM_CREATE_IC, 741XIM_SET_IC_VALUES and XIM_GET_IC_VALUES requests. The structures 742contain: 743 744/* 745 * value type for IC defined in XimProto.h 746 */ 747#define XimType_SeparatorOfNestedList 0 748#define XimType_CARD8 1 749#define XimType_CARD16 2 750#define XimType_CARD32 3 751#define XimType_STRING8 4 752#define XimType_Window 5 753#define XimType_XIMStyles 10 754#define XimType_XRectangle 11 755#define XimType_XPoint 12 756#define XimType_XFontSet 13 757#define XimType_XIMOptions 14 758#define XimType_XIMHotKeyTriggers 15 759#define XimType_XIMHotKeyState 16 760#define XimType_XIMStringConversion 17 761#define XimType_NEST 0x7fff 762 763typedef struct { 764 int attribute_id; /* ID for this IC */ 765 CARD16 name_length; /* length of IC name below */ 766 char *name; /* IC name */ 767 int value_length; /* length of IC value below */ 768 void *value; /* IC value */ 769 int type; /* value type for IC, see above */ 770} XICAttribute; 771 772typedef struct { 773 int major_code; 774 int minor_code; 775 CARD16 connect_id; 776 CARD16 icid; 777 /* input context ID: 778 for each CREATE, different ID is expected to be returned. 779 for each SET, it shows the ID to set. 780 for each GET, it shows the ID to get. 781 */ 782 CARD16 preedit_attr_num; /* number of preedit_attr list below */ 783 CARD16 status_attr_num; /* number of preedit_attr list below */ 784 CARD16 ic_attr_num; /* number of ic_attr list below */ 785 XICAttribute *preedit_attr; /* IC values for preedit attribute */ 786 XICAttribute *status_attr; /* IC values for status attribute */ 787 XICAttribute *ic_attr; /* IC values for other attributes */ 788} IMChangeICStruct; 789 790 When XIM_SET_IC_VALUES or XIM_GET_IC_VALUES, your IMserver should 791check icid member to know which input context should be specified. When 792XIM_CREATE_IC, your IMserver should set icid member to identify the 793input context newly created. 794 795IMTriggerNotifyStruct 796--------------------- 797 The IMTriggerNotifyStruct structure is used for XIM_TRIGGER_NOTIFY 798request. The structure contains: 799 800typedef struct { 801 int major_code; 802 int minor_code; 803 CARD16 connect_id; 804 CARD16 icid; 805 CARD32 flag; 806 CARD32 key_index; 807 CARD32 event_mask; 808} IMTriggerNotifyStruct; 809 810IMForwardEventStruct 811-------------------- 812 The IMForwardEventStruct structure is used for XIM_FORWARD_EVENT 813request. The structure contains: 814 815typedef struct { 816 int major_code; 817 int minor_code; 818 CARD16 connect_id; 819 CARD16 icid; /* input context ID */ 820 BITMASK16 sync_bit; /* precessed synchronously or not */ 821 CARD16 serial_number; 822 XEvent event; /* X event to be filtered */ 823} IMForwardEventStruct; 824 8253.2. R5 Ximp IMProtocol 826 8273.2.1. XIMProtocol union data structure 828 829 In R5 Ximp IMProtocol model, all the event structures have the 830following common members: 831 832typedef struct { 833 INT32 type; /* message type */ 834 CARD32 icid; /* input context ID */ 835 Window focus_win; /* focus window */ 836 long fwin_sel_mask; /* focus window select-mask */ 837 CARD32 ximp_type_mask; /* Ximp event flow type */ 838 Window client_win; /* client window */ 839} XIMPAnyStruct; 840 841 The type member specifies the Ximp IMProtocol type constant name that 842uniquely identies itself. 843 In addition to the individual structures declared for each Ximp 844XIMProtocol type, the Ximp IMProtocol structure is a union of the 845individual structures declared for each Ximp IMProtocol type. Depending 846on the type, you should access members of each Ximp IMProtocol by using 847the XIMProtocol union. 848 849typedef union _IMPProtocol { 850 int type; 851 XIMPAnyStruct any; 852 XIMPKeyEventStruct keyevent; 853 XIMPICValuesStruct create; 854 XIMPICValuesStruct setvalue; 855 XIMPICValuesStruct getvalue; 856 XIMPAnyStruct destroy; 857 XIMPAnyStruct regkey; 858 XIMPAnyStruct setfocus; 859 XIMPAnyStruct unsetfocus; 860 XIMPClientWindowStruct clientwin; 861 XIMPFocusWindowStruct focuswin; 862 XIMPMoveStruct move; 863 XIMPEventMaskNotifyStruct evmasknotify; 864 XIMPExtensionStruct extension; 865 XIMPReadPropStruct readprop; 866 XIMPResetStruct reset; 867 XIMPCommitStringStruct commitstring; 868 XIMPErrorStruct error; 869 XIMPAnyStruct geometry_cb; 870 XIMPPreeditCBStruct preedit_cb; 871 XIMPStatusCBStruct status_cb; 872 long pad[24]; 873} IMPProtocol; 874 875 The first entry of any XIMProtocol structure is always the 876type member, which specifies the Ximp IMProtocol type. 877 8784. Writing IMservers 879 880When writing an IMserver that uses the IMdkit, you should make sure that 881your IMserver performs the following: 882 883 1. Include <X11/Xlib.h> in your IMserver programs. 884 885 2. Include <X11/Ximd/IMdkit.h>. This header file defines all the 886 necessary data types and IMdkit functions that you need to use. 887 888 3. Include <X11/Ximd/Xi18n.h> for R6 standard IMProtocol, or 889 <X11/Ximd/Ximp.h> for R5 Ximp IMProtocol, respectively. 890 891 4. Call the IMOpenIM function with all the necessary IMValues to 892 initialize the connection. The names of each IMValues have a global 893 symbol that begins with IM to help catch spelling errors. For 894 example, IMModifiers is defined for the XIMProtocol model, and 895 IMLocale is defined for the locale resource. For further information, 896 see "Section 1.1 Open IM Service" and Section 2 "IMValues" 897 898 5. To set additional IMValues or override the existing IMValues you 899 set by IMOpenIM, use IMSetIMValues. You can also use IMGetIMValues to 900 look up at existing IMValues. Note that some of IMValues must be set 901 at the IM service creation time, and never be changed by 902 IMSetIMValues. 903 904 6. You must set the IMProtocol callback routine by the 905 IMProtocolHandler argument with IMOpenIM or IMSetIMValues functions. 906 This callback is called whenever the IMProtocol is delivered by XIM 907 clients. 908 909 7. Now you should select all the necessary X events for your windows 910 with XSelectInput function, and map the windows with XMapWindow 911 function, then sit in a loop processing events as follows. 912 913 for (;;) { 914 XEvent event; 915 XNextEvent(your_display, &event); 916 if (XFilterEvent(&event, NULL) == True) 917 continue; 918 YourXEventHandler(&event); 919 } 920 921 Here, all the IMProtocols you need are passed to your IMProtocol 922 callback routine by X Filtering mechanism of XFilterEvent function, 923 and all unfiltered X events you want are passed to YourXEventHandler 924 function above. 925 926 8. Link your IMserver with libXimd (the IMdkit library) and libX11 927 (the core X library). The following provides a sample command line: 928 929 cc -o sampleIM sampleIM.c -lXimd -lX11 930