specs/XIM/xim.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   4 [
   5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
   6 ]>
   7
   8
   9 <!-- lifted from troff+ms+XMan by doclifter -->
  10 <article class="specification" id="xim">
  11
  12 <articleinfo>
  13    <title>The Input Method Protocol</title>
  14    <subtitle>X Consortium Standard</subtitle>
  15    <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  16    <releaseinfo>Version 1.0</releaseinfo>
  17    <authorgroup>
  18       <author>
  19          <firstname>Masahiko</firstname><surname>Narita</surname>
  20          <affiliation><orgname>FUJITSU Limited.</orgname></affiliation>
  21       </author>
  22       <author>
  23          <firstname>Hideki</firstname><surname>Hiura</surname>
  24          <affiliation><orgname>SunSoft, Inc.</orgname></affiliation>
  25       </author>
  26    </authorgroup>
  27    <copyright><year>1993</year><year>1994</year>
  28       <holder>FUJITSU LIMITED</holder>
  29       <holder>Oracle and/or its affiliates</holder>
  30    </copyright>
  31
  32 <abstract>
  33 <para>
  34 This specifies a protocol between IM library and IM (Input Method) Server for internationalized text input, which is indepedent from any specific language, any specific input method and the transport layer used in communication between the IM library and the IM Server, and uses a client-server model.  This protocol allows user to use his/her favorite method for all applications within the stand-along distrubuted environment.
  35 </para>
  36 </abstract>
  37
  38 <legalnotice>
  39 <para>Permission to use,copy and distribute this documetation for any purpose
  40 and without fee is hereby granted, provided that the above copyright notice
  41 and this permission notice appear in all copies.  Fujitsu and Sun Microsystems
  42 make no representation about the suitability for any purpose of the information in this document.
  43 This documentation is provided as is without express implied warranty.
  44 </para>
  45 </legalnotice>
  46
  47 <legalnotice>
  48 <para role="multiLicensing">Copyright © 1993, 1994 X Consortium</para>
  49 <para>Permission is hereby granted, free of charge, to any person obtaining a copy of
  50 this software and associated documentation files (the "Software"), to deal in
  51 the Software without restriction, including without limitation the rights to
  52 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
  53 of the Software, and to permit persons to whom the Software is furnished to do
  54 so, subject to the following conditions:
  55 </para>
  56 <para>The above copyright notice and this permission notice shall be included in all
  57 copies or substantial portions of the Software.</para>
  58 <para>THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  59 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  60 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
  61 CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  62 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  63 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  64 </para>
  65 <para>
  66 Except as contained in this notice, the name of the X Consortium shall not be
  67 used in advertising or otherwise to promote the sale, use or other dealings in
  68 this Software without prior written authorization from the X Consortium.
  69 </para>
  70 <para>X Window System is a trademark of The Open Group.</para>
  71 </legalnotice>
  72
  73 </articleinfo>
  74
  75 <sect1 id="Introduction">
  76 <title>Introduction</title>
  77 <sect2 id="Scope">
  78 <title>Scope</title>
  79 <!-- .XS -->
  80 <!-- (SN Scope -->
  81 <!-- .XE -->
  82 <para>
  83 <!-- .LP -->
  84 The internationalization in the
  85 X Window System
  86 Version 11, Release 5 (X11R5) provides a common API which application
  87 developers can use to create portable internationalized programs and to
  88 adapt them to the requirements of different native languages, local customs,
  89 and character string encodings (this is called "localization").
  90 As one of its internationalization mechanisms X11R5 has defined a functional
  91 interface for internationalized text input, called XIM (X Input Method).
  92 </para>
  93 <para>
  94 <!-- .LP -->
  95 When a client-server model is used with an IM (Input Method) implementation,
  96 a protocol must be established between the client and the server.
  97 However, the protocol used to interface Input Method Servers (IM Servers)
  98 with the Input Method libraries (IM libraries) to which applications are
  99 linked was not addressed in X11R5.
 100 This led application developers to depend on vendor-specific input methods,
 101 decreased the user's choice of available input methods, and made it more
 102 difficult for developers to create portable applications. This paper describes
 103 the Input Method Protocol developed for X11R6 to resolve the above problems
 104 and to address the requirements of existing and future input methods.
 105 </para>
 106 <para>
 107 <!-- .LP -->
 108 The Input Method Protocol is independent from the transport layer used in
 109 communication between the IM library and the IM Server.
 110 Thus, the input method protocol can be built on any inter-process
 111 communication mechanism, such as TCP/IP or the X protocol.
 112 </para>
 113 <para>
 114 In addition, the protocol provides for future extensions such as differing
 115 input model types.
 116 </para>
 117 </sect2>
 118
 119 <sect2 id="Background">
 120 <title>Background</title>
 121 <!-- .XS -->
 122 <!-- (SN Background -->
 123 <!-- .XE -->
 124 <para>
 125 <!-- .LP -->
 126 Text input is much more simple for some languages than
 127 others.  English, for instance, uses an alphabet of a manageable size,
 128 and input consists of pressing the corresponding key on a keyboard,
 129 perhaps in combination with a shift key for capital letters or special
 130 characters.
 131 </para>
 132 <para>
 133 <!-- .LP -->
 134 Some languages have larger alphabets, or modifiers such as accents,
 135 which require the addition of special key combinations in order to enter
 136 text.  These input methods may require "dead-keys" or "compose-keys"
 137 which, when followed by different combinations of key strokes,
 138 generate different characters.
 139 </para>
 140 <para>
 141 <!-- .LP -->
 142 Text input for ideographic languages is much less simple.  In these
 143 languages, characters represent actual objects rather than phonetic
 144 sounds used in pronouncing a word, and the number of characters
 145 in these languages may continue to grow.  In Japanese, for instance, most
 146 text input methods involve entering characters in a phonetic alphabet,
 147 after which the input method searches a dictionary for possible
 148 ideographic equivalents (of which there may be many).  The input method then
 149 presents the candidate characters for the user to choose from.
 150 </para>
 151 <para>
 152 <!-- .LP -->
 153 In Japanese, either Kana (phonetic symbols) or Roman letters are
 154 typed and then a region is selected for conversion to Kanji. Several
 155 Kanji characters may have the same phonetic representation. If that
 156 is the case with the string entered, a menu of characters is presented
 157 and the user must choose the appropriate one. If no choice is necessary
 158 or a preference has been established, the input method does the
 159 substitution directly.
 160 </para>
 161 <para>
 162 <!-- .LP -->
 163 These complicated input methods must present state information (Status Area),
 164 text entry and edit space (Preedit Area), and menu/choice presentations
 165 (Auxiliary Area).  Much of the protocol between the IM library and the IM
 166 Server involves managing these IM areas.
 167 Because of the size and complexity of these input methods, and because
 168 of how widely they vary from one language or locale to another, they are
 169 usually implemented as separate processes which can serve many client
 170 processes on the same computer or network.
 171 </para>
 172 <para>
 173 <!-- .LP -->
 174 </para>
 175 </sect2>
 176 <sect2 id="Input_Method_Styles">
 177 <title>Input Method Styles</title>
 178 <!-- .XS -->
 179 <!-- (SN Input Method Styles -->
 180 <!-- .XE -->
 181 <para>
 182 <!-- .LP -->
 183 X11 internationalization support includes the following four types of
 184 input method:
 185 <!-- .RS -->
 186 </para>
 187
 188 <variablelist>
 189   <varlistentry>
 190     <term>- on-the-spot:</term>
 191     <listitem>
 192       <para>
 193 The client application is directed by the IM Server to display all
 194 pre-edit data at the site of text insertion.  The client registers
 195 callbacks invoked by the input method during pre-editing.
 196       </para>
 197     </listitem>
 198   </varlistentry>
 199   <varlistentry>
 200     <term>- off-the-spot:</term>
 201     <listitem>
 202       <para>
 203 The client application provides display windows for the pre-edit data
 204 to the input method which displays into them directly.
 205       </para>
 206     </listitem>
 207   </varlistentry>
 208   <varlistentry>
 209     <term>- over-the-spot:</term>
 210     <listitem>
 211       <para>
 212 The input method displays pre-edit data in a window which it brings up
 213 directly over the text insertion position.
 214       </para>
 215     </listitem>
 216   </varlistentry>
 217   <varlistentry>
 218     <term>- root-window:</term>
 219     <listitem>
 220       <para>
 221 The input method displays all pre-edit data in a separate area of the
 222 screen in a window specific to the input method.
 223       </para>
 224     </listitem>
 225   </varlistentry>
 226 </variablelist>
 227
 228 <para>
 229 Client applications must choose from the available input methods
 230 supported by the IM Server and provide the display areas and callbacks
 231 required by the input method.
 232 </para>
 233 </sect2>
 234
 235 </sect1>
 236 <sect1 id="Architecture">
 237 <title>Architecture</title>
 238 <!-- .XS -->
 239 <!-- (SN Architecture -->
 240 <!-- .XE -->
 241 <sect2 id="Implementation_Model">
 242 <title>Implementation Model</title>
 243 <!-- .XS -->
 244 <!-- (SN Implementation Model -->
 245 <!-- .XE -->
 246 <para>
 247 <!-- .LP -->
 248 Within the X Window System environment, the following two typical
 249 architectural models can be used as an input method's implementation
 250 model.
 251 </para>
 252
 253 <variablelist>
 254   <varlistentry>
 255     <term>- Client/Server model:</term>
 256     <listitem>
 257       <para>
 258 A separate process, the IM Server, processes input and handles preediting,
 259 converting, and committing.  The IM library within the application, acting
 260 as client to the IM Server, simply receives the committed string from the
 261 IM Server.
 262       </para>
 263     </listitem>
 264   </varlistentry>
 265   <varlistentry>
 266     <term>- Library model:</term>
 267     <listitem>
 268       <para>
 269 All input is handled by the IM library within the application.  The
 270 event process is closed within the IM library and a separate IM Server
 271 process may not be required.
 272       </para>
 273     </listitem>
 274   </varlistentry>
 275 </variablelist>
 276
 277 <para>
 278 <!-- .LP -->
 279 Most languages which need complex preediting, such as Asian languages,
 280 are implemented using the Client/Server IM model.  Other languages
 281 which need only dead key or compose key processing, such as European
 282 languages, are implemented using the Library model.
 283 </para>
 284 <para>
 285 <!-- .LP -->
 286 In this paper, we discuss mainly the Client/Server IM model and the
 287 protocol used in communication between the IM library (client) and the IM
 288 Server.
 289 </para>
 290 </sect2>
 291
 292 <sect2 id="Structure_of_IM">
 293 <title>Structure of IM</title>
 294 <!-- .XS -->
 295 <!-- (SN Structure of IM -->
 296 <!-- .XE -->
 297 <para>
 298 <!-- .LP -->
 299 When the client connects or disconnects to the IM Server, an open or close
 300 operation occurs between the client and the IM Server.
 301 </para>
 302 <para>
 303 <!-- .LP -->
 304 The IM can be specified at the time of XOpenIM() by setting the locale
 305 of the client and a locale modifier. Since the IM remembers
 306 the locale at the time of creation XOpenIM() can be called
 307 multiple times (with the
 308 setting for the locale and the locale modifier changed) to support
 309 multiple languages.
 310 </para>
 311 <para>
 312 <!-- .LP -->
 313 In addition, the supported IM type can be obtained using XGetIMValues().
 314 </para>
 315 <para>
 316 <!-- .LP -->
 317 The client usually holds multiple input (text) fields. Xlib provides a
 318 value type called the "Input Context" (IC) to manage each individual
 319 input field.  An IC can be created by specifying XIM using XCreateIC(),
 320 and it can be destroyed using XDestroyIC().
 321 </para>
 322 <para>
 323 <!-- .LP -->
 324 The IC can specify the type of IM which is supported by XIM for each
 325 input field, so each input field can handle a different type of IM.
 326 </para>
 327 <para>
 328 <!-- .LP -->
 329 Most importantly information such as the committed string sent from
 330 the IM Server to the client, is exchanged based on each IC.
 331 </para>
 332 <para>
 333 <!-- .LP -->
 334 Since each IC corresponds to an input field, the focused input field
 335 should be announced to the IM Server using XSetICFocus(). (XUnsetICFocus()
 336 can also be used to change the focus.)
 337 </para>
 338 <para>
 339 <!-- .LP -->
 340 </para>
 341 </sect2>
 342 <sect2 id="Event_Handling_Model">
 343 <title>Event Handling Model</title>
 344 <!-- .XS -->
 345 <!-- (SN Event Handling Model -->
 346 <!-- .XE -->
 347 <para>
 348 <!-- .LP -->
 349 Existing input methods support either the FrontEnd method, the BackEnd method,
 350 or both.  This protocol specifically supports the BackEnd method as
 351 the default method, but also supports the FrontEnd method as an optional
 352 IM Server extension.
 353 </para>
 354 <para>
 355 <!-- .LP -->
 356 The difference between the FrontEnd and BackEnd methods is in how
 357 events are delivered to the IM Server.  (Fig. 1) <!-- xref -->
 358 </para>
 359
 360 <sect3 id="BackEnd_Method">
 361 <title>BackEnd Method</title>
 362 <!-- .XS -->
 363 <!-- (SN BackEnd Method -->
 364 <!-- .XE -->
 365 <para>
 366 <!-- .LP -->
 367 In the BackEnd method, client window input events are always delivered
 368 to the IM library, which then passes them to the IM Server.  Events are
 369 handled serially in the order delivered, and therefore there is no
 370 synchronization problem between the IM library and the IM Server.
 371 </para>
 372 <para>
 373 <!-- .LP -->
 374 Using this method, the IM library forwards all KeyPress and KeyRelease
 375 events to the IM Server (as required by the Event Flow Control model
 376 described in
 377 <xref linkend='Event_Flow_Control' xrefstyle='select: title'/>)
 378 and synchronizes with the IM Server (as described in
 379 <xref linkend='Filtering_Events' xrefstyle='select: title'/>).
 380
 381 </para>
 382 </sect3>
 383
 384 <sect3 id="FrontEnd_Method">
 385 <title>FrontEnd Method</title>
 386 <!-- .XS -->
 387 <!-- (SN FrontEnd Method -->
 388 <!-- .XE -->
 389 <para>
 390 <!-- .LP -->
 391 In the FrontEnd method, client window input events are delivered by the
 392 X server directly to both the IM Server and the IM library.  Therefore this
 393 method provides much better interactive performance while preediting
 394 (particularly in cases such as when the IM Server is running locally on
 395 the user's workstation and the client application is running on another
 396 workstation over a relatively slow network).
 397 </para>
 398 <para>
 399 <!-- .LP -->
 400 However, the FrontEnd model may have synchronization problems between
 401 the key events handled in the IM Server and other events handled in the
 402 client, and these problems could possibly cause the loss or duplication
 403 of key events.  For this reason, the BackEnd method is the core method
 404 supported, and the FrontEnd method is made available as an extension for
 405 performance purposes. (Refer to
 406 <xref linkend="common_extensions" xrefstyle='select: title'/>
 407 for more information.)
 408 </para>
 409
 410 <mediaobject  id="flow_of_events">
 411   <imageobject>
 412     <imagedata  format="SVG"  fileref="eventflow.svg"/>
 413   </imageobject>
 414   <caption>The flow of events</caption>
 415 </mediaobject>
 416
 417 <!--
 418 <para>
 419 Fig.1 The Flow of Events
 420 </para>
 421 -->
 422
 423 </sect3>
 424 </sect2>
 425
 426 <sect2 id='Event_Flow_Control'>
 427 <title>Event Flow Control</title>
 428 <!-- .XS -->
 429 <!-- (SN Event Flow Control -->
 430 <!-- .XE -->
 431 <para>
 432 <!-- .LP -->
 433 This protocol supports two event flow models for communication between the
 434 IM library and the IM Server (Static and Dynamic).
 435 </para>
 436 <para>
 437 <!-- .LP -->
 438 Static Event Flow requires that input events always be sent to the IM
 439 Server from the client.
 440 </para>
 441 <para>
 442 <!-- .LP -->
 443 Dynamic Event Flow, however, requires only that those input events which
 444 need to be processed (converted) be sent to the IM Server from the client.
 445 </para>
 446 <para>
 447 <!-- .LP -->
 448 For instance, in the case of inputing a combination of ASCII characters
 449 and Chinese characters, ASCII characters do not need to be processed in
 450 the IM Server, so their key events do not have to be sent to the IM
 451 Server.  On the other hand, key events necessary for composing Chinese
 452 characters must be sent to the IM Server.
 453 </para>
 454 <para>
 455 <!-- .LP -->
 456 Thus, by adopting the Dynamic Event Flow, the number of requests among the
 457 X Server, the client, and the IM Server is significantly reduced, and the
 458 number of context switches is also reduced, resulting in improved performance.
 459 The IM Server can send
 460 <function>XIM_REGISTER_TRIGGERKEYS </function>
 461 message in order to switch the event flow in the Dynamic Event Flow.
 462 </para>
 463 <para>
 464 <!-- .LP -->
 465 The protocol for this process is described in
 466 <xref linkend='Event_Flow_Control_2' xrefstyle='select: title'/>.
 467 </para>
 468 </sect2>
 469 </sect1>
 470
 471 <sect1 id="Default_Preconnection_Convention">
 472 <title>Default Preconnection Convention</title>
 473 <!-- .XS -->
 474 <!-- (SN Default Preconnection Convention  -->
 475 <!-- .XE -->
 476 <para>
 477 <!-- .LP -->
 478 IM Servers are strongly encouraged to register their symbolic
 479 names as the ATOM names into the IM Server directory property,
 480 <function>XIM_SERVERS,</function>
 481 on the root window of the screen_number 0.
 482 This property can contain a list of ATOMs, and the each ATOM represents
 483 each possible IM Server.
 484 IM Server names are restricted to POSIX Portable Filename Character Set.
 485 To discover if the IM Server is active, see if there is an owner for
 486 the selection with that atom name.  To learn the address of that IM Server,
 487 convert the selection target
 488 <function>TRANSPORT,</function>
 489 which will return a string form of the transport address(es).
 490 To learn the supported locales of that IM Server, convert the selection target
 491 <function>LOCALES,</function>
 492 which will return a set of names of the supported locales in the syntax
 493 X/Open defines.
 494 </para>
 495 <para>
 496 <!-- .LP -->
 497 The basic semantics to determine the IM Server if there are
 498 multiple ATOMs are found in
 499 <function>XIM_SERVERS</function>
 500 property, is first fit if the IM Server name is not given as
 501 a X modifier's category
 502 <function>im.</function>
 503 </para>
 504 <para>
 505 <!-- .LP -->
 506 The address information retrievable from the
 507 <function>TRANSPORT</function>
 508 target is a transport-specific name.
 509 The preregistered formats for transport-specific names are listed in
 510 <xref linkend="transport_list" xrefstyle='select: title'/>.
 511 Additional transport-specific names may be registered with X Consortium.
 512 </para>
 513
 514 <para>
 515 For environments that lack X connections, or for IM Servers which
 516 do not use the X Window System, the preconnection convention with IM Server
 517 may be given outside the X Window system (e.g. using a Name Service).
 518 </para>
 519 </sect1>
 520
 521 <sect1 id="Protocol">
 522 <title>Protocol</title>
 523 <!-- .XS -->
 524 <!-- (SN Protocol -->
 525 <!-- .XE -->
 526 <para>
 527 <!-- .LP -->
 528 The protocol described below uses the bi-directional
 529 synchronous/asynchronous request/reply/error model and is specified
 530 using the same conventions outlined in Section 2 of the core X Window
 531 System protocol [1]:
 532 </para>
 533
 534 <sect2 id="Basic_Requests_Packet_Format">
 535 <title>Basic Requests Packet Format</title>
 536 <!-- .XS -->
 537 <!-- (SN Basic Requests Packet Format -->
 538 <!-- .XE -->
 539 <para>
 540 <!-- .LP -->
 541 This section describes the requests that may be exchanged between the client
 542 and the IM Server.
 543 </para>
 544 <para>
 545 <!-- .LP -->
 546 The basic request packet header format is as follows.
 547 </para>
 548 <literallayout class="monospaced">
 549           major-opcode:               CARD8
 550           minor-opcode:               CARD8
 551           length:                     CARD16
 552 </literallayout>
 553
 554 <para>
 555 The MAJOR-OPCODE specifies which core request or extension package this
 556 packet represents.  If the MAJOR-OPCODE corresponds to a core request,
 557 the MINOR-OPCODE contains 8 bits of request-specific data.
 558 (If the MINOR-OPCODE is not used, it is 0.)
 559 Otherwise, the MAJOR-OPCODE and the MINOR-OPCODE are specified by
 560 <function>XIM_QUERY_EXTENSION</function>
 561 message.  (Refer to 4.7. Query the supported extension protocol list.)
 562 The LENGTH field specifies the number of 4 bytes elements following the
 563 header.  If no additional data is followed by the header, the LENGTH field
 564 will be 0.
 565 </para>
 566 </sect2>
 567
 568 <sect2 id="Data_Types">
 569 <title>Data Types</title>
 570 <!-- .XS -->
 571 <!-- (SN Data Types -->
 572 <!-- .XE -->
 573 <para>
 574 The following data types are used in the core X IM Server protocol:
 575 </para>
 576
 577 <literallayout class="monospaced">
 578 BITMASK16
 579      CARD16
 580 BITMASK32
 581      CARD32
 582 PADDING FORMAT
 583      Where N is some expression, and Pad(N) is the number of bytes needed to round N up to a
 584
 585           Pad(N) = (4 - (N mod 4)) mod 4
 586
 587 LPCE
 588   1          A character from the4 X Portable Character Set in Latin Portable
 589              Character Encoding
 590
 591 STRING
 592      2     n              length of string in bytes
 593      n     LISTofLPCE     string
 594      p                    unused, p=Pad(2+n)
 595
 596 STR
 597      1     n              length of name in bytes
 598      n     STRING8        name
 599
 600 XIMATTR
 601      2     CARD16         attribute ID (*1)
 602      2     CARD16         type of the value (*2)
 603      2     n              length of im-attribute
 604      n     STRING8        im-attribute
 605      p                    unused, p = Pad(2+n)
 606
 607 The im-attribute argument specifies XIM values such as XNQueryInputStyle.
 608
 609 XICATTR
 610      2     CARD16         attribute ID (*1)
 611      2     CARD16         type of the value (*2)
 612      2     n              length of ic-attribute
 613      n     STRING8        ic-attribute
 614      p                    unused, p = Pad(2+n)
 615
 616 (*1) XIMATTR and XICATTR are used during the setup stage and XIMATTRIBUTE and
 617      XICATTRIBUTE are used after each attribute ID has been recognized by
 618      the IM Server and the IM library.
 619
 620 (*2) The value types are defined as follows:
 621 </literallayout>
 622 <informaltable id="valuetypes" frame="topbot">
 623   <?dbfo keep-together="auto" ?>
 624   <tgroup cols="5" align='left' colsep='0' rowsep='0'>
 625   <colspec colname="col1" colwidth="0.9*"/>
 626   <colspec colname="col2" colwidth="3.0*"/>
 627   <colspec colname="col3" colwidth="3.2*"/>
 628   <colspec colname="col4" colwidth="2.9*"/>
 629   <colspec colname="col5" colwidth="2.9*"/>
 630   <spanspec namest="col3" nameend="col5" spanname="span-horiz" align="center"/>
 631   <thead>
 632     <row rowsep='1'>
 633       <entry>values</entry>
 634       <entry>data</entry>
 635       <entry>format</entry>
 636       <!-- <entry spanname="span-horiz">format</entry> -->
 637     </row>
 638   </thead>
 639   <tbody>
 640     <row>
 641       <entry>#0</entry>
 642       <entry>Separator of NestedList</entry>
 643       <entry>-----(*3)</entry>
 644     </row>
 645     <row>
 646       <entry>#1</entry>
 647       <entry>byte data</entry>
 648       <entry>CARD8</entry>
 649     </row>
 650     <row>
 651       <entry>#2</entry>
 652       <entry>word data</entry>
 653       <entry>CARD16</entry>
 654     </row>
 655     <row>
 656       <entry>#3</entry>
 657       <entry>long data</entry>
 658       <entry>CARD32</entry>
 659     </row>
 660     <row>
 661       <entry>#4</entry>
 662       <entry>char data</entry>
 663       <entry>STRING8</entry>
 664     </row>
 665     <row>
 666       <entry>#5</entry>
 667       <entry>Window</entry>
 668       <entry>CARD32</entry>
 669     </row>
 670     <row>
 671       <entry>#10</entry>
 672       <entry>XIMStyles</entry>
 673       <entry>2</entry>
 674       <entry>n</entry>
 675       <entry>number of XIMStyle list</entry>
 676     </row>
 677     <row>
 678       <entry></entry>
 679       <entry></entry>
 680       <entry>2</entry>
 681       <entry></entry>
 682       <entry>unused</entry>
 683     </row>
 684     <row>
 685       <entry></entry>
 686       <entry></entry>
 687       <entry>n</entry>
 688       <entry>CARD32</entry>
 689       <entry>XIMStyle list</entry>
 690     </row>
 691     <row>
 692       <entry>#11</entry>
 693       <entry>XRectangle</entry>
 694       <entry>2</entry>
 695       <entry>INT16</entry>
 696       <entry>X</entry>
 697     </row>
 698     <row>
 699       <entry></entry>
 700       <entry></entry>
 701       <entry>2</entry>
 702       <entry>INT16</entry>
 703       <entry>Y</entry>
 704     </row>
 705     <row>
 706       <entry></entry>
 707       <entry></entry>
 708       <entry>2</entry>
 709       <entry>CARD16</entry>
 710       <entry>width</entry>
 711     </row>
 712     <row>
 713       <entry></entry>
 714       <entry></entry>
 715       <entry>2</entry>
 716       <entry>CARD16</entry>
 717       <entry>height</entry>
 718     </row>
 719     <row>
 720       <entry>#12</entry>
 721       <entry>XPoint</entry>
 722       <entry>2</entry>
 723       <entry>INT16</entry>
 724       <entry>X</entry>
 725     </row>
 726     <row>
 727       <entry></entry>
 728       <entry></entry>
 729       <entry>2</entry>
 730       <entry>INT16</entry>
 731       <entry>Y</entry>
 732     </row>
 733     <row>
 734       <entry>#13</entry>
 735       <entry>XFontSet</entry>
 736       <entry>2</entry>
 737       <entry>n</entry>
 738       <entry>length of Base font name</entry>
 739     </row>
 740     <row>
 741       <entry></entry>
 742       <entry></entry>
 743       <entry>n</entry>
 744       <entry>STRING8</entry>
 745       <entry>Base font name list</entry>
 746     </row>
 747     <row>
 748       <entry></entry>
 749       <entry></entry>
 750       <entry>p</entry>
 751       <entry></entry>
 752       <entry>unused, p = Pad(2+n)</entry>
 753     </row>
 754     <row>
 755       <entry>#15</entry>
 756       <entry>XIMHotKeyTriggers</entry>
 757       <entry>4</entry>
 758       <entry>n</entry>
 759       <entry>number of XIMTRIGGERKEY list (*4)</entry>
 760     </row>
 761     <row>
 762       <entry></entry>
 763       <entry></entry>
 764       <entry>n</entry>
 765       <entry>XIMTRIGGERKEY</entry>
 766       <entry>XIMHotkeyTrigger list</entry>
 767     </row>
 768     <row>
 769       <entry></entry>
 770       <entry></entry>
 771       <entry>n</entry>
 772       <entry>XIMHOTKEYSTATE</entry>
 773       <entry>HotKey processing state</entry>
 774     </row>
 775     <row>
 776       <entry>#17</entry>
 777       <entry>XIMStringConversion</entry>
 778       <entry>XIMSTRCONVTEXT</entry>
 779       <entry></entry>
 780       <entry></entry>
 781     </row>
 782     <row>
 783       <entry>#18</entry>
 784       <entry>XIMPreeditState</entry>
 785       <entry>XIMPREEDITSTATE</entry>
 786     </row>
 787     <row>
 788       <entry>#19</entry>
 789       <entry>XIMResetState</entry>
 790       <entry>XIMRESETSTATE</entry>
 791     </row>
 792     <row>
 793       <entry>#x7fff</entry>
 794       <entry>NestedList</entry>
 795       <entry>-----</entry>
 796     </row>
 797   </tbody>
 798   </tgroup>
 799 </informaltable>
 800
 801 <literallayout class="monospaced">
 802 (*3)  The IC value for the separator of NestedList is defined as follows,
 803             #define   XNSeparatorofNestedList   "separatorofNestedList"
 804       , which is registered in X Consortium and cannot be used for any other purpose.
 805
 806 (*4) LISTofFOO
 807             A Type name of the form LISTof FOO means a counted list of elements of type FOO.
 808             The size of the length field may vary (it is not necessarily the same
 809             size as a FOO), and in some cases, it may be implicit.
 810 XIMTRIGGERKEY
 811      4     CARD32       keysym
 812      4     CARD32       modifier
 813      4     CARD32       modifier mask
 814
 815 ENCODINGINFO
 816      2     n            length of encoding info
 817      n     STRING8      encoding info
 818      p                  unused, p=Pad(2+n)
 819
 820
 821      1     CARD8        extension major-opcode
 822      1     CARD8        extension minor-opcode
 823      2     n            length of extension name
 824      n     STRING8      extension name
 825      p                  unused, p = Pad(n)
 826
 827 XIMATTRIBUTE
 828      2     CARD16       attribute ID
 829      2     n            value length
 830      n                  value
 831      p                  unused, p = Pad(n)
 832
 833 XICATTRIBUTE
 834      2     CARD16       attribute ID
 835      2     n            value length
 836      n                  value
 837      p                  unused, p = Pad(n)
 838
 839
 840
 841 XIMSTRCONVTEXT
 842      2    CARD16                      XIMStringConversionFeedback
 843           #x0000001                   XIMStringConversionLeftEdge
 844           #x0000002                   XIMStringConversionRightEdge
 845           #x0000004                   XIMStringConversionTopEdge
 846           #x0000008                   XIMStringConversionBottomEdge
 847           #x0000010                   XIMStringConversionConvealed
 848           #x0000020                   XIMStringConversionWrapped
 849      2     n                          byte length of the retrieved string
 850      n     STRING8                    retrieved string
 851      p                                unused, p = Pad(n)
 852      2     m                          byte length of feedback array
 853      2                                unused
 854      m     LISTofXIMSTRCONVFEEDBACK   feedback array(*1)
 855
 856 (*1)   This field is reserved for future use.
 857
 858 XIMFEEDBACK
 859      4    CARD32       XIMFeedback
 860           #x000001     XIMReverse
 861           #x000002     XIMUnderline
 862           #x000004     XIMHighlight
 863           #x000008     XIMPrimary
 864           #x000010     XIMSecondary
 865           #x000020     XIMTertiary
 866           #x000040     XIMVisibleToForward
 867           #x000080     XIMVisibleToBackward
 868           #x000100     XIMVisibleCenter
 869
 870 XIMHOTKEYSTATE
 871      4    CARD32       XIMHotKeyState
 872           #x0000001    XIMHotKeyStateON
 873           #x0000002    XIMHotKeyStateOFF
 874
 875 XIMPREEDITSTATE
 876      4    CARD32       XIMPreeditState
 877           #x0000001    XIMPreeditEnable
 878           #x0000002    XIMPreeditDisable
 879
 880 XIMRESETSTATE
 881      4    CARD32       XIMResetState
 882           #x0000001    XIMInitialState
 883           #x0000002    XIMPreserveState
 884 </literallayout>
 885 </sect2>
 886
 887 <sect2 id="Error_Notification">
 888 <title>Error Notification</title>
 889 <!-- .XS -->
 890 <!-- (SN Error Notification -->
 891 <!-- .XE -->
 892 <para>
 893 Both the IM Server and the IM library return
 894 <function>XIM_ERROR</function>
 895 messages instead of the corresponding reply messages if any errors occur
 896 during data processing.
 897 </para>
 898
 899 <para>
 900 At most one error is generated per request. If more than one error condition
 901 is encountered in processing a request, the choice of which error is returned
 902 is implementation-dependent.
 903 </para>
 904
 905 <literallayout class="monospaced">
 906 XIM_ERROR (IM Server &lt;--&gt; IM library)
 907 <!-- .sp 6p -->
 908           2     CARD16          input-method-ID
 909           2     CARD16          input-context-ID
 910           2     BITMASK16       flag (*1)
 911                 #0000           Both Input-Method-ID and Input-Context-ID are invalid
 912                 #0001           Input-Method-ID is valid
 913                 #0002           Input-Context-ID is valid
 914           2     CARD16          Error Code
 915                 #1              BadAlloc
 916                 #2              BadStyle
 917                 #3              BadClientWindow
 918                 #4              BadFocusWindow
 919                 #5              BadArea
 920                 #6              BadSpotLocation
 921                 #7              BadColormap
 922                 #8              BadAtom
 923                 #9              BadPixel
 924                 #10             BadPixmap
 925                 #11             BadName
 926                 #12             BadCursor
 927                 #13             BadProtocol
 928                 #14             BadForeground
 929                 #15             BadBackground
 930                 #16             LocaleNotSupported
 931                 #999            BadSomething (*2)
 932           2     n               byte length of error detail.
 933           2     CARD16          type of error detail (*3)
 934           n     STRING8         error detail (*4)
 935           p                     unused, p = Pad(n)
 936
 937 (*1)  Before an IM is created, both Input-Method-ID and
 938       Input-Context-ID are invalid.
 939       Before an IC is created, only Input-Method-ID is valid.
 940       After that, both of Input-Method-ID and Input-Context-ID are valid.
 941
 942 (*2) Unspecific error, for example "language engine died"
 943
 944 (*3) This field is reserved for future use.
 945
 946 (*4) Vendor defined detail error message
 947 </literallayout>
 948 </sect2>
 949
 950 <sect2 id="Connection_Establishment">
 951 <title>Connection Establishment</title>
 952 <!-- .XS -->
 953 <!-- (SN Connection Establishment -->
 954 <!-- .XE -->
 955 <para>
 956 <function>XIM_CONNECT</function>
 957 message requests to establish a connection over a mutually-understood virtual
 958 stream.
 959 </para>
 960
 961 <literallayout class="monospaced">
 962 XIM_CONNECT (IM library -&gt; IM Server)
 963      1                      byte order
 964            #x42             MSB first
 965            #x6c             LSB first
 966      1                      unused
 967      2     CARD16           client-major-protocol-version (*1)
 968      2     CARD16           client-minor-protocol-version (*1)
 969      2     CARD16           number of client-auth-protocol-names
 970      n     LISTofSTRING     client-auth-protocol-names
 971
 972 (*1) Specify the version of IM Protocol that the client supports.
 973 </literallayout>
 974
 975 <para>
 976 A client must send
 977 <function>XIM_CONNECT</function>
 978 message as the first message on the connection.
 979 The list specifies the names of authentication protocols the sending
 980 IM Server is willing to perform.
 981 (If the client need not authenticate, the list may be omited.)
 982 </para>
 983
 984 <para>
 985 <function>XIM_AUTH_REQUIRED </function>
 986 message is used to send the authentication protocol name and protocol-specific
 987 data.
 988 </para>
 989
 990 <literallayout class="monospaced">
 991 XIM_AUTH_REQUIRED (IM library &lt;--&gt; IM Server)
 992
 993      1     CARD8              auth-protocol-index
 994      3                        unused
 995      2     n                  length of authentication data
 996      2                        unused
 997      n     &lt;varies&gt;     data
 998      p                        unused, p = Pad(n)
 999 </literallayout>
1000
1001 <para>
1002 The auth-protocol is specified by an index into the list of names
1003 given in the
1004 <function>XIM_CONNECT</function>
1005 or
1006 <function>XIM_AUTH_SETUP</function>
1007 message. Any protocol-specific data that might be required is also sent.
1008 </para>
1009
1010 <para>
1011 The IM library sends
1012 <function>XIM_AUTH_REPLY</function>
1013 message as the reply to
1014 <function>XIM_AUTH_REQUIRED</function>
1015 message, if the IM Server is authenticated.
1016 </para>
1017
1018 <literallayout class="monospaced">
1019 XIM_AUTH_REPLY (IM library -&gt; IM Server)
1020      2     n                 length of authentication data
1021      2                       unused
1022      2     n                 length of authentication data
1023      2                       unused
1024      n     &lt;varies&gt;      data
1025      p                       unused, p = Pad(n)
1026 </literallayout>
1027
1028 <para>
1029 The auth data is specific to the authentication protocol in use.
1030 </para>
1031 <para>
1032 <!-- .LP -->
1033 <function>XIM_AUTH_NEXT </function>
1034 message requests to send more auth data.
1035 </para>
1036
1037 <literallayout class="monospaced">
1038 XIM_AUTH_NEXT (IM library &lt;--&gt; IM Server)
1039      2     n                 length of authentication data
1040      2                       unused
1041      n     &lt;varies&gt;      data
1042      p                       unused, p = Pad(n)
1043 </literallayout>
1044 <para>
1045 The auth data is specific to the authentication protocol in use.
1046 </para>
1047
1048 <para>
1049 <!-- .LP -->
1050 The IM Server sends
1051 <function>XIM_AUTH_SETUP</function>
1052 message to authenticate the client.
1053 </para>
1054
1055 <literallayout class="monospaced">
1056 XIM_AUTH_SETUP (IM Server -&gt; IM library)
1057      2     CARD16           number of client-auth-protocol-names
1058      2                      unused
1059      n     LISTofSTRING     server-auth-protocol-names
1060 </literallayout>
1061
1062 <para>
1063 The list specifies the names of authentication protocols the
1064 client is willing to perform.
1065 </para>
1066
1067 <para>
1068 <function>XIM_AUTH_NG</function>
1069 message requests to give up the connection.
1070 </para>
1071
1072 <para>
1073 XIM_AUTH_NG (IM library &lt;--&gt; IM Server)
1074 </para>
1075
1076 <para>
1077 The IM Server sends
1078 <function>XIM_CONNECT_REPLY</function>
1079 message as the reply to
1080 <function>XIM_CONNECT</function>
1081 or
1082 <function>XIM_AUTH_REQUIRED</function>
1083 message.
1084 </para>
1085
1086 <literallayout class="monospaced">
1087 XIM_CONNECT_REPLY (IM Server -&gt; IM library)
1088      2     CARD16     server-major-protocol-version (*1)
1089      2     CARD16     server-minor-protocol-version (*1)
1090
1091 (*1) Specify the version of IM Protocol that the IM Server supports.
1092 This document specifies major version one, minor version zero.
1093 </literallayout>
1094
1095 <para>
1096 Here are the state diagrams for the client and the IM Server.
1097 </para>
1098
1099 <para>
1100 State transitions for the client
1101 </para>
1102
1103 <variablelist>
1104   <varlistentry>
1105     <term><emphasis remap='I'>init_status</emphasis>:</term>
1106     <listitem>
1107       <para>
1108 Use authorization function -&gt; <emphasis remap='I'>client_ask</emphasis>
1109       </para>
1110       <para>
1111 Not use authorization function -&gt; <emphasis remap='I'>client_no_check</emphasis>
1112       </para>
1113     </listitem>
1114   </varlistentry>
1115   <varlistentry>
1116     <term><emphasis remap='I'>start</emphasis>:</term>
1117     <listitem>
1118       <para>
1119 Send <function>XIM_CONNECT</function>
1120       </para>
1121       <para>
1122 If <emphasis remap='I'>client_ask</emphasis> -&gt; <emphasis remap='I'>client_wait1</emphasis>
1123       </para>
1124       <para>
1125 If <emphasis remap='I'>client_no_check</emphasis>,
1126 client-auth-protocol-names may be omited -&gt; <emphasis remap='I'>client_wait2</emphasis>
1127       </para>
1128     </listitem>
1129   </varlistentry>
1130   <varlistentry>
1131     <term><emphasis remap='I'>client_wait1</emphasis>:</term>
1132     <listitem>
1133       <para>
1134 Receive <function>XIM_AUTH_REQUIRED</function>
1135 -&gt; <emphasis remap='I'>client_check</emphasis>
1136       </para>
1137       <para>
1138 Receive &lt;other&gt; -&gt; <emphasis remap='I'>client_NG</emphasis>
1139       </para>
1140     </listitem>
1141   </varlistentry>
1142   <varlistentry>
1143     <term><emphasis remap='I'>client_check</emphasis>:</term>
1144     <listitem>
1145       <para>
1146 If no more auth needed, send <function>XIM_AUTH_REPLY</function>
1147 -&gt; <emphasis remap='I'>client_wait2</emphasis>
1148       </para>
1149       <para>
1150 If good auth data, send <function>XIM_AUTH_NEXT</function>
1151 -&gt; <emphasis remap='I'>client_wait1</emphasis>
1152       </para>
1153       <para>
1154 If bad auth data, send <function>XIM_AUTH_NG</function>
1155 -&gt; give up on this protocol
1156       </para>
1157     </listitem>
1158   </varlistentry>
1159   <varlistentry>
1160     <term><emphasis remap='I'>client_wait2</emphasis>:</term>
1161     <listitem>
1162       <para>
1163 Receive <function>XIM_CONNECT_REPLY</function>
1164 -&gt; connect Receive
1165 <function>XIM_AUTH_SETUP </function>
1166 -&gt; <emphasis remap='I'>client_more</emphasis>
1167       </para>
1168       <para>
1169 Receive <function>XIM_AUTH_NEXT</function>
1170 -&gt; <emphasis remap='I'>client_more</emphasis>
1171       </para>
1172       <para>
1173 Receive <function>XIM_AUTH_NG</function>
1174 -&gt; give up on this protocol
1175       </para>
1176       <para>
1177 Receive &lt;other&gt; -&gt; <emphasis remap='I'>client_NG</emphasis>
1178       </para>
1179     </listitem>
1180   </varlistentry>
1181   <varlistentry>
1182     <term><emphasis remap='I'>client_more</emphasis>:</term>
1183     <listitem>
1184       <para>
1185 Send <function>XIM_AUTH_REQUIRED</function>
1186 -&gt; <emphasis remap='I'>client_wait2</emphasis>
1187       </para>
1188     </listitem>
1189   </varlistentry>
1190   <varlistentry>
1191     <term><emphasis remap='I'>client_NG</emphasis>:</term>
1192     <listitem>
1193       <para>
1194 Send <function>XIM_AUTH_NG</function>
1195 -&gt; give up on this protocol
1196       </para>
1197     </listitem>
1198   </varlistentry>
1199 </variablelist>
1200
1201 <para>
1202 State transitions for the IM Server
1203 </para>
1204
1205 <variablelist>
1206   <varlistentry>
1207     <term><emphasis remap='I'>init_status</emphasis>:</term>
1208     <listitem>
1209       <para>
1210 Use authorization function -&gt; <emphasis remap='I'>server_ask</emphasis>
1211       </para>
1212       <para>
1213 Not use authorization function -&gt; <emphasis remap='I'>server_no_check</emphasis>
1214       </para>
1215     </listitem>
1216   </varlistentry>
1217   <varlistentry>
1218     <term><emphasis remap='I'>start</emphasis>:</term>
1219     <listitem>
1220       <para>
1221 Receive <function>XIM_CONNECT</function>
1222       </para>
1223       <para>
1224 -&gt; <emphasis remap='I'>start2</emphasis>
1225 Receive &lt;other&gt; -&gt; <emphasis remap='I'>server_NG</emphasis>
1226       </para>
1227     </listitem>
1228   </varlistentry>
1229   <varlistentry>
1230     <term><emphasis remap='I'>start2</emphasis>:</term>
1231     <listitem>
1232       <para>
1233 If <emphasis remap='I'>client_ask</emphasis>, send
1234 <function>XIM_AUTH_REQUIRED</function>
1235 -&gt; <emphasis remap='I'>server_wait1</emphasis>
1236       </para>
1237       <para>
1238 If <emphasis remap='I'>client_no_check</emphasis> and
1239 <emphasis remap='I'>server_ask</emphasis>, send
1240 <function>XIM_AUTH_SETUP</function>
1241 -&gt; <emphasis remap='I'>server_wait2</emphasis>
1242       </para>
1243       <para>
1244 If <emphasis remap='I'>client_no_check</emphasis> and
1245 <emphasis remap='I'>server_no_check</emphasis>, send
1246 <function>XIM_CONNECT_REPLY</function>
1247 -&gt; connect
1248       </para>
1249     </listitem>
1250   </varlistentry>
1251   <varlistentry>
1252     <term><emphasis remap='I'>server_wait1</emphasis>:</term>
1253     <listitem>
1254       <para>
1255 Receive
1256 <function>XIM_AUTH_REPLY</function>
1257 -&gt; <emphasis remap='I'>server2</emphasis>
1258       </para>
1259       <para>
1260 Receive
1261 <function>XIM_AUTH_NEXT</function>
1262 -&gt; <emphasis remap='I'>server_more</emphasis>
1263       </para>
1264       <para>
1265 Receive &lt;other&gt; -&gt; <emphasis remap='I'>server_NG</emphasis>
1266       </para>
1267     </listitem>
1268   </varlistentry>
1269   <varlistentry>
1270     <term><emphasis remap='I'>server_more</emphasis></term>
1271     <listitem>
1272       <para>
1273 Send
1274 <function>XIM_AUTH_REQUIRED</function>
1275 -&gt; <emphasis remap='I'>server_wait1</emphasis>
1276       </para>
1277     </listitem>
1278   </varlistentry>
1279   <varlistentry>
1280     <term><emphasis remap='I'>server2</emphasis></term>
1281     <listitem>
1282       <para>
1283 If <emphasis remap='I'>server_ask</emphasis>, send
1284 <function>XIM_AUTH_SETUP</function>
1285 -&gt; <emphasis remap='I'>server_wait2</emphasis>
1286       </para>
1287       <para>
1288 If <emphasis remap='I'>server_no_check</emphasis>, send
1289 <function>XIM_CONNECT_REPLY </function>
1290 -&gt; connect
1291       </para>
1292     </listitem>
1293   </varlistentry>
1294   <varlistentry>
1295     <term><emphasis remap='I'>server_wait2</emphasis></term>
1296     <listitem>
1297       <para>
1298 Receive
1299 <function>XIM_AUTH_REQUIRED</function>
1300 -&gt; <emphasis remap='I'>server_check</emphasis>
1301       </para>
1302       <para>
1303 Receive &lt;other&gt; -&gt; <emphasis remap='I'>server_NG</emphasis>
1304       </para>
1305     </listitem>
1306   </varlistentry>
1307   <varlistentry>
1308     <term><emphasis remap='I'>server_check</emphasis></term>
1309     <listitem>
1310       <para>
1311 If no more auth data, send
1312 <function>XIM_CONNECT_REPLY</function>
1313 -&gt; connect
1314       </para>
1315       <para>
1316 If bad auth data, send
1317 <function>XIM_AUTH_NG</function>
1318 -&gt; give up on this protocol
1319       </para>
1320       <para>
1321 If good auth data, send
1322 <function>XIM_AUTH_NEXT</function>
1323 -&gt; <emphasis remap='I'>server_wait2</emphasis>
1324       </para>
1325     </listitem>
1326   </varlistentry>
1327   <varlistentry>
1328     <term><emphasis remap='I'>server_NG</emphasis></term>
1329     <listitem>
1330       <para>
1331 Send
1332 <function>XIM_AUTH_NG</function>
1333 -&gt; give up on this protocol
1334       </para>
1335     </listitem>
1336   </varlistentry>
1337 </variablelist>
1338
1339 <para>
1340 <function>XIM_DISCONNECT </function>
1341 message requests to shutdown the connection over a mutually-understood
1342 virtual stream.
1343 </para>
1344
1345 <para>
1346 XIM_DISCONNECT (IM library -&gt; IM Server)
1347 </para>
1348
1349 <para>
1350 <function>XIM_DISCONNECT</function>
1351 is a synchronous request.  The IM library should wait until it receives
1352 either an
1353 <function>XIM_DISCONNECT_REPLY</function>
1354 packet or an <function>XIM_ERROR</function> packet.
1355 </para>
1356
1357 <para>
1358 XIM_DISCONNECT_REPLY (IM Server -&gt; IM library)
1359 </para>
1360
1361 <para>
1362 <function>XIM_OPEN</function>
1363 requests to establish a logical connection between the IM library and the IM
1364 Server.
1365 </para>
1366
1367 <literallayout class="monospaced">
1368 XIM_OPEN (IM library -&gt; IM Server)
1369      n     STR     locale name
1370      p             unused, p = Pad(n)
1371 </literallayout>
1372
1373 <para>
1374 <function>XIM_OPEN</function>
1375 is a synchronous request.  The IM library should wait until receiving
1376 either an <function>XIM_OPEN_REPLY</function>
1377 packet or an <function>XIM_ERROR </function> packet.
1378 </para>
1379
1380 <literallayout class="monospaced">
1381 XIM_OPEN_REPLY (IM Server -&gt; IM library)
1382      2     CARD16             input-method-ID
1383      2     n                  byte length of IM attributes supported
1384      n     LISTofXIMATTR      IM attributes supported
1385      2     m                  byte length of IC attributes supported
1386      2     CARD16             unused
1387      m     LISTofXICATTR      IC attributes supported
1388 </literallayout>
1389
1390 <para>
1391 <function>XIM_OPEN_REPLY</function>
1392 message returns all supported IM and IC attributes in LISTofXIMATTR and
1393 LISTofXICATTR.  These IM and IC attribute IDs are used to reduce the amount
1394 of data which must be transferred via the network. In addition, this
1395 indicates to the IM library what kinds of IM/IC attributes can be used
1396 in this session, and what types of data will be exchanged. This allows
1397 the IM Server provider and application writer to support IM system
1398 enhancements with new IM/IC attributes, without modifying Xlib.
1399 The IC value for the separator of NestedList must be included in the
1400 LISTofXICATTR.
1401 </para>
1402
1403 <para>
1404 <function>XIM_CLOSE </function>
1405 message requests to shutdown the logical connection between the IM library
1406 and the IM Server.
1407 </para>
1408
1409 <literallayout class="monospaced">
1410 XIM_CLOSE (IM library -&gt; IM Server)
1411      2     CARD16     input-method-ID
1412      2                unused
1413 </literallayout>
1414
1415 <para>
1416 <function>XIM_CLOSE</function>
1417 is a synchronous request.  The IM library should wait until receiving
1418 either an <function>XIM_CLOSE_REPLY</function>
1419 packet or an <function>XIM_ERROR</function> packet.
1420 </para>
1421
1422 <literallayout class="monospaced">
1423 XIM_CLOSE_REPLY (IM Server -&gt; IM library)
1424      2     CARD16     input-method-ID
1425      2                unused
1426 </literallayout>
1427
1428 </sect2>
1429
1430 <sect2 id='Event_Flow_Control_2'>
1431 <title>Event Flow Control</title>
1432 <!-- .XS -->
1433 <!-- (SN Event Flow Control -->
1434 <!-- .XE -->
1435 <para>
1436 <!-- .LP -->
1437 An IM Server must send
1438 <function>XIM_SET_EVENT_MASK </function>
1439 message to the IM library in order for events to be forwarded to the IM
1440 Server, since the IM library initially doesn't forward any events to the
1441 IM Server. In the protocol, the IM Server will specify masks of X events
1442 to be forwarded and which need to be synchronized by the IM library.
1443 </para>
1444
1445 <literallayout class="monospaced">
1446 XIM_SET_EVENT_MASK (IM Server -&gt; IM library)
1447      2     CARD16        input-method-ID
1448      2     CARD16        input-context-ID
1449      4     EVENTMASK     forward-event-mask (*1)
1450      4     EVENTMASK     synchronous-event-mask (*2)
1451
1452 (*1)  Specify all the events to be forwarded to the IM Server by the IM library.
1453 (*2)  Specify the events to be forwarded with synchronous flag on by the IM library.
1454 </literallayout>
1455
1456 <para>
1457 <function>XIM_SET_EVENT_MASK </function>
1458 is an asynchronous request.  The event masks are valid immediately after
1459 they are set until changed by another
1460 <function>XIM_SET_EVENT_MASK</function>
1461 message.  If input-context-ID is set to zero, the default value of the
1462 input-method-ID will be changed to the event masks specified in the request.
1463 That value will be used for the IC's which have no individual values.
1464 </para>
1465
1466 <para>
1467 Using the Dynamic Event Flow model, an IM Server sends
1468 <function>XIM_REGISTER_TRIGGERKEYS </function>
1469 message to the IM library before sending
1470 <function>XIM_OPEN_REPLY</function>
1471 message.
1472 Or the IM library may suppose that the IM Server uses the Static Event Flow
1473 model.
1474 </para>
1475
1476 <literallayout class="monospaced">
1477 XIM_REGISTER_TRIGGERKEYS (IM Server -&gt; IM library)
1478 <!-- .sp 6p -->
1479      2     CARD16                  input-method-ID
1480      2                             unused
1481      4     n                       byte length of on-keys
1482      n     LISTofXIMTRIGGERKEY     on-keys list
1483      4     m                       byte length of off-keys
1484      m     LISTofXIMTRIGGERKEY     off-keys list
1485 </literallayout>
1486
1487 <para>
1488 <function>XIM_REGISTER_TRIGGERKEYS</function>
1489 is an asynchronous request.
1490 The IM Server notifys the IM library of on-keys and off-keys lists with
1491 this message.
1492 </para>
1493
1494 <para>
1495 The IM library notifys the IM Server with
1496 <function>XIM_TRIGGER_NOTIFY </function>
1497 message that a key event matching either on-keys or off-keys has been occurred.
1498 </para>
1499
1500 <literallayout class="monospaced">
1501 XIM_TRIGGER_NOTIFY (IM library -&gt; IM Server)
1502      2     CARD16           input-method-ID
1503      2     CARD16           input-context-ID
1504      4     CARD32           flag
1505            #0               on-keys list
1506            #1               off-keys list
1507      4     CARD32           index of keys list
1508      4     EVENTMASK        client-select-event-mask (*1)
1509
1510 (*1)  Specify the events currently selected by the IM library with XSelectInput.
1511
1512 </literallayout>
1513
1514 <para>
1515 <function>XIM_TRIGGER_NOTIFY </function>
1516 is a synchronous request.  The IM library should wait until receiving
1517 either an <function>XIM_TRIGGER_NOTIFY_REPLY</function>
1518 packet or an <function>XIM_ERROR</function> packet.
1519 </para>
1520
1521 <literallayout class="monospaced">
1522 XIM_TRIGGER_NOTIFY_REPLY (IM Server -&gt; IM library)
1523      2     CARD16     input-method-ID
1524      2     CARD16     input-context-ID
1525 </literallayout>
1526
1527 </sect2>
1528
1529 <sect2 id="Encoding_Negotiation">
1530 <title>Encoding Negotiation</title>
1531 <para>
1532 <function>XIM_ENCODING_NEGOTIATION</function>
1533 message requests to decide which encoding to be sent across the wire.
1534 When the negotiation fails, the fallback default encoding is Portable
1535 Character Encoding.
1536 </para>
1537
1538 <literallayout class="monospaced">
1539 XIM_ENCODING_NEGOTIATION (IM library -&gt; IM Server).sp 6p
1540      2     CARD16                 input-method-ID
1541      2     n                      byte length of encodings listed by name
1542      n     LISTofSTR              list of encodings supported in the IM library.
1543      p                            unused, p = Pad(n)
1544      2     m                      byte length of encodings listed by detailed data
1545      2                            unused
1546      m     LISTofENCODINGINFO     list of encordings supported in the IM library
1547 </literallayout>
1548
1549 <para>
1550 The IM Server must choose one encoding from the list sent by the IM library.
1551 If index of the encording determined is -1 to indicate that the negotiation
1552 is failed, the fallback default encoding is used.
1553 The message must be issued after sending
1554 <function>XIM_OPEN</function> message via XOpenIM().
1555 The name of encoding may be registered with X Consortium.
1556 </para>
1557
1558 <para>
1559 <function>XIM_ENCODING_NEGOTIATION</function>
1560 is a synchronous request.  The IM library should wait until receiving
1561 either an <function>XIM_ENCODING_NEGOTIATION_REPLY</function>
1562 packet or an <function>XIM_ERROR</function> packet.
1563 </para>
1564
1565
1566 <literallayout class="monospaced">
1567 XIM_ENCODING_NEGOTIATION_REPLY (IM Server -&gt; IM library)
1568      2     CARD16     input-method-ID
1569      2     CARD16     category of the encoding determined.
1570            #0         name
1571            #1         detailed data
1572      2     INT16      index of the encoding determinated.
1573      2                unused
1574 </literallayout>
1575
1576 </sect2>
1577
1578 <sect2 id="Query_the_supported_extension_protocol_list">
1579 <title>Query the supported extension protocol list</title>
1580 <para>
1581 <function>XIM_QUERY_EXTENSION</function>
1582 message requests to query the IM extensions supported by the IM Server to
1583 which the client is being connected.
1584 </para>
1585
1586 <literallayout class="monospaced">
1587 XIM_QUERY_EXTENSION (IM library -&gt; IM Server)
1588      2     CARD16        input-method-ID
1589      2     n             byte length of extensions supported by the IM library
1590      n     LISTofSTR     extensions supported by the IM library
1591      p                   unused, p = Pad(n)
1592 </literallayout>
1593
1594 <para>
1595 An example of a supported extension is FrontEnd.
1596 The message must be issued after sending
1597 <function>XIM_OPEN </function> message via XOpenIM().
1598 </para>
1599
1600 <para>
1601 If n is 0, the IM library queries the IM Server for all extensions.
1602 </para>
1603
1604 <para>
1605 If n is not 0, the IM library queries whether the IM Server supports the
1606 contents specified in the list.
1607 </para>
1608
1609 <para>
1610 If a client uses an extension request without previously having issued a
1611 <function>XIM_QUERY_EXTENSION</function>
1612 message for that extension, the IM Server responds with a
1613 <function>BadProtocol</function>
1614 error.  If the IM Server encounters a request with an unknown MAJOR-OPCODE
1615 or MINOR-OPCODE, it responds with a
1616 <function>BadProtocol</function> error.
1617 </para>
1618
1619 <para>
1620 <function>XIM_QUERY_EXTENSION</function>
1621 is a synchronous request.  The IM library should wait until receiving
1622 either an <function>XIM_QUERY_EXTENSION_REPLY</function>
1623 packet or an <function>XIM_ERROR</function> packet.
1624 </para>
1625
1626 <literallayout class="monospaced">
1627 XIM_QUERY_EXTENSION_REPLY (IM Server -&gt; IM library)
1628      2     CARD16      input-method-ID
1629      2     n           byte length of extensions supported by both the IM library and the IM Server
1630      n     LISTofEXT   list of extensions supported by both the IM library and the IM Server
1631
1632 </literallayout>
1633
1634 <para>
1635 <function>XIM_QUERY_EXTENSION_REPLY</function>
1636 message returns the list of extensions supported by both the IM library and
1637 the IM Server. If the list passed in
1638 <function>XIM_QUERY_EXTENSION</function>
1639 message is NULL, the IM Server returns the full list of extensions supported
1640 by the IM Server.  If the list is not NULL, the IM Server returns the
1641 extensions in the list that are supported by the IM Server.
1642 </para>
1643
1644 <para>
1645 <!-- .LP -->
1646 A zero-length string is not a valid extension name.  The IM library should
1647 disregard any zero-length strings that are returned in the extension list.
1648 The IM library does not use the requests which are not supported by the IM
1649 Server.
1650 </para>
1651
1652 </sect2>
1653
1654 <sect2 id="Setting_IM_Values">
1655 <title>Setting IM Values</title>
1656 <para>
1657 <function>XIM_SET_IM_VALUES </function>
1658 requests to set attributes to the IM.
1659 </para>
1660
1661 <literallayout class="monospaced">
1662 XIM_SET_IM_VALUES (IM library -&gt; IM Server)
1663      2     CARD16                 input-method-ID
1664      2     n                      byte length of im-attribute
1665      n     LISTofXIMATTRIBUTE     im-attributes
1666 </literallayout>
1667
1668 <para>
1669 The im-attributes in
1670 <function>XIM_SET_IM_VALUES</function>
1671 message are specified as a LISTofXIMATTRIBUTE, specifying the attributes
1672 to be set. Attributes other than the ones returned by
1673 <function>XIM_OPEN_REPLY</function>
1674 message should not be specified.
1675 </para>
1676
1677 <para>
1678 <function>XIM_SET_IM_VALUES </function>
1679 is a synchronous request. The IM library should wait until receiving
1680 either an
1681 <function>XIM_SET_IM_VALUES_REPLY</function>
1682 packet or an
1683 <function>XIM_ERROR</function>
1684 packet, because it must receive the error attribute if
1685 <function>XIM_ERROR</function> message is returned.
1686 </para>
1687
1688 <literallayout class="monospaced">
1689 XIM_SET_IM_VALUES_REPLY (IM Server -&gt; IM library)
1690      2     CARD16     input-method-ID
1691      2                unused
1692 </literallayout>
1693
1694 <para>
1695 <function>XIM_SET_IM_VALUES_REPLY</function>
1696 message returns the input-method-ID to distinguish replies from multiple IMs.
1697 </para>
1698
1699 </sect2>
1700 <sect2 id="Getting_IM_Values">
1701 <title>Getting IM Values</title>
1702 <para>
1703 <function>XIM_GET_IM_VALUES </function>
1704 requests to query IM values supported by the IM Server currently being
1705 connected.
1706 </para>
1707
1708 <literallayout class="monospaced">
1709 XIM_GET_IM_VALUES (IM library -&gt; IM Server)
1710      2     CARD16           input-method-ID
1711      2     n                byte length of im-attribute-id
1712      n     LISTofCARD16     im-attribute-id
1713      p                      unused, p=Pad(n)
1714 </literallayout>
1715
1716 <para>
1717 <function>XIM_GET_IM_VALUES</function>
1718 is a synchronous request.  The IM library should wait until it receives
1719 either an
1720 <function>XIM_GET_IM_VALUES_REPLY</function>
1721 packet or an <function>XIM_ERROR</function> packet.
1722 </para>
1723
1724 <literallayout class="monospaced">
1725 XIM_GET_IM_VALUES_REPLY (IM Server -&gt; IM library)
1726      2     CARD16                 input-method-ID
1727      2     n                      byte length of im-attributes returned
1728      n     LISTofXIMATTRIBUTE     im-attributes returned
1729 </literallayout>
1730
1731 <para>
1732 The IM Server returns IM values with
1733 <function>XIM_GET_IM_VALUES_REPLY</function>
1734 message.  The order of the returned im-attribute values corresponds directly
1735 to that of the list passed with the
1736 <function>XIM_GET_IM_VALUES</function> message.
1737 </para>
1738
1739 </sect2>
1740 <sect2 id="Creating_an_IC">
1741 <title>Creating an IC</title>
1742 <para>
1743 <function>XIM_CREATE_IC</function> message requests to create an IC.
1744 </para>
1745
1746 <literallayout class="monospaced">
1747 XIM_CREATE_IC (IM library -&gt; IM Server)
1748      2     CARD16                 input-method-ID
1749      2     n                      byte length of ic-attributes
1750      n     LISTofXICATTRIBUTE     ic-attributes
1751 </literallayout>
1752
1753 <para>
1754 The input-context-id is specified by the IM Server to identify the client
1755 (IC).  (It is not specified by the client in
1756 <function>XIM_CREATE_IC</function>
1757 message.), and it should not be set to zero.
1758 </para>
1759
1760 <para>
1761 <function>XIM_CREATE_IC</function>
1762 is a synchronous request which returns the input-context-ID.
1763 The IM library should wait until it receives either an
1764 <function>XIM_CREATE_IC_REPLY</function>
1765 packet or an
1766 <function>XIM_ERROR</function>
1767 packet.
1768 </para>
1769
1770 <literallayout class="monospaced">
1771 XIM_CREATE_IC_REPLY (IM Server -&gt; IM library)
1772      2     CARD16     input-method-ID
1773      2     CARD16     input-context-ID
1774 </literallayout>
1775
1776 </sect2>
1777 <sect2 id="Destroying_the_IC">
1778 <title>Destroying the IC</title>
1779 <para>
1780 <function>XIM_DESTROY_IC</function>
1781 message requests to destroy the IC.
1782 </para>
1783
1784 <literallayout class="monospaced">
1785 XIM_DESTROY_IC (IM library -&gt; IM Server)
1786      2     CARD16     input-method-ID
1787      2     CARD16     input-context-ID
1788 </literallayout>
1789
1790 <para>
1791 <function>XIM_DESTROY_IC </function>
1792 is a synchronous request. The IM library should not free its resources
1793 until it receives an
1794 <function>XIM_DESTROY_IC_REPLY</function>
1795 message because <function>XIM_DESTROY_IC</function>
1796 message may result in Callback packets such as
1797 <function>XIM_PREEDIT_DRAW</function>
1798 and <function>XIM_PREEDIT_DONE.</function>
1799 </para>
1800
1801 <literallayout class="monospaced">
1802 XIM_DESTROY_IC_REPLY (IM Server -&gt; IM library)
1803      2     CARD16     input-method-ID
1804      2     CARD16     input-context-ID
1805 </literallayout>
1806
1807 </sect2>
1808
1809 <sect2 id="Setting_IC_Values">
1810 <title>Setting IC Values</title>
1811 <para>
1812 <function>XIM_SET_IC_VALUES</function>
1813 messages requests to set attributes to the IC.
1814 </para>
1815
1816
1817 <literallayout class="monospaced">
1818 XIM_SET_IC_VALUES (IM library -&gt; IM Server)
1819      2     CARD16                 input-method-ID
1820      2     CARD16                 input-context-ID
1821      2     n                      byte length of ic-attributes
1822      2                            unused
1823      n     LISTofXICATTRIBUTE     ic-attributes
1824 </literallayout>
1825
1826 <para>
1827 The ic-attributes in
1828 <function>XIM_SET_IC_VALUES</function>
1829 message are specified as a LISTofXICATTRIBUTE, specifying the attributes
1830 to be set. Attributes other than the ones returned by
1831 <function>XIM_OPEN_REPLY</function> message should not be specified.
1832 </para>
1833
1834 <para>
1835 <function>XIM_SET_IC_VALUES </function>
1836 is a synchronous request. The IM library should wait until receiving
1837 either an <function>XIM_SET_IC_VALUES_REPLY </function>
1838 packet or an <function>XIM_ERROR</function>
1839 packet, because it must receive the error attribute if
1840 <function>XIM_ERROR</function> message is returned.
1841 </para>
1842
1843
1844 <literallayout class="monospaced">
1845 XIM_SET_IC_VALUES_REPLY (IM Server -&gt; IM library)
1846 <!-- .sp 6p -->
1847      2     CARD16     input-method-ID
1848      2     CARD16     input-context-ID
1849 </literallayout>
1850
1851 </sect2>
1852 <sect2 id="Getting_IC_Values">
1853 <title>Getting IC Values</title>
1854 <para>
1855 <function>XIM_GET_IC_VALUES</function>
1856 message requests to query IC values supported by the IM Server currently
1857 being connected.
1858 </para>
1859
1860
1861 <literallayout class="monospaced">
1862 XIM_GET_IC_VALUES (IM library -&gt; IM Server)
1863 <!-- .sp 6p -->
1864      2     CARD16           input-method-ID
1865      2     CARD16           input-context-ID
1866      2     n                byte length of ic-attribute-id
1867      n     LISTofCARD16     ic-attribute-id
1868      p                      unused, p=Pad(2+n)
1869 </literallayout>
1870
1871 <para>
1872 In LISTofCARD16, the appearance of the ic-attribute-id for the separator
1873 of NestedList shows the end of the heading nested list.
1874 </para>
1875
1876 <para>
1877 <function>XIM_GET_IC_VALUES</function>
1878 is a synchronous request and returns each attribute with its values to
1879 show the correspondence.  The IM library should wait until receiving
1880 either an <function>XIM_GET_IC_VALUES_REPLY</function>
1881 packet or an <function>XIM_ERROR</function> packet.
1882 </para>
1883
1884 <literallayout class="monospaced">
1885 XIM_GET_IC_VALUES_REPLY (IM Server -&gt; IM library)
1886      2     CARD16                 input-method-ID
1887      2     CARD16                 input-context-ID
1888      2     n                      byte length of ic-attribute
1889      2                            unused
1890      n     LISTofXICATTRIBUTE     ic-attribute
1891 </literallayout>
1892
1893 </sect2>
1894 <sect2 id="Setting_IC_Focus">
1895 <title>Setting IC Focus</title>
1896 <para>
1897 <function>XIM_SET_IC_FOCUS</function>
1898 message requests to set the focus to the IC.
1899 </para>
1900
1901 <literallayout class="monospaced">
1902 XIM_SET_IC_FOCUS (IM library -&gt; IM Server)
1903      2     CARD16     input-method-ID
1904      2     CARD16     input-context-ID
1905 </literallayout>
1906
1907 <para>
1908 <function>XIM_SET_IC_FOCUS</function> is an asynchronous request.
1909 </para>
1910
1911 </sect2>
1912 <sect2 id="Unsetting_IC_Focus">
1913 <title>Unsetting IC Focus</title>
1914 <para>
1915 <function>XIM_UNSET_IC_FOCUS</function>
1916 message requests to unset the focus to the focused IC.
1917 </para>
1918
1919 <literallayout class="monospaced">
1920 XIM_UNSET_IC_FOCUS (IM library -&gt; IM Server)
1921      2     CARD16     input-method-ID
1922      2     CARD16     input-context-ID
1923 </literallayout>
1924
1925 <para>
1926 <function>XIM_UNSET_IC_FOCUS</function>
1927 is an asynchronous request.
1928 </para>
1929
1930 </sect2>
1931
1932 <sect2 id='Filtering_Events'>
1933 <title>Filtering Events</title>
1934 <para>
1935 Event filtering is mainly provided for BackEnd method to allow input method
1936 to capture X events transparently to clients.
1937 </para>
1938
1939 <para>
1940 X Events are forwarded by
1941 <function>XIM_FORWARD_EVENT</function> message.
1942 This message can be operated both synchronously and asynchronously.
1943 If the requester sets the synchronous flag, the receiver must send
1944 <function>XIM_SYNC_REPLY</function>
1945 message back to the requester when all the data processing is done.
1946 </para>
1947 <para>
1948 Protocol flow of BackEnd model
1949 </para>
1950
1951 <para>
1952 With BackEnd method, the protocol flow can be classified into two
1953 methods in terms of synchronization, depending on the synchronous-eventmask
1954 of <function>XIM_SET_EVENT_MASK</function>
1955 message.  One can be called on-demand-synchronous method and another
1956 can be called as full-synchronous method.
1957 </para>
1958
1959 <para>
1960 In on-demand-synchronous method, the IM library always receives
1961 <function>XIM_FORWARD_EVENT</function>
1962 or
1963 <function>XIM_COMMIT</function>
1964 message as a synchronous request. Also, the IM Server needs to synchronously
1965 process the correspondent reply from the IM library and the following
1966 <function>XIM_FORWARD_EVENT</function>
1967 message sent from the IM library when any of the event causes the IM Server
1968 to send
1969 <function>XIM_FORWARD_EVENT</function>
1970 or
1971 <function>XIM_COMMIT</function>
1972 message to the IM library, so that the input service is consistent.  If the
1973 IM library gets the control back from the application after receiving the
1974 synchronous request, the IM library replies for the synchronous request before
1975 processing any of the events. In this time, the IM Server blocks
1976 <function>XIM_FORWARD_EVENT</function>
1977 message which is sent by the IM library, and handles it after receiving the
1978 reply. However, the IM Server handles the other protocols at any time.
1979 </para>
1980
1981 <para>
1982 In full-synchronous method, the IM library always sends
1983 <function>XIM_FORWARD_EVENT</function>
1984 message to the IM Server as a synchronous request. Therefore, the reply to it
1985 from the IM Server will be put between the
1986 <function>XIM_FORWARD_EVENT</function> message and its
1987 <function>XIM_SYNC_REPLY</function> message.  In case of sending
1988 <function>XIM_FORWARD_EVENT</function> or
1989 <function>XIM_COMMIT</function>
1990 message, the IM Server should set the synchronous flag off. Because the
1991 synchronization can be done by the following
1992 <function>XIM_SYNC_REPLY</function> message.
1993 </para>
1994
1995 <para>
1996 Following chart shows one of the simplest protocol flow which only
1997 deals with keyevents for preediting operation.
1998 </para>
1999
2000 <mediaobject  id="sampleprotocolflow">
2001   <imageobject>
2002     <imagedata  format="SVG"  fileref="sampleprotocolflow1.svg"/>
2003   </imageobject>
2004   <caption>Sample Protocol Flow</caption>
2005 </mediaobject>
2006
2007
2008 <para>
2009 Following chart shows one of the complex protocol flow, which deals
2010 with multiple focus windows and button press event as well as keyevent,
2011 and the focus is moved by the application triggered by both of keyevent
2012 and button press event.
2013 </para>
2014 <mediaobject  id="sampleprotocolflow2">
2015   <imageobject>
2016     <imagedata  format="SVG"  fileref="sampleprotocolflow2.svg"/>
2017   </imageobject>
2018   <caption>Sample Protocol Flow 2</caption>
2019 </mediaobject>
2020
2021 <literallayout class="monospaced">
2022 XIM_FORWARD_EVENT (IM library &lt;--&gt; IM Server)
2023      2     CARD16         input-method-ID
2024      2     CARD16         input-context-ID
2025      2     BITMASK16      flag
2026            #0001          synchronous
2027            #0002          request filtering (*1)
2028            #0004          request lookupstring (*2)
2029      2     CARD16         serial number
2030            XEVENT         X event
2031
2032 (*1)  Indicate the receiver should filter events and possible preedit may be invoked.
2033
2034 (*2)  Indicate the receiver should only do lookup string. The IM Server is expected
2035 to just do a conversion of the key event to the best candidate. This bit may
2036 affect the state of the preedit state (e.g. compose of dead key sequences).
2037 </literallayout>
2038
2039 <para>
2040 XEVENT format is same as the X Protocol event format(xEvent).
2041 As the value of xEvent's sequenceNumber is the bottom of 16 bit of XEvent's
2042 xany.serial, the top of 16 bit is sent by serial number(INT16).
2043 </para>
2044
2045 <para>
2046 <function>XIM_FORWARD_EVENT</function>
2047 message is used for forwarding the events from the IM library to the IM Server
2048 in order for IM to be able to filter the event. On the other hand, this
2049 message is also used for forwarding the events from the IM Server to the IM
2050 library if the event forwarded from the IM library is not filtered.
2051 The IM Server, which receives
2052 <function>XIM_FORWARD_EVENT</function>
2053 message without synchronous bit, should set synchronous bit.
2054 If both "request event filtering" and "request lookupstring" flag are
2055 set, then both filtering and lookup should be done for the same event.
2056 </para>
2057
2058 </sect2>
2059
2060 <sect2 id="Synchronizing_with_the_IM_Server">
2061 <title>Synchronizing with the IM Server</title>
2062
2063 <para>
2064 <function>XIM_SYNC</function>
2065 message requests to synchronize the IM library and the IM Server.
2066 </para>
2067
2068 <literallayout class="monospaced">
2069 XIM_SYNC (IM library &lt;--&gt; IM Server)
2070      2     CARD16     input-method-ID
2071      2     CARD16     input-context-ID
2072 </literallayout>
2073
2074 <para>
2075 This synchronization can be started either on the IM library side or on the
2076 IM Server side.  The side which receives
2077 <function>XIM_SYNC</function>
2078 message should process all XIM requests before replying. The input-context-ID
2079 is necessary to distinguish the IC with which the IM library and the IM
2080 Server are synchronized.
2081 </para>
2082
2083 <literallayout class="monospaced">
2084 XIM_SYNC_REPLY (IM Server &lt;--&gt; IM library)
2085      2     CARD16     input-method-ID
2086      2     CARD16     input-context-ID
2087 </literallayout>
2088
2089
2090
2091 <para>
2092 The side which receives
2093 <function>XIM_FORWARD_EVENT, </function>
2094 <function>XIM_COMMIT</function>
2095 or any other message with synchronous bit, should process all XIM request
2096 before replying, and send
2097 <function>XIM_SYNC_REPLY</function>
2098 message as the reply to the previous message.
2099 </para>
2100
2101 </sect2>
2102
2103 <sect2 id="Sending_a_committed_string">
2104 <title>Sending a committed string</title>
2105 <para>
2106 When the IM Server commits a string, the IM Server sends either the committed
2107 string or list of KeySym, or both, by
2108 <function>XIM_COMMIT</function>
2109 message.
2110 </para>
2111
2112 <literallayout class="monospaced">
2113 XIM_COMMIT (IM Server -&gt; IM library)
2114
2115      2     CARD16          input-method-ID
2116      2     CARD16          input-context-ID
2117      2     BITMASK16       flag
2118            #0001           synchronous
2119            #0002           XLookupChars
2120            #0004           XLookupKeySym
2121            #0006           XLookupBoth = XLookupChars | XLookupKeySym
2122 </literallayout>
2123
2124 <para>
2125 If flag is XLookupKeySym, the arguments continue as follows:
2126 </para>
2127
2128 <literallayout class="monospaced">
2129      2                unused
2130      4     KEYSYM     KeySym
2131 </literallayout>
2132
2133 <para>
2134 If flag is XLookupChars, the arguments continue as follows
2135 </para>
2136
2137 <literallayout class="monospaced">
2138      2     m              byte length of committed string
2139      m     LISTofBYTE     committed string
2140      p                    unused, p = Pad(m)
2141 </literallayout>
2142
2143 <para>
2144 If flag is XLookupBoth, the arguments continue as follows
2145 </para>
2146
2147 <literallayout class="monospaced">
2148      2                    unused
2149      4     KEYSYM         KeySym
2150      2     n              byte length of committed string
2151      n     LISTofBYTE     committed string
2152      p                    unused, p = Pad(2+n)
2153 </literallayout>
2154
2155 <para>
2156 The IM Server which receives
2157 <function>XIM_COMMIT</function>
2158 message without synchronous bit should set synchronous bit.
2159 </para>
2160
2161 </sect2>
2162
2163 <sect2 id="Reset_IC">
2164 <title>Reset IC</title>
2165 <para>
2166 <function>XIM_RESET_IC</function>
2167 message requests to reset the status of IC in the IM Server.
2168 </para>
2169
2170 <literallayout class="monospaced">
2171 XIM_RESET_IC (IM library -&gt; IM Server)
2172      2     CARD16     input-method-ID
2173      2     CARD16     input-context-ID
2174 </literallayout>
2175
2176
2177 <para>
2178 <function>XIM_RESET_IC</function>
2179 is a synchronous request. The IM library should wait until receiving either an
2180 <function>XIM_RESET_IC_REPLY</function> packet or an
2181 <function>XIM_ERROR</function> packet.
2182 </para>
2183
2184 <literallayout class="monospaced">
2185 XIM_RESET_IC_REPLY (IM Server -&gt; IM library)
2186
2187      2     CARD16         input-method-ID
2188      2     CARD16         input-context-ID
2189      2     n              byte length of preedit string
2190      n     LISTofBYTE     preedit string
2191      p                    unused, p = Pad(2+n)
2192 </literallayout>
2193
2194 <para>
2195 <function>XIM_RESET_IC_REPLY </function>
2196 message returns the input-context-ID to distinguish replies from multiple ICs.
2197 </para>
2198
2199 </sect2>
2200 <sect2 id="Callbacks">
2201 <title>Callbacks</title>
2202 <para>
2203 If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGeometryCallback
2204 may be used, and if XIMPreeditCallback and/or XIMStatusCallback are set,
2205 corresponding callbacks may be used.
2206 </para>
2207
2208 <para>
2209 Any callback request may be sent from an IM Server to an IM client
2210 asynchronously in response to any request previously sent by the IM client
2211 to the IM Server.
2212 </para>
2213
2214 <para>
2215 When an IM Server needs to send a callback request synchronously with
2216 the request previously sent by an IM client, the IM Server sends it
2217 before replying to the previous request.
2218 </para>
2219
2220 <sect3 id="Negotiating_geometry">
2221 <title>Negotiating geometry</title>
2222 <para>
2223 The IM Server sends
2224 <function>XIM_GEOMETRY </function>
2225 message to start geometry negotiation, if XIMStyle has XIMPreeditArea or
2226 XIMStatusArea set.
2227 </para>
2228
2229
2230 <literallayout class="monospaced">
2231 XIM_GEOMETRY (IM Server -&gt; IM library)
2232
2233      2     CARD16     input-method-ID
2234      2     CARD16     input-context-ID
2235 </literallayout>
2236
2237 <para>
2238 There is always a single Focus Window, even if some input fields have only
2239 one IC.
2240 </para>
2241
2242 </sect3>
2243
2244 <sect3 id="Converting_a_string">
2245 <title>Converting a string</title>
2246
2247 <literallayout class="monospaced">
2248 XIM_STR_CONVERSION (IM Server -&gt; IM library)
2249
2250      2     CARD16     input-method-ID
2251      2     CARD16     input-context-ID
2252      2     CARD16     XIMStringConversionPosition
2253      2                unused
2254      4     CARD32     XIMCaretDirection
2255            #0         XIMForwardChar
2256            #1         XIMBackwardChar
2257            #2         XIMForwardWord
2258            #3         XIMBackwardWord
2259            #4         XIMCaretUp
2260            #5         XIMCaretDown
2261            #6         XIMNextLine
2262            #7         XIMCPreviousLine
2263            #8         XIMLineStart
2264            #9         XIMLineEnd
2265            #10        XIMAbsolutePosition
2266            #11        XIMDontChange
2267      2     CARD16     factor
2268      2     CARD16     XIMStringConversionOperation
2269            #0001      XIMStringConversionSubstitution
2270            #0002      XIMStringConversionRetrieval
2271      2     INT16      byte length to multiply the XIMStringConversionType
2272 </literallayout>
2273
2274 <para>
2275 <function>XIM_STR_CONVERSION </function>
2276 message may be used to start the string conversion from the IM Server.
2277 </para>
2278
2279 <literallayout class="monospaced">
2280 XIM_STR_CONVERSION_REPLY (IM library -&gt; IM Server)
2281
2282      2     CARD16             input-method-ID
2283      2     CARD16             input-context-ID
2284      4     CARD32             XIMStringConversionFeedback
2285            XIMSTRCONVTEXT     XIMStringConversionText
2286 </literallayout>
2287
2288 <para>
2289 <function>XIM_STR_CONVERSION_REPLY </function>
2290 message returns the string to be converted and the feedback information array.
2291 </para>
2292 </sect3>
2293
2294 <sect3 id="Preedit_Callbacks">
2295 <title>Preedit Callbacks</title>
2296
2297 <para>
2298 The IM Server sends
2299 <function>XIM_PREEDIT_START </function>
2300 message to call the XIMPreeditStartCallback function.
2301 </para>
2302
2303 <literallayout class="monospaced">
2304 XIM_PREEDIT_START (IM Server -&gt; IM library)
2305
2306      2     CARD16     input-method-ID
2307      2     CARD16     input-context-ID
2308 </literallayout>
2309
2310 <para>
2311 The reply to this message must be sent synchronously. The reply forwards
2312 the return value from the callback function to the IM Server.
2313 </para>
2314
2315 <literallayout class="monospaced">
2316 XIM_PREEDIT_START_REPLY (IM library -&gt; IM Server)
2317
2318      2     CARD16     input-method-ID
2319      2     CARD16     input-context-ID
2320      4     INT32     return value
2321 </literallayout>
2322
2323 <para>
2324 <function>XIM_PREEDIT_START_REPLY</function>
2325 message returns the input-context-ID to distinguish replies from multiple
2326 IC's.  The return value contains the return value of the function
2327 XIMPreeditStartCallback.
2328 </para>
2329
2330 <para>
2331 The IM Server sends
2332 <function>XIM_PREEDIT_DRAW </function>
2333 message to call the XIMPreeditDrawCallback function.
2334 </para>
2335
2336 <literallayout class="monospaced">
2337 XIM_PREEDIT_DRAW (IM Server -&gt; IM library)
2338
2339      2     CARD16                input-method-ID
2340      2     CARD16                input-context-ID
2341      4     INT32                 caret
2342      4     INT32                 chg_first
2343      4     INT32                 chg_length
2344      4     BITMASK32             status
2345            #x0000001             no string
2346            #x0000002             no feedback
2347      2     n                     length of preedit string
2348      n     STRING8               preedit string
2349      p                           unused, p = Pad(2+n)
2350      2     m                     byte length of feedback array
2351      2                           unused
2352      m     LISTofXIMFEEDBACK     feedback array
2353 </literallayout>
2354
2355 <para>
2356 The fields "caret", "chg_first" and "chg_length" correspond to the
2357 fields of XIMPreeditDrawCallbackStruct.
2358 When the "no string" bit of the status field is set, the text field of
2359 XIMPreeditDrawCallbackStruct is NULL.
2360 When the "no feedback" bit of the status field is set, the text feedback
2361 field of XIMPreeditDrawCallbackStruct is NULL.
2362 When the above bits are not set, "preedit string" contains the preedit
2363 string to be displayed, and the feedback array contains feedback information.
2364 </para>
2365
2366 <para>
2367 The IM Server sends
2368 <function>XIM_PREEDIT_CARET</function>
2369 message to call the PreeditCaretCallback function.
2370 </para>
2371
2372 <literallayout class="monospaced">
2373 XIM_PREEDIT_CARET (IM Server -&gt; IM library)
2374
2375      2     CARD16     input-method-ID
2376      2     CARD16     input-context-ID
2377      4     INT32      position
2378      4     CARD32     direction
2379            #0         XIMForwardChar
2380            #1         XIMBackwardChar
2381            #2         XIMForwardWord
2382            #3         XIMBackwardWord
2383            #4         XIMCaretUp
2384            #5         XIMCaretDown
2385            #6         XIMNextLine
2386            #7         XIMCPreviousLine
2387            #8         XIMLineStart
2388            #9         XIMLineEnd
2389            #10        XIMAbsolutePosition
2390            #11        XIMDontChange
2391      4     CARD32     style
2392            #0         XIMInvisible
2393            #1         XIMCPrimary
2394            #2         XIMSecondary
2395 </literallayout>
2396
2397 <para>
2398 Each entry corresponds to a field of XIMPreeditCaretCallbackStruct.
2399 Since this callback sets the caret position, its reply must be sent
2400 synchronously.
2401 </para>
2402
2403 <literallayout class="monospaced">
2404 XIM_PREEDIT_CARET_REPLY (IM library -&gt; IM Server)
2405
2406      2     CARD16     input-method-ID
2407      2     CARD16     input-context-ID
2408      4     CARD32     position
2409 </literallayout>
2410
2411 <para>
2412 The position is the value returned by the callback function after it
2413 has been called.
2414 </para>
2415
2416 <para>
2417 The IM Server sends
2418 <function>XIM_PREEDIT_DONE </function>
2419 message to call the XIMPreeditDoneCallback function.
2420 </para>
2421
2422 <literallayout class="monospaced">
2423 XIM_PREEDIT_DONE (IM Server -&gt; IM library)
2424
2425      2     CARD16     input-method-ID
2426      2     CARD16     input-context-ID
2427 </literallayout>
2428
2429 </sect3>
2430
2431 <sect3 id="Preedit_state_notify">
2432 <title>Preedit state notify</title>
2433
2434 <literallayout class="monospaced">
2435 XIM_PREEDITSTATE (IM Server -&gt; IM Library)
2436      2     CARD16        input-method-ID
2437      2     CARD16        input-context-ID
2438      4     BITMASK32     XIMPreeditState
2439            #x0000000     XIMPreeditUnknown
2440            #x0000001     XIMPreeditEnable
2441            #x0000002     XIMPreeditDisable
2442 </literallayout>
2443
2444 <para>
2445 <function>XIM_PREEDITSTATE</function>
2446 message is used to call the XIMPreeditStateNotifyCallback function.
2447 </para>
2448
2449 </sect3>
2450
2451 <sect3 id="Status_Callbacks">
2452 <title>Status Callbacks</title>
2453
2454 <para>
2455 The IM Server sends
2456 <function>XIM_STATUS_START </function>
2457 message to call the XIMStatusStartCallback function.
2458 </para>
2459
2460 <literallayout class="monospaced">
2461 XIM_STATUS_START (IM Server -&gt; IM library)
2462
2463      2     CARD16     input-method-ID
2464      2     CARD16     input-context-ID
2465 </literallayout>
2466
2467 <para>
2468 The IM Server sends
2469 <function>XIM_STATUS_DRAW </function>
2470 message to call the XIMStatusDrawCallback function.
2471 </para>
2472
2473 <literallayout class="monospaced">
2474 XIM_STATUS_DRAW (IM Server -&gt; IM library)
2475
2476      2     CARD16     input-method-ID
2477      2     CARD16     input-context-ID
2478      4     CARD32     type
2479            #0         XIMTextType
2480            #1         XIMBitmapType
2481 </literallayout>
2482
2483 <para>
2484 If type is XIMTextType, the arguments continue as follows.
2485 </para>
2486
2487 <literallayout class="monospaced">
2488      4     BITMASK32            status
2489            #x0000001            no string
2490            #x0000002            no feedback
2491      2     n                    length of status string
2492      n     STRING8              status string
2493      p                          unused, p = Pad(2+n)
2494      2     m                    byte length of feedback array
2495      2                          unused
2496      m     LISTofXIMFEEDBACK    feedback array
2497 </literallayout>
2498
2499 <para>
2500 If type is XIMBitmapType, the arguments continue as follows.
2501 </para>
2502
2503 <literallayout class="monospaced">
2504      4     PIXMAP     pixmap data
2505 </literallayout>
2506
2507 <para>
2508 The field "type" corresponds to the field in XIMStatusDrawCallbackStruct.
2509 </para>
2510
2511 <para>
2512 The IM Server sends
2513 <function>XIM_STATUS_DONE </function>
2514 message to call the XIMStatusDoneCallback function.
2515 </para>
2516
2517 <literallayout class="monospaced">
2518 XIM_STATUS_DONE (IM Server -&gt; IM library)
2519
2520      2     CARD16     input-method-ID
2521      2     CARD16     input-context-ID
2522 </literallayout>
2523
2524 </sect3>
2525 </sect2>
2526 </sect1>
2527
2528 <sect1 id="Acknowledgements">
2529 <title>Acknowledgements</title>
2530 <para>
2531 This document represents the culmination of several years of debate and
2532 experiments done under the auspices of the MIT X Consortium i18n working
2533 group.  Although this was a group effort, the author remains responsible
2534 for any errors or omissions.
2535 </para>
2536
2537 <para>
2538 We would like to thank to all members of this group.
2539 And we would like to make special thanks to the following people
2540 (in alphabetical order) for their participation in the IM Protocol
2541 design,
2542 Hector Chan, Takashi Fujiwara, Yoshio Horiuchi, Makoto Inada,
2543 Hiromu Inukai, Mickael Kung, Seiji Kuwari, Franky Ling, Hiroyuki Machida,
2544 Hiroyuki Miyamoto, Frank Rojas, Bob Scheifler, Makiko Shimamura,
2545 Shoji Sugiyama, Hidetoshi Tajima, Masaki Takeuchi, Makoto Wakamatsu,
2546 Masaki Wakao, Nobuyuki Tanaka, Shigeru Yamada, Katsuhisa Yano, Jinsoo Yoon.
2547 </para>
2548
2549 </sect1>
2550
2551 <bibliography>
2552 <title>References</title>
2553 <biblioentry>
2554   <title>X Window System Protocol Version 11</title>
2555   <author><firstname>Robert W.</firstname><surname>Scheifler</surname></author>
2556 </biblioentry>
2557
2558 <biblioentry>
2559   <title>Xlib - C Language X Interface"</title>
2560   <author><firstname>Robert W.</firstname><surname>Scheifler</surname></author>
2561 </biblioentry>
2562 </bibliography>
2563
2564 <appendix id="common_extensions">
2565 <title>Common Extensions</title>
2566 <para>
2567 Extension opcodes and packet names (e.g.
2568 <function>XIM_EXT_SET_EVENT_MASK</function>
2569 ) for additional extensions may be registered with X Consortium.
2570 The following is a commonly well-known extended packet.
2571 </para>
2572
2573 <para>
2574 (1) Extension to manipulate the event handling\fP
2575 </para>
2576
2577 <para>
2578 <!-- .LP -->
2579 <function>XIM_EXT_SET_EVENT_MASK </function>
2580 message specifies the set of event masks that the IM library should manipulate.
2581 </para>
2582
2583 <literallayout class="monospaced">
2584 XIM_EXT_SET_EVENT_MASK (IM Server -&gt; IM library)
2585
2586      2     CARD16        input-method-ID
2587      2     CARD16        input-context-ID
2588      4     EVENTMASK     filter-event-mask (*1)
2589      4     EVENTMASK     intercept-event-mask (*2)
2590      4     EVENTMASK     select-event-mask (*3)
2591      4     EVENTMASK     forward-event-mask (*4)
2592      4     EVENTMASK     synchronous-event-mask (*5)
2593
2594      (*1) Specify the events to be neglected by the IM library via XFilterEvent.
2595      (*2) Specify the events to be deselected by the IM library with XSelectInput.
2596      (*3) Specify the events to be selected by the IM library with XSelectInput.
2597      (*4) Specify all the events to be forwarded to the IM Server by the IM library.
2598      (*5) Specify the events to be forwarded with synchronous flag on by the IM library.
2599 </literallayout>
2600
2601 <para>
2602 <!-- .LP -->
2603 The IM library must reply
2604 <function>XIM_SYNC_REPLY</function>
2605 message to the IM Server. This request is valid after the ic is created.
2606 </para>
2607
2608 <para>
2609 (2) Extension for improvement of performance.
2610 </para>
2611 <para>
2612 The following requests may be used for improvement of performance.
2613 </para>
2614
2615 <para>
2616 <function>XIM_EXT_FORWARD_KEYEVENT</function>
2617 message may be used instead of
2618 <function>XIM_FORWARD_EVENT</function>
2619 message.
2620 </para>
2621
2622 <literallayout class="monospaced">
2623 XIM_EXT_FORWARD_KEYEVENT (IM Server &lt;--&gt; IM library)
2624      2     CARD16     input-method-ID
2625      2     CARD16     input-context-ID
2626      2     BITMASK16     flag
2627           #0001     synchronous
2628      2     CARD16     sequence number
2629      1     BYTE     xEvent.u.u.type
2630      1     BYTE     keycode
2631      2     CARD16     state
2632      4     CARD32     time
2633      4     CARD32     window
2634 </literallayout>
2635
2636 <para>
2637 <function>XIM_EXT_MOVE</function>
2638 message may be used to change the spot location instead of
2639 <function></function>
2640 XIM_SET_IC_VALUES
2641 message.
2642 It is effective only if the client specified XIMPreeditPosition.
2643 </para>
2644
2645
2646 <literallayout class="monospaced">
2647 XIM_EXT_MOVE (IM library -&gt; IM Server)
2648
2649      2     CARD16     input-method-ID
2650      2     CARD16     input-context-ID
2651      2     INT16     X
2652      2     INT16     Y
2653 </literallayout>
2654
2655 <para>
2656 <function>XIM_EXT_MOVE</function>
2657 message is a asynchronous request.
2658 </para>
2659
2660 </appendix>
2661 <appendix id="transport_list">
2662 <title>Transport List</title>
2663
2664 <para>
2665 The list of transport specific IM Server address format registered
2666 </para>
2667
2668 <para>
2669 The following format represents the ATOM contained in
2670 <function>XIM_SERVERS</function>
2671 property and the string returned from the request converting
2672 selection target LOCALES and TRANSPORT.
2673 </para>
2674 <literallayout class="monospaced">
2675      "{<emphasis remap='I'>category</emphasis>=[<emphasis remap='I'>value</emphasis>,...]}..."
2676 </literallayout>
2677 <para>
2678 The following categories are currently registered.
2679 </para>
2680
2681 <literallayout class="monospaced">
2682 <function>server</function>;: IM Server name (used for XIM_SERVERS)
2683 <function>locale</function>;: XPG4 locale name (LOCALES)
2684 <function>transport</function>;: transport-specific name (TRANSPORT)
2685 </literallayout>
2686
2687 <para>
2688 The preregistered formats for transport-specific names are as follows:
2689 </para>
2690
2691 <para>
2692 <function>TCP/IP Names</function>
2693 </para>
2694
2695 <para>
2696 The following syntax should be used for system internal domain names:
2697 </para>
2698 <literallayout class="monospaced">
2699 &lt;<emphasis remap='I'>local name</emphasis>&gt;  ::= "local/"&lt;<emphasis remap='I'>hostname</emphasis>&gt;":"&lt;<emphasis remap='I'>pathname</emphasis>&gt;
2700 </literallayout>
2701 <para>
2702 Where &lt;<emphasis remap='I'>pathname</emphasis>&gt; is a path name of socket address.
2703 </para>
2704
2705 <para>
2706 IM Server's name should be set to &lt;<emphasis remap='I'>pathname</emphasis>&gt; to run multiple IM Server
2707 at the same time
2708 </para>
2709
2710 <para>
2711 The following syntax should be used for Internet domain names:
2712 </para>
2713 <literallayout class="monospaced">
2714 &lt;<emphasis remap='I'>TCP name</emphasis>&gt;  ::=  "tcp/"&lt;<emphasis remap='I'>hostname</emphasis>&gt;":"&lt;<emphasis remap='I'>ipportnumber</emphasis>&gt;
2715 </literallayout>
2716 <para>
2717 where &lt;<emphasis remap='I'>hostname</emphasis>&gt; is either symbolic (such as expo.lcs.mit.edu) or
2718 numeric decimal (such as 18.30.0.212).  The &lt;<emphasis remap='I'>ipportnumber</emphasis>&gt; is the
2719 port on which the IM Server is listening for connections.
2720 For example:
2721 </para>
2722 <literallayout class="monospaced">
2723 tcp/expo.lcs.mit.edu:8012
2724 tcp/18.30.0.212:7890
2725 </literallayout>
2726
2727 <para>
2728 <function>DECnet Names</function>
2729 </para>
2730
2731 <para>
2732 The following syntax should be used for DECnet names:
2733 </para>
2734 <literallayout class="monospaced">
2735 &lt;<emphasis remap='I'>DECnet name</emphasis>&gt;  ::=  "decnet/"&lt;<emphasis remap='I'>nodename</emphasis>&gt;"::IMSERVER$"&lt;<emphasis remap='I'>objname</emphasis>&gt;
2736 </literallayout>
2737 <para>
2738 where &lt;<emphasis remap='I'>nodename</emphasis>&gt; is either
2739 symbolic (such as SRVNOD) or the numeric
2740 decimal form of the DECnet address (such as 44.70).
2741 The &lt;<emphasis remap='I'>objname</emphasis>&gt;
2742 is normal, case-insensitive DECnet object name. For example:
2743 </para>
2744
2745 <literallayout class="monospaced">
2746 DECNET/SRVNOD::IMSERVER$DEFAULT
2747 decnet/44.70::IMSERVER$other
2748 </literallayout>
2749
2750 <para>
2751 <function>X Names</function>
2752 </para>
2753
2754 <para>
2755 The following syntax should be used for X names:
2756 </para>
2757 <literallayout class="monospaced">
2758 &lt;<emphasis remap='I'>X name</emphasis>&gt;  ::=  "X/"
2759 </literallayout>
2760
2761 <para>
2762 If a given category has multiple values, the value is evaluated in order of
2763 setting.
2764 </para>
2765
2766 </appendix>
2767 <appendix id="protocol_number">
2768 <title>Protocol Number</title>
2769
2770 <para>
2771 <function>Major Protocol number</function>
2772 </para>
2773
2774 <literallayout class="monospaced">
2775 XIM_CONNECT                                  #001
2776 XIM_CONNECT_REPLY                            #002
2777 XIM_DISCONNECT                               #003
2778 XIM_DISCONNECT_REPLY                         #004
2779
2780 XIM_AUTH_REQUIRED                            #010
2781 XIM_AUTH_REPLY                               #011
2782 XIM_AUTH_NEXT                                #012
2783 XIM_AUTH_SETUP                               #013
2784 XIM_AUTH_NG                                  #014
2785
2786 XIM_ERROR                                    #020
2787
2788 XIM_OPEN                                     #030
2789 XIM_OPEN_REPLY                               #031
2790 XIM_CLOSE                                    #032
2791 XIM_CLOSE_REPLY                              #033
2792 XIM_REGISTER_TRIGGERKEYS                     #034
2793 XIM_TRIGGER_NOTIFY                           #035
2794 XIM_TRIGGER_NOTIFY_REPLY                     #036
2795 XIM_SET_EVENT_MASK                           #037
2796 XIM_ENCODING_NEGOTIATION                     #038
2797 XIM_ENCODING_NEGOTIATION_REPLY               #039
2798 XIM_QUERY_EXTENSION                          #040
2799 XIM_QUERY_EXTENSION_REPLY                    #041
2800 XIM_SET_IM_VALUES                            #042
2801 XIM_SET_IM_VALUES_REPLY                      #043
2802 XIM_GET_IM_VALUES                            #044
2803 XIM_GET_IM_VALUES_REPLY                      #045
2804
2805 XIM_CREATE_IC                                #050
2806 XIM_CREATE_IC_REPLY                          #051
2807 XIM_DESTROY_IC                               #052
2808 XIM_DESTROY_IC_REPLY                         #053
2809 XIM_SET_IC_VALUES                            #054
2810 XIM_SET_IC_VALUES_REPLY                      #055
2811 XIM_GET_IC_VALUES                            #056
2812 XIM_GET_IC_VALUES_REPLY                      #057
2813 XIM_SET_IC_FOCUS                             #058
2814 XIM_UNSET_IC_FOCUS                           #059
2815 XIM_FORWARD_EVENT                            #060
2816 XIM_SYNC                                     #061
2817 XIM_SYNC_REPLY                               #062
2818 XIM_COMMIT                                   #063
2819 XIM_RESET_IC                                 #064
2820 XIM_RESET_IC_REPLY                           #065
2821
2822 XIM_GEOMETRY                                 #070
2823 XIM_STR_CONVERSION                           #071
2824 XIM_STR_CONVERSION_REPLY                     #072
2825 XIM_PREEDIT_START                            #073
2826 XIM_PREEDIT_START_REPLY                      #074
2827 XIM_PREEDIT_DRAW                             #075
2828 XIM_PREEDIT_CARET                            #076
2829 XIM_PREEDIT_CARET_REPLY                      #077
2830 XIM_PREEDIT_DONE                             #078
2831 XIM_STATUS_START                             #079
2832 XIM_STATUS_DRAW                              #080
2833 XIM_STATUS_DONE                              #081
2834 XIM_PREEDITSTATE                             #082
2835
2836 (*) The IM Server's extension protocol number should be more than #128.
2837 </literallayout>
2838 </appendix>
2839
2840 <appendix id="implementation_tips">
2841
2842 <title>Implementation Tips</title>
2843 <para>
2844 (1) FrontEnd Method
2845 </para>
2846
2847 <para>
2848 FrontEnd method is recognized as a performance acceleration by the
2849 trade off of the variety of the reliability.
2850 </para>
2851
2852 <para>
2853 In order to use the FrontEnd method, the IM library must query the IM
2854 Server to see if the FrontEnd extension is available.  The query is
2855 made by using the
2856 <function>XIM_QUERY_EXTENSION</function>
2857 message. The IM Server may send
2858 <function>XIM_EXT_SET_EVENT_MASK</function>
2859 message with intercept-event-mask, forward-event-mask, and
2860 synchronous-event-mask values set after replying
2861 <function>XIM_QUERY_EXTENSION_REPLY</function>
2862 message.
2863 </para>
2864
2865 <para>
2866 FrontEnd method can be implemented in a couple of ways depending on
2867 how the IM Server utilize
2868 <function>XIM_EXT_SET_EVENT_MASK</function>
2869 message.
2870 </para>
2871
2872 <para>
2873 One approach is to update both of the input mask and the filter-event-mask
2874 depending on the preeidting state. The sample protocol sequence using the
2875 static event flow is as follows:
2876 </para>
2877
2878 <mediaobject  id="staticflow">
2879   <imageobject>
2880     <imagedata  scale="75" format="SVG"  fileref="staticflow.svg"/>
2881   </imageobject>
2882   <caption>The flow of events</caption>
2883 </mediaobject>
2884
2885 <para>
2886 To pursuit a maximum performance regardless of the preediting mode,
2887 the IM Server may use the dynamic event flow with the following
2888 sample protocol sequence.
2889 </para>
2890
2891 <mediaobject  id="dynamicflow">
2892   <imageobject>
2893     <imagedata  scale="75" format="SVG"  fileref="dynamicflow.svg"/>
2894   </imageobject>
2895   <caption>The flow of events</caption>
2896 </mediaobject>
2897
2898 <para>
2899 This method can reduce the XIM protocol traffic dramatically
2900 by updating intercept-event-mask and select-event-mask accordingly.
2901 The tradeoff of this performance improvement is that the key
2902 events may be lost or disordered in some particular situation, such as
2903 when the user types the keyboard in following sequence really fast:
2904 </para>
2905
2906 <para>
2907 &lt;preediting on key&gt;"some strings"&lt;preediting off
2908 key&gt;"another string"
2909 </para>
2910
2911 <para>
2912 Since this method requires the input mask updates to the both the IM Server
2913 and Xlib when turning on and off the preediting, and there is a time lag
2914 till the requests take effect when two client issues the input mask updates
2915 simultaneously.
2916 </para>
2917
2918 <para>
2919 Another approach of the FrontEnd method is to update the filter-event-mask
2920 depending on the preediting state and not to update the input mask.
2921 The IM Server must register both of the preediting on key list and off key
2922 list by
2923 <function>XIM_REGISTER_TRIGGERKEYS</function>
2924 message.
2925 In this method, Both the IM Server and the IM client select the same
2926 events on the same client's window, so that the events are delivered
2927 to both of the IM Server and the client. The preediting on and off
2928 states are expressed by whether the key events are filtered or not.
2929 The sample protocol sequence are as follows:
2930 </para>
2931
2932 <para>
2933 &lt;&lt;Using static event flow&gt;&gt;
2934 </para>
2935
2936 <mediaobject  id="staticflowsampleseq">
2937   <imageobject>
2938     <imagedata  scale="75" format="SVG"  fileref="staticflowsampleseq.svg"/>
2939   </imageobject>
2940   <caption>The flow of events</caption>
2941 </mediaobject>
2942
2943 <para>
2944 &lt;&lt;Using the dynamic event flow&gt;&gt;
2945 </para>
2946
2947 <mediaobject  id="dynamicflowsampleseq">
2948   <imageobject>
2949     <imagedata  scale="75" format="SVG"  fileref="dynamicflowsampleseq.svg"/>
2950   </imageobject>
2951   <caption>The flow of events</caption>
2952 </mediaobject>
2953
2954 <para>
2955 This method does not have the problem of the time lag when going across
2956 the preediting on and off mode, however, the amount of the performance
2957 acceleration is not as good as the method described above.
2958 </para>
2959
2960 <para>
2961 In general, the FrontEnd method requires some synchronization to some
2962 of the X protocols, such as the ChangeWindowAttribute protocol for the
2963 event mask change or the GrabKey protocol, since it relies on the X's
2964 principal event dispatching mechanism. Any X protocol bindings do not
2965 consider the synchronization might cause some mis-synchronization
2966 between the IM clients and the IM Server.
2967 </para>
2968
2969 <para>
2970 (2) Transport Layer
2971 </para>
2972
2973 <para>
2974 The Xlib XIM implementation is layered into three functions, a protocol
2975 layer, an interface layer and a transport layer. The purpose of this
2976 layering is to make the protocol independent of transport implementation.
2977 Each function of these layers are:
2978 </para>
2979
2980 <variablelist>
2981   <varlistentry>
2982     <term>The protocol layer</term>
2983     <listitem>
2984       <para>
2985 implements overall function of XIM and calls the interface layer
2986 functions when it needs to communicate to IM Server.
2987       </para>
2988     </listitem>
2989   </varlistentry>
2990   <varlistentry>
2991     <term>The interface layer</term>
2992     <listitem>
2993       <para>
2994 separates the implementation of the transport layer from the protocol
2995 layer, in other words, it provides implementation independent hook for
2996 the transport layer functions.
2997       </para>
2998     </listitem>
2999   </varlistentry>
3000   <varlistentry>
3001     <term>The transport layer</term>
3002     <listitem>
3003       <para>
3004 handles actual data communication with IM Server. It is done by a set
3005 of several functions named transporters.
3006       </para>
3007     </listitem>
3008   </varlistentry>
3009 </variablelist>
3010
3011 <para>
3012 The interface layer and the transport layer make various communication
3013 channels usable such as X Protocol, TCP/IP, DECnet or STREAM.
3014 The following is a sample implementation for the transporter using
3015 the X connection.
3016 Refer to "xtrans" for the transporter using Socket Transport. <!-- xref ?-->
3017 </para>
3018
3019 <para>
3020 At the beginning of the X Transport connection for the XIM transport
3021 mechanism, two different windows must be created either in an Xlib XIM
3022 or in an IM Server, with which the Xlib and the IM Server exchange the
3023 XIM transports by using the ClientMessage events and Window Properties.
3024 In the following, the window created by the Xlib is referred as the
3025 "client communication window", and on the other hand, the window created
3026 by the IM Server is referred as the "IMS communication window".
3027 </para>
3028
3029 <para>
3030 Connection
3031 </para>
3032
3033 <para>
3034 In order to establish a connection, a communication window is created.
3035 A ClientMessage in the following event's format is sent to the owner
3036 window of XIM_SERVER selection, which the IM Server has created.
3037 </para>
3038
3039 <para>
3040 Refer to "The Input Method Protocol" for the XIM_SERVER atom. <!-- xref -->
3041 </para>
3042
3043 <table frame="topbot" id="clientmessage_sent_to_the_ims_window">
3044   <?dbfo keep-together="always" ?>
3045   <title>The ClientMessage sent to the IMS window.</title>
3046   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3047   <colspec colname="col1" colwidth="1.0*"/>
3048   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3049   <colspec colname="col3" colwidth="3.5*"/>
3050   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3051   <thead>
3052     <row rowsep='1'>
3053       <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
3054       <entry>Contents</entry>
3055     </row>
3056   </thead>
3057   <tbody>
3058     <row>
3059       <entry>int</entry>
3060       <entry>type</entry>
3061       <entry>ClientMessage</entry>
3062     </row>
3063     <row>
3064       <entry>u_long</entry>
3065       <entry>serial</entry>
3066       <entry>Set by the X Window System</entry>
3067     </row>
3068     <row>
3069       <entry>Bool</entry>
3070       <entry>send_event</entry>
3071       <entry>Set by the X Window System</entry>
3072     </row>
3073     <row>
3074       <entry>Display</entry>
3075       <entry>*display</entry>
3076       <entry>The display to which connects</entry>
3077     </row>
3078     <row>
3079       <entry>Window</entry>
3080       <entry>window</entry>
3081       <entry>IMS Window ID</entry>
3082     </row>
3083     <row>
3084       <entry>Atom</entry>
3085       <entry>message_type</entry>
3086       <entry>XInternAtom(display, "_XIM_XCONNECT", False)</entry>
3087     </row>
3088     <row>
3089       <entry>int</entry>
3090       <entry>format</entry>
3091       <entry>32</entry>
3092     </row>
3093     <row>
3094       <entry>long</entry>
3095       <entry>data.l[0]</entry>
3096       <entry>client communication window ID</entry>
3097     </row>
3098     <row>
3099       <entry>long</entry>
3100       <entry>data.l[1]</entry>
3101       <entry>client-major-transport-version (*1)</entry>
3102     </row>
3103     <row>
3104       <entry>long</entry>
3105       <entry>data.l[2]</entry>
3106       <entry>client-major-transport-version (*1)</entry>
3107     </row>
3108   </tbody>
3109   </tgroup>
3110 </table>
3111
3112 <para>
3113 In order to establish the connection (to notify the IM Server communication
3114 window), the IM Server sends a ClientMessage in the following event's
3115 format to the client communication window.
3116 </para>
3117
3118 <table frame="topbot" id="clientmessage_sent_by_the_im_server">
3119   <?dbfo keep-together="always" ?>
3120   <title>The ClientMessage sent by the IM Server.</title>
3121   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3122   <colspec colname="col1" colwidth="1.0*"/>
3123   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3124   <colspec colname="col3" colwidth="3.5*"/>
3125   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3126   <thead>
3127     <row rowsep='1'>
3128       <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
3129       <entry>Contents</entry>
3130     </row>
3131   </thead>
3132   <tbody>
3133     <row>
3134       <entry>int</entry>
3135       <entry>type</entry>
3136       <entry>ClientMessage</entry>
3137     </row>
3138     <row>
3139       <entry>u_long</entry>
3140       <entry>serial</entry>
3141       <entry>Set by the X Window System</entry>
3142     </row>
3143     <row>
3144       <entry>Bool</entry>
3145       <entry>send_event</entry>
3146       <entry>Set by the X Window System</entry>
3147     </row>
3148     <row>
3149       <entry>Display</entry>
3150       <entry>*display</entry>
3151       <entry>The display to which connects</entry>
3152     </row>
3153     <row>
3154       <entry>Window</entry>
3155       <entry>window</entry>
3156       <entry>client communication window ID</entry>
3157     </row>
3158     <row>
3159       <entry>Atom</entry>
3160       <entry>message_type</entry>
3161       <entry>XInternAtom(display, "_XIM_XCONNECT", False)</entry>
3162     </row>
3163     <row>
3164       <entry>int</entry>
3165       <entry>format</entry>
3166       <entry>32</entry>
3167     </row>
3168     <row>
3169       <entry>long</entry>
3170       <entry>data.l[0]</entry>
3171       <entry>IMS communication window ID</entry>
3172     </row>
3173     <row>
3174       <entry>long</entry>
3175       <entry>data.l[1]</entry>
3176       <entry>server-major-transport-version (*1)</entry>
3177     </row>
3178     <row>
3179       <entry>long</entry>
3180       <entry>data.l[2]</entry>
3181       <entry>server-minor-transport-version (*1)</entry>
3182     </row>
3183     <row>
3184       <entry>long</entry>
3185       <entry>data.l[3]</entry>
3186       <entry>dividing size between ClientMessage and Property (*2)</entry>
3187     </row>
3188   </tbody>
3189   </tgroup>
3190 </table>
3191
3192 <para>
3193 (*1) major/minor-transport-version
3194 </para>
3195 <para>
3196 The read/write method is decided by the combination of
3197 major/minor-transport-version, as follows:
3198 </para>
3199
3200
3201 <table frame="all" id="readwrite_method_and_the_majorminor_transport_version">
3202   <?dbfo keep-together="always" ?>
3203   <title>The read/write method and the major/minor-transport-version</title>
3204   <tgroup cols="3" align='left' colsep='1' rowsep='1'>
3205   <colspec colname="col1" colwidth="1.0*"/>
3206   <colspec colname="col2" colwidth="1.0*"/>
3207   <colspec colname="col3" colwidth="3.0*"/>
3208   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3209   <thead>
3210     <row>
3211       <entry spanname="span-horiz" colsep='1'>Transport-version</entry>
3212       <entry>read/write</entry>
3213     </row>
3214     <row>
3215       <entry>major</entry>
3216       <entry>minor</entry>
3217       <entry></entry>
3218     </row>
3219   </thead>
3220   <tbody>
3221     <row>
3222       <entry morerows="2">0</entry>
3223       <entry>0</entry>
3224       <entry>only-CM &amp; Property-with-CM</entry>
3225     </row>
3226     <row>
3227       <entry>1</entry>
3228       <entry>only-CM &amp; multi-CM</entry>
3229     </row>
3230     <row rowsep="1">
3231       <entry>2</entry>
3232       <entry>only-CM &amp; multi-CM &amp; Property-with-CM</entry>
3233     </row>
3234     <row rowsep="1">
3235       <entry>1</entry>
3236       <entry>0</entry>
3237       <entry>PropertyNotify</entry>
3238     </row>
3239     <row>
3240       <entry morerows="1">2</entry>
3241       <entry>0</entry>
3242       <entry>only-CM &amp; PropertyNotify</entry>
3243     </row>
3244     <row>
3245       <entry>1</entry>
3246       <entry>only-CM &amp; multi-CM &amp; PropertyNotify</entry>
3247     </row>
3248   </tbody>
3249   </tgroup>
3250 </table>
3251
3252 <literallayout class="monospaced">
3253 only-CM            :    data is sent via a ClientMessage
3254 multi-CM           :    data is sent via multiple ClientMessages
3255 Property-with-CM   :    data is written in Property, and its Atom
3256                         is send via ClientMessage
3257 PropertyNotify     :    data is written in Property, and its Atom
3258                         is send via PropertyNotify
3259
3260 </literallayout>
3261
3262 <para>
3263 The method to decide major/minor-transport-version is as follows:
3264 </para>
3265
3266 <itemizedlist>
3267   <listitem>
3268     <para>
3269 The client sends 0 as major/minor-transport-version to the IM Server.
3270 The client must support all methods in Table D-3.
3271 The client may send another number as major/minor-transport-version to
3272 use other method than the above in the future.
3273     </para>
3274   </listitem>
3275   <listitem>
3276     <para>
3277 The IM Server sends its major/minor-transport-version number to
3278 the client. The client sends data using the method specified by the
3279 IM Server.
3280     </para>
3281   </listitem>
3282   <listitem>
3283     <para>
3284 If major/minor-transport-version number is not available, it is regarded
3285 as 0.
3286 <!-- .RE -->
3287     </para>
3288   </listitem>
3289 </itemizedlist>
3290
3291 <para>
3292 (*2) dividing size between ClientMessage and Property
3293 </para>
3294
3295 <para>
3296 If data is sent via both of multi-CM and Property, specify the dividing
3297 size between ClientMessage and Property. The data, which is smaller than
3298 this size, is sent via multi-CM (or only-CM), and the data, which is
3299 lager than this size, is sent via Property.
3300 </para>
3301
3302 <para>
3303 <emphasis role="bold">read/write</emphasis>
3304 </para>
3305
3306 <para>
3307 The data is transferred via either ClientMessage or Window Property in
3308 the X Window System.
3309 </para>
3310
3311 <para>
3312 Format for the data from the Client to the IM Server
3313 </para>
3314
3315 <para>
3316 ClientMessage
3317 </para>
3318
3319 <para>
3320 If data is sent via ClientMessage event, the format is as follows:
3321 </para>
3322
3323
3324 <table frame="topbot" id="clientmessage_events_format_first_or_middle">
3325   <?dbfo keep-together="always" ?>
3326 <title>The ClientMessage event's format (first or middle)</title>
3327   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3328   <colspec colname="col1" colwidth="1.0*"/>
3329   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3330   <colspec colname="col3" colwidth="3.5*"/>
3331   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3332   <thead>
3333     <row rowsep='1'>
3334       <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
3335       <entry>Contents</entry>
3336     </row>
3337   </thead>
3338   <tbody>
3339     <row>
3340       <entry>int</entry>
3341       <entry>type</entry>
3342       <entry>ClientMessage</entry>
3343     </row>
3344     <row>
3345       <entry>u_long</entry>
3346       <entry>serial</entry>
3347       <entry>Set by the X Window System</entry>
3348     </row>
3349     <row>
3350       <entry>Bool</entry>
3351       <entry>send_event</entry>
3352       <entry>Set by the X Window System</entry>
3353     </row>
3354     <row>
3355       <entry>Display</entry>
3356       <entry>*display</entry>
3357       <entry>The display to which connects</entry>
3358     </row>
3359     <row>
3360       <entry>Window</entry>
3361       <entry>window</entry>
3362       <entry>IMS communication window ID</entry>
3363     </row>
3364     <row>
3365       <entry>Atom</entry>
3366       <entry>message_type</entry>
3367       <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
3368     </row>
3369     <row>
3370       <entry>int</entry>
3371       <entry>format</entry>
3372       <entry>8</entry>
3373     </row>
3374     <row>
3375       <entry>char</entry>
3376       <entry>data.b[20]</entry>
3377       <entry>(read/write DATA : 20 byte)</entry>
3378     </row>
3379   </tbody>
3380   </tgroup>
3381 </table>
3382
3383 <table frame="topbot" id="clientmessage_events_format_only_or_last">
3384   <?dbfo keep-together="always" ?>
3385 <title>The ClientMessage event's format (only or last)</title>
3386   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3387   <colspec colname="col1" colwidth="1.0*"/>
3388   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3389   <colspec colname="col3" colwidth="3.5*"/>
3390   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3391   <thead>
3392     <row rowsep='1'>
3393       <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
3394       <entry>Contents</entry>
3395     </row>
3396   </thead>
3397   <tbody>
3398     <row>
3399       <entry>int</entry>
3400       <entry>type</entry>
3401       <entry>ClientMessage</entry>
3402     </row>
3403     <row>
3404       <entry>u_long</entry>
3405       <entry>serial</entry>
3406       <entry>Set by the X Window System</entry>
3407     </row>
3408     <row>
3409       <entry>Bool</entry>
3410       <entry>send_event</entry>
3411       <entry>Set by the X Window System</entry>
3412     </row>
3413     <row>
3414       <entry>Display</entry>
3415       <entry>*display</entry>
3416       <entry>The display to which connects</entry>
3417     </row>
3418     <row>
3419       <entry>Window</entry>
3420       <entry>window</entry>
3421       <entry>IMS communication window ID</entry>
3422     </row>
3423     <row>
3424       <entry>Atom</entry>
3425       <entry>message_type</entry>
3426       <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
3427     </row>
3428     <row>
3429       <entry>int</entry>
3430       <entry>format</entry>
3431       <entry>8</entry>
3432     </row>
3433     <row>
3434       <entry>char</entry>
3435       <entry>data.b[20]</entry>
3436       <entry>(read/write DATA : MAX 20 byte)  (*1)</entry>
3437     </row>
3438   </tbody>
3439   </tgroup>
3440 </table>
3441
3442 <para>
3443 (*1) If the data is smaller than 20 byte, all data other than available data
3444 must be 0.
3445 </para>
3446
3447 <para>
3448 Property
3449 </para>
3450
3451 <para>
3452 In the case of large data, data will be sent via the Window Property
3453 for the efficiency.  There are the following two methods to notify
3454 Property, and transport-version is decided which method is used.
3455 </para>
3456
3457 <itemizedlist>
3458   <listitem>
3459     <para>
3460 The XChangeProperty function is used to store data in the client
3461 communication window, and Atom of the stored data is notified to the
3462 IM Server via ClientMessage event.
3463     </para>
3464   </listitem>
3465   <listitem>
3466     <para>
3467 The XChangeProperty function is used to store data in the client
3468 communication window, and Atom of the stored data is notified to the
3469 IM Server via PropertyNotify event.
3470     </para>
3471   </listitem>
3472 </itemizedlist>
3473
3474 <para>
3475 The arguments of the XChangeProperty are as follows:
3476 </para>
3477
3478 <table frame="topbot" id="xchangeproperty_events_format">
3479   <?dbfo keep-together="always" ?>
3480 <title>The XChangeProperty event's format</title>
3481   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3482   <colspec colname="col1" colwidth="1.0*"/>
3483   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3484   <colspec colname="col3" colwidth="3.5*"/>
3485   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3486   <thead>
3487     <row rowsep='1'>
3488       <entry spanname="span-horiz" colsep='1'>Argument</entry>
3489       <entry>Contents</entry>
3490     </row>
3491   </thead>
3492   <tbody>
3493     <row>
3494       <entry>Display</entry>
3495       <entry>*display</entry>
3496       <entry>The display to which connects</entry>
3497     </row>
3498     <row>
3499       <entry>Window</entry>
3500       <entry>window</entry>
3501       <entry>IMS communication window ID</entry>
3502     </row>
3503     <row>
3504       <entry>Atom</entry>
3505       <entry>property</entry>
3506       <entry>read/write property Atom (*1)</entry>
3507     </row>
3508     <row>
3509       <entry>Atom</entry>
3510       <entry>type</entry>
3511       <entry>XA_STRING  </entry>
3512     </row>
3513     <row>
3514       <entry>int</entry>
3515       <entry>format</entry>
3516       <entry>8</entry>
3517     </row>
3518     <row>
3519       <entry>int</entry>
3520       <entry>mode</entry>
3521       <entry>PropModeAppend</entry>
3522     </row>
3523     <row>
3524       <entry>u_char</entry>
3525       <entry>*data</entry>
3526       <entry>read/write DATA</entry>
3527     </row>
3528     <row>
3529       <entry>int</entry>
3530       <entry>nelements</entry>
3531       <entry>length of DATA</entry>
3532     </row>
3533   </tbody>
3534   </tgroup>
3535 </table>
3536
3537 <para>
3538 The read/write property ATOM allocates the following strings by
3539 <olink targetdoc='libX11' targetptr='XInternAtom'><function>XInternAtom</function></olink>.
3540 </para>
3541
3542 <para>
3543 "_clientXXX"
3544 </para>
3545
3546 <para>
3547 The client changes the property with the mode of PropModeAppend and
3548 the IM Server will read it with the delete mode i.e. (delete = True).
3549 </para>
3550
3551 <para>
3552 If Atom is notified via ClientMessage event, the format of the ClientMessage
3553 is as follows:
3554 </para>
3555
3556 <table frame="topbot" id="clientmessage_events_format_to_send_atom_of_property">
3557   <?dbfo keep-together="always" ?>
3558 <title>The ClientMessage event's format to send Atom of property</title>
3559   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3560   <colspec colname="col1" colwidth="1.0*"/>
3561   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3562   <colspec colname="col3" colwidth="3.5*"/>
3563   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3564   <thead>
3565     <row rowsep='1'>
3566       <entry spanname="span-horiz" colsep='1'>Structure Members</entry>
3567       <entry>Contents</entry>
3568     </row>
3569   </thead>
3570   <tbody>
3571     <row>
3572       <entry>int</entry>
3573       <entry>type</entry>
3574       <entry>ClientMessage</entry>
3575     </row>
3576     <row>
3577       <entry>u_long</entry>
3578       <entry>serial</entry>
3579       <entry>Set by the X Window System</entry>
3580     </row>
3581     <row>
3582       <entry>Bool</entry>
3583       <entry>send_event</entry>
3584       <entry>Set by the X Window System</entry>
3585     </row>
3586     <row>
3587       <entry>Display</entry>
3588       <entry>*display</entry>
3589       <entry>The display to which connects</entry>
3590     </row>
3591     <row>
3592       <entry>Window</entry>
3593       <entry>window</entry>
3594       <entry>IMS communication window ID</entry>
3595     </row>
3596     <row>
3597       <entry>Atom</entry>
3598       <entry>message_type</entry>
3599       <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
3600     </row>
3601     <row>
3602       <entry>int</entry>
3603       <entry>format</entry>
3604       <entry>32</entry>
3605     </row>
3606     <row>
3607       <entry>long</entry>
3608       <entry>data.l[0]</entry>
3609       <entry>length of read/write property Atom</entry>
3610     </row>
3611     <row>
3612       <entry>long</entry>
3613       <entry>data.l[1]</entry>
3614       <entry>read/write property Atom</entry>
3615     </row>
3616   </tbody>
3617   </tgroup>
3618 </table>
3619
3620 <para>
3621 Format for the data from the IM Server to the Client
3622 </para>
3623
3624 <para>
3625 <!-- .LP -->
3626 <!-- .RS -->
3627 <!-- .B -->
3628 ClientMessage
3629 </para>
3630 <para>
3631 <!-- .LP -->
3632 The format of the ClientMessage is as follows:
3633 </para>
3634
3635
3636
3637 <table frame="topbot" id="clientmessage_events_format_for_first_or_middle">
3638   <?dbfo keep-together="always" ?>
3639 <title>The ClientMessage event's format (first or middle)</title>
3640   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3641   <colspec colname="col1" colwidth="1.0*"/>
3642   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3643   <colspec colname="col3" colwidth="3.5*"/>
3644   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3645   <thead>
3646     <row rowsep='1'>
3647       <entry spanname="span-horiz" colsep='1'>Structure Members</entry>
3648       <entry>Contents</entry>
3649     </row>
3650   </thead>
3651   <tbody>
3652     <row>
3653       <entry>int</entry>
3654       <entry>type</entry>
3655       <entry>ClientMessage</entry>
3656     </row>
3657     <row>
3658       <entry>u_long</entry>
3659       <entry>serial</entry>
3660       <entry>Set by the X Window System</entry>
3661     </row>
3662     <row>
3663       <entry>Bool</entry>
3664       <entry>send_event </entry>
3665       <entry>Set by the X Window System</entry>
3666     </row>
3667     <row>
3668       <entry>Display</entry>
3669       <entry>*display</entry>
3670       <entry>The display to which connects</entry>
3671     </row>
3672     <row>
3673       <entry>Window</entry>
3674       <entry>window</entry>
3675       <entry>client communication window ID</entry>
3676     </row>
3677     <row>
3678       <entry>Atom</entry>
3679       <entry>message_type</entry>
3680       <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
3681     </row>
3682     <row>
3683       <entry>int</entry>
3684       <entry>format</entry>
3685       <entry>8</entry>
3686     </row>
3687     <row>
3688       <entry>char</entry>
3689       <entry>data.b[20]</entry>
3690       <entry>(read/write DATA : 20 byte)</entry>
3691     </row>
3692   </tbody>
3693   </tgroup>
3694 </table>
3695
3696
3697 <table frame="topbot" id="clientmessage_events_format_for_only_or_last">
3698   <?dbfo keep-together="always" ?>
3699 <title>The ClientMessage event's format (only or last)</title>
3700   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3701   <colspec colname="col1" colwidth="1.0*"/>
3702   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3703   <colspec colname="col3" colwidth="3.5*"/>
3704   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3705   <thead>
3706     <row rowsep='1'>
3707       <entry spanname="span-horiz" colsep='1'>Structure Members</entry>
3708       <entry>Contents</entry>
3709     </row>
3710   </thead>
3711   <tbody>
3712     <row>
3713       <entry>int</entry>
3714       <entry>type</entry>
3715       <entry>ClientMessage</entry>
3716     </row>
3717     <row>
3718       <entry>u_long</entry>
3719       <entry>serial</entry>
3720       <entry>Set by the X Window System</entry>
3721     </row>
3722     <row>
3723       <entry>Bool</entry>
3724       <entry>send_event </entry>
3725       <entry>Set by the X Window System</entry>
3726     </row>
3727     <row>
3728       <entry>Display</entry>
3729       <entry>*display</entry>
3730       <entry>The display to which connects</entry>
3731     </row>
3732     <row>
3733       <entry>Window</entry>
3734       <entry>window</entry>
3735       <entry>client communication window ID</entry>
3736     </row>
3737     <row>
3738       <entry>Atom</entry>
3739       <entry>message_type</entry>
3740       <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
3741     </row>
3742     <row>
3743       <entry>int</entry>
3744       <entry>format</entry>
3745       <entry>8</entry>
3746     </row>
3747     <row>
3748       <entry>char</entry>
3749       <entry>data.b[20]</entry>
3750       <entry>(read/write DATA : MAX 20 byte) (*1)</entry>
3751     </row>
3752   </tbody>
3753   </tgroup>
3754 </table>
3755
3756 <para>
3757 (*1) If the data size is smaller than 20 bytes, all data other than available
3758 data must be 0.
3759 </para>
3760
3761 <para>
3762 Property
3763 </para>
3764
3765 <para>
3766 In the case of large data, data will be sent via the Window Property
3767 for the efficiency. There are the following two methods to notify
3768 Property, and transport-version is decided which method is used.
3769 </para>
3770
3771 <itemizedlist>
3772   <listitem>
3773     <para>
3774 The XChangeProperty function is used to store data in the IMS
3775 communication window, and Atom of the property is sent via the
3776 ClientMessage event.
3777     </para>
3778   </listitem>
3779   <listitem>
3780     <para>
3781 The XChangeProperty function is used to store data in the IMS
3782 communication window, and Atom of the property is sent via
3783 PropertyNotify event.
3784     </para>
3785   </listitem>
3786 </itemizedlist>
3787
3788 <para>
3789 The arguments of the XChangeProperty are as follows:
3790 </para>
3791
3792 <table frame="topbot" id="xchangeproperty_events_format_2">
3793   <?dbfo keep-together="always" ?>
3794 <title>The XChangeProperty event's format</title>
3795   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3796   <colspec colname="col1" colwidth="1.0*"/>
3797   <colspec colname="col2" colwidth="1.0*" colsep="1"/>
3798   <colspec colname="col3" colwidth="3.5*"/>
3799   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3800   <thead>
3801     <row rowsep='1'>
3802       <entry spanname="span-horiz" colsep='1'>Argument</entry>
3803       <entry>Contents</entry>
3804     </row>
3805   </thead>
3806   <tbody>
3807     <row>
3808       <entry>Display</entry>
3809       <entry>*display</entry>
3810       <entry>The display which to connects</entry>
3811     </row>
3812     <row>
3813       <entry>Window</entry>
3814       <entry>window</entry>
3815       <entry>client communication window ID</entry>
3816     </row>
3817     <row>
3818       <entry>Atom</entry>
3819       <entry>property</entry>
3820       <entry>read/write property Atom (*1)</entry>
3821     </row>
3822     <row>
3823       <entry>Atom</entry>
3824       <entry>type</entry>
3825       <entry>XA_STRING</entry>
3826     </row>
3827     <row>
3828       <entry>int</entry>
3829       <entry>format</entry>
3830       <entry>8</entry>
3831     </row>
3832     <row>
3833       <entry>int</entry>
3834       <entry>mode</entry>
3835       <entry>PropModeAppend</entry>
3836     </row>
3837     <row>
3838       <entry>u_char</entry>
3839       <entry>*data</entry>
3840       <entry>read/write DATA</entry>
3841     </row>
3842     <row>
3843       <entry>int</entry>
3844       <entry>nelements</entry>
3845       <entry>length of DATA</entry>
3846     </row>
3847   </tbody>
3848   </tgroup>
3849 </table>
3850
3851 <para>
3852 (*1)  The read/write property ATOM allocates some strings, which are not
3853 allocated by the client, by <olink targetdoc='libX11' targetptr='XInternAtom'><function>XInternAtom</function></olink>.
3854 </para>
3855
3856 <para>
3857 The IM Server changes the property with the mode of PropModeAppend and
3858 the client reads it with the delete mode, i.e. (delete = True).
3859 </para>
3860
3861 <para>
3862 If Atom is notified via ClientMessage event, the format of the ClientMessage
3863 is as follows:
3864 </para>
3865
3866
3867 <table frame="topbot" id="clientmessage_events_format_to_send_atom_of_property_2">
3868   <?dbfo keep-together="always" ?>
3869 <title>The ClientMessage event's format to send Atom of property</title>
3870   <tgroup cols="3" align='left' colsep='0' rowsep='0'>
3871   <colspec colname="col1" colwidth="1.0*"/>
3872   <colspec colname="col2" colwidth="1.0*" colsep='1'/>
3873   <colspec colname="col3" colwidth="3.5*"/>
3874   <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
3875   <thead>
3876     <row rowsep='1'>
3877       <entry spanname="span-horiz" colsep='1'>Structure Member</entry>
3878       <entry>Contents</entry>
3879     </row>
3880   </thead>
3881   <tbody>
3882     <row>
3883       <entry>int</entry>
3884       <entry>type</entry>
3885       <entry>ClientMessage  </entry>
3886     </row>
3887     <row>
3888       <entry>u_long</entry>
3889       <entry>serial</entry>
3890       <entry>Set by the X Window System  </entry>
3891     </row>
3892     <row>
3893       <entry>Bool</entry>
3894       <entry>send_event</entry>
3895       <entry>Set by the X Window System  </entry>
3896     </row>
3897     <row>
3898       <entry>Display</entry>
3899       <entry>*display</entry>
3900       <entry>The display to which connects  </entry>
3901     </row>
3902     <row>
3903       <entry>Window</entry>
3904       <entry>window</entry>
3905       <entry>client communication window ID  </entry>
3906     </row>
3907     <row>
3908       <entry>Atom</entry>
3909       <entry>message_type</entry>
3910       <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
3911     </row>
3912     <row>
3913       <entry>int</entry>
3914       <entry>format</entry>
3915       <entry>32  </entry>
3916     </row>
3917     <row>
3918       <entry>long</entry>
3919       <entry>data.l[0]</entry>
3920       <entry>length of read/write property ATOM  </entry>
3921     </row>
3922     <row>
3923       <entry>long</entry>
3924       <entry>data.l[1]</entry>
3925       <entry>read/write property ATOM  </entry>
3926     </row>
3927   </tbody>
3928   </tgroup>
3929 </table>
3930
3931 <para>
3932 Closing Connection
3933 </para>
3934
3935 <para>
3936 If the client disconnect with the IM Server, shutdown function should
3937 free the communication window properties and etc..
3938 </para>
3939 </appendix>
3940 </article>