

















                    [1mThe Input Method Protocol[0m

                           [1mVersion 1.0[0m

                      [1mX Consortium Standard[0m

                    [1mX Version 11, Release 6.4[0m





                         [4mMasahiko[24m [4mNarita[0m
                        FUJITSU Limited.

                          [4mHideki[24m [4mHiura[0m
                          SunSoft, Inc.





                            [4mABSTRACT[0m

     This  specifies  a  protocol  between IM library and IM
     (Input Method) Server for internationalized text input,
     which is independent 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 input method for all ap-
     plications within the stand-alone distributed  environ-
     ment.
































      X Window System is a trademark of X Consortium, Inc.

         Copyright (C) 1993, 1994 by X Consortium, Inc.

Permission  is  hereby granted, free of charge, to any person ob-
taining a copy of  this  software  and  associated  documentation
files  (the "Software"), to deal in the Software without restric-
tion, including without limitation the rights to use, copy,  mod-
ify,  merge,  publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom  the  Software  is
furnished to do so, subject to the following conditions:

The  above  copyright  notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF  ANY  KIND,
EXPRESS  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE  AND  NONIN-
FRINGEMENT.  IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY
CLAIM,  DAMAGES  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CON-
TRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR  IN  CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except  as contained in this notice, the name of the X Consortium
shall not be used in advertising  or  otherwise  to  promote  the
sale,  use or other dealings in this Software without prior writ-
ten authorization from the X Consortium.




           Copyright (C) 1993, 1994 by FUJITSU LIMITED

       Copyright (C) 1993, 1994 by Sun Microsystems, Inc.

Permission to use, copy, modify, and distribute  this  documenta-
tion  for any purpose and without fee is hereby granted, provided
that the above copyright notice and this permission notice appear
in all copies.  Fujitsu and Sun Microsystems make no  representa-
tions about the suitability for any purpose of the information in
this  document.  This documentation is provided as is without ex-
press or implied warranty.













[1m1.  Introduction[0m

[1m1.1.  Scope[0m

The internationalization in the X Window System Version  11,  Re-
lease  5 (X11R5) provides a common API which application develop-
ers can use to create portable internationalized programs and  to
adapt them to the requirements of different native languages, lo-
cal customs, and character string encodings (this is called ``lo-
calization'').   As  one  of  its internationalization mechanisms
X11R5 has defined a functional  interface  for  internationalized
text input, called XIM (X Input Method).

When  a client-server model is used with an IM (Input Method) im-
plementation, a protocol must be established between  the  client
and  the  server.   However, the protocol used to interface Input
Method Servers (IM Servers) with the Input Method  libraries  (IM
libraries)  to which applications are linked was not addressed in
X11R5.  This led application developers to depend on  vendor-spe-
cific input methods, decreased the user's choice of available in-
put  methods, and made it more difficult for developers to create
portable applications. This paper describes the Input Method Pro-
tocol developed for X11R6 to resolve the above  problems  and  to
address the requirements of existing and future input methods.

The Input Method Protocol is independent from the transport layer
used  in  communication between the IM library and the IM Server.
Thus, the input method protocol can be built on any inter-process
communication mechanism, such as TCP/IP or the X protocol.

In addition, the protocol provides for future extensions such  as
differing input model types.


[1m1.2.  Background[0m

Text  input  is  much more simple for some languages than others.
English, for instance, uses an alphabet of a manageable size, and
input consists of pressing the corresponding key on  a  keyboard,
perhaps  in  combination  with a shift key for capital letters or
special characters.

Some languages have larger alphabets, or modifiers  such  as  ac-
cents,  which require the addition of special key combinations in
order to enter text.  These input  methods  may  require  ``dead-
keys'' or ``compose-keys'' which, when followed by different com-
binations of key strokes, generate different characters.

Text  input  for  ideographic  languages is much less simple.  In
these languages, characters represent actual objects rather  than
phonetic  sounds  used  in  pronouncing a word, and the number of
characters in these languages may continue to grow.  In Japanese,
for instance, most text input methods involve entering characters
in a phonetic alphabet, after which the input method  searches  a



                                [1m1[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


dictionary  for  possible ideographic equivalents (of which there
may be many).  The input method then presents the candidate char-
acters for the user to choose from.

In Japanese, either Kana (phonetic symbols) or Roman letters  are
typed and then a region is selected for conversion to Kanji. Sev-
eral  Kanji characters may have the same phonetic representation.
If that is the case with the string entered, a menu of characters
is presented and the user must choose the appropriate one. If  no
choice is necessary or a preference has been established, the in-
put method does the substitution directly.

These  complicated  input  methods must present state information
(Status Area), text entry and  edit  space  (Preedit  Area),  and
menu/choice presentations (Auxiliary Area).  Much of the protocol
between  the IM library and the IM Server involves managing these
IM areas.  Because of the size  and  complexity  of  these  input
methods, and because of how widely they vary from one language or
locale  to  another,  they  are  usually  implemented as separate
processes which can serve many client processes on the same  com-
puter or network.


[1m1.3.  Input Method Styles[0m

X11  internationalization  support  includes  the  following four
types of input method:

     - on-the-spot:      The client application  is  directed  by
                         the  IM  Server  to display all pre-edit
                         data at the site of text insertion.  The
                         client registers  callbacks  invoked  by
                         the input method during pre-editing.

     - off-the-spot:     The  client application provides display
                         windows for the pre-edit data to the in-
                         put method which displays into them  di-
                         rectly.

     - over-the-spot:    The  input method displays pre-edit data
                         in a window which it brings up  directly
                         over the text insertion position.

     - root-window:      The  input  method displays all pre-edit
                         data in a separate area of the screen in
                         a window specific to the input method.

Client applications must choose from the available input  methods
supported  by  the  IM  Server  and provide the display areas and
callbacks required by the input method.







                                [1m2[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


[1m2.  Architecture[0m

[1m2.1.  Implementation Model[0m

Within the X Window System environment, the following two typical
architectural models can be used as an input method's implementa-
tion model.

     - Client/Server model:
                         A  separate  process,  the  IM   Server,
                         processes  input and handles preediting,
                         converting, and committing.  The IM  li-
                         brary  within the application, acting as
                         client to the IM Server, simply receives
                         the committed string from the IM Server.

     - Library model:    All input is handled by the  IM  library
                         within   the   application.   The  event
                         process is closed within the IM  library
                         and a separate IM Server process may not
                         be required.

Most  languages which need complex preediting, such as Asian lan-
guages, are implemented using the Client/Server IM model.   Other
languages  which  need  only  dead key or compose key processing,
such as European languages, are  implemented  using  the  Library
model.

In  this  paper, we discuss mainly the Client/Server IM model and
the  protocol  used  in  communication  between  the  IM  library
(client) and the IM Server.


[1m2.2.  Structure of IM[0m

When the client connects or disconnects to the IM Server, an open
or close operation occurs between the client and the IM Server.

The  IM  can be specified at the time of XOpenIM() by setting the
locale of the client and a locale modifier. Since the  IM  remem-
bers  the  locale at the time of creation XOpenIM() can be called
multiple times (with the setting for the locale  and  the  locale
modifier changed) to support multiple languages.

In  addition, the supported IM type can be obtained using XGetIM-
Values().

The client usually holds multiple input (text) fields. Xlib  pro-
vides  a  value  type called the ``Input Context'' (IC) to manage
each individual input field.  An IC can be created by  specifying
XIM  using  XCreateIC(),  and  it  can  be  destroyed  using XDe-
stroyIC().





                                [1m3[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


The IC can specify the type of IM which is supported by  XIM  for
each input field, so each input field can handle a different type
of IM.

Most  importantly  information  such as the committed string sent
from the IM Server to the client, is exchanged based on each IC.

Since each IC corresponds to an input field,  the  focused  input
field  should  be announced to the IM Server using XSetICFocus().
(XUnsetICFocus() can also be used to change the focus.)


[1m2.3.  Event Handling Model[0m

Existing input methods support either the  FrontEnd  method,  the
BackEnd method, or both.  This protocol specifically supports the
BackEnd method as the default method, but also supports the Fron-
tEnd method as an optional IM Server extension.

The difference between the FrontEnd and BackEnd methods is in how
events are delivered to the IM Server.  (Fig. 1)


[1m2.3.1.  BackEnd Method[0m

In  the BackEnd method, client window input events are always de-
livered to the IM library, which  then  passes  them  to  the  IM
Server.   Events are handled serially in the order delivered, and
therefore there is no synchronization problem between the IM  li-
brary and the IM Server.

Using  this  method,  the  IM  library  forwards all KeyPress and
KeyRelease events to the IM Server (as required by the Event Flow
Control model described in section 2.4. ``Event Flow  Control''),
and  synchronizes  with  the  IM  Server (as described in section
4.16.  ``Filtering Events'').


[1m2.3.2.  FrontEnd Method[0m

In the FrontEnd method, client window input events are  delivered
by  the  X  server  directly to both the IM Server and the IM li-
brary.  Therefore this method provides  much  better  interactive
performance  while preediting (particularly in cases such as when
the IM Server is running locally on the  user's  workstation  and
the  client  application is running on another workstation over a
relatively slow network).

However, the FrontEnd model may have synchronization problems be-
tween the key events handled in the IM Server  and  other  events
handled  in  the  client, and these problems could possibly cause
the loss or duplication of key  events.   For  this  reason,  the
BackEnd  method  is  the  core method supported, and the FrontEnd
method  is  made  available  as  an  extension  for   performance



                                [1m4[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


purposes. (Refer to Appendix A for more information.)
























































                                [1m5[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


... 0.05 6.513 4.737 10.45 ... 0.000i 3.937i 4.687i 0.000i

         +


                            ____________________
                            ||                   ||
                            |  Application      |
                            |                   |
                            |  _______          |
                            |         ||         |
                            |  ||   _||__|__________|
                            |  |   |  | Library |||
                            |  ||   _|__|__________||
                            _|__||_______|__________||
                               |||      |
                               |      ||
                               |   ___|__________________
                               |   ||                    ||
                               |   |    IM Ser|ver       |
                               |   _|__________|__________|
                 BackEnd Method|(Core)        |||FrontEnd Method (Extension)
                               |              |
                            ___|_______________|__
                            ||                   ||
                            |      X Server     |
                            _|___________________|


                    Fig.1 The Flow of Events


[1m2.4.  Event Flow Control[0m

This  protocol  supports  two event flow models for communication
between the IM library and the IM Server (Static and Dynamic).

Static Event Flow requires that input events always  be  sent  to
the IM Server from the client.

Dynamic  Event  Flow,  however,  requires  only  that those input
events which need to be processed (converted) be sent to  the  IM
Server from the client.

For  instance,  in  the  case  of inputing a combination of ASCII
characters and Chinese characters, ASCII characters do  not  need
to be processed in the IM Server, so their key events do not have
to  be sent to the IM Server.  On the other hand, key events nec-
essary for composing Chinese characters must be sent  to  the  IM
Server.

Thus,  by adopting the Dynamic Event Flow, the number of requests
among the X Server, the client, and the  IM  Server  is  signifi-
cantly  reduced,  and  the  number  of  context  switches is also



                                [1m6[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


reduced, resulting in improved performance.  The  IM  Server  can
send  message  in  order  to switch the event flow in the Dynamic
Event Flow.

The protocol for  this  process  is  described  in  section  4.5.
``Event Flow Control''.


[1m3.  Default Preconnection Convention[0m

IM  Servers  are  strongly  encouraged to register their symbolic
names as the ATOM names into the IM Server directory property, on
the root window of the screen_number 0.  This property  can  con-
tain  a list of ATOMs, and the each ATOM represents each possible
IM Server.  IM Server names  are  restricted  to  POSIX  Portable
Filename  Character Set.  To discover if the IM Server is active,
see if there is an owner for the selection with that  atom  name.
To  learn  the  address  of that IM Server, convert the selection
target which will return a  string  form  of  the  transport  ad-
dress(es).   To  learn  the  supported locales of that IM Server,
convert the selection target which will return a set of names  of
the supported locales in the syntax X/Open defines.

The  basic semantics to determine the IM Server if there are mul-
tiple ATOMs are found in property, is first fit if the IM  Server
name is not given as a X modifier's category

The  address  information retrievable from the target is a trans-
port-specific name.  The preregistered formats for transport-spe-
cific names are listed in Appendix B.  Additional  transport-spe-
cific names may be registered with X Consortium.

For environments that lack X connections, or for IM Servers which
do not use the X Window System, the preconnection convention with
IM  Server may be given outside the X Window system (e.g. using a
Name Service).


[1m4.  Protocol[0m

The protocol described below  uses  the  bi-directional  synchro-
nous/asynchronous  request/reply/error model and is specified us-
ing the same conventions outlined in Section 2 of the core X Win-
dow System protocol [1]:


[1m4.1.  Basic Requests Packet Format[0m

This section describes the requests that may be exchanged between
the client and the IM Server.

The basic request packet header format is as follows.





                                [1m7[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


               major-opcode:            CARD8
               minor-opcode:            CARD8
               length:                  CARD16

The MAJOR-OPCODE specifies which core request or extension  pack-
age this packet represents.  If the MAJOR-OPCODE corresponds to a
core  request,  the  MINOR-OPCODE contains 8 bits of request-spe-
cific data.  (If the MINOR-OPCODE is not used, it is 0.)   Other-
wise, the MAJOR-OPCODE and the MINOR-OPCODE are specified by mes-
sage.   (Refer  to  4.7.  Query  the supported extension protocol
list.)  The LENGTH field specifies the number of 4 bytes elements
following the header.  If no additional data is followed  by  the
header, the LENGTH field will be 0.


[1m4.2.  Data Types[0m

The  following data types are used in the core X IM Server proto-
col:

BITMASK16
  CARD16

BITMASK32
  CARD32

PADDING FORMAT
  Where N is some expression, and Pad(N) is the number of bytes needed to round N up to a
  multiple of four.
     Pad(N) = (4 - (N mod 4)) mod 4

LPCE
  1                 A character from the4 X Portable Character Set in Latin Portable
                    Character Encoding























                                [1m8[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


STRING
  2  n              length of string in bytes
  n  LISTofLPCE     string
  p                 unused, p=Pad(2+n)

STR
  1  n              length of name in bytes
  n  STRING8        name

XIMATTR
  2  CARD16         attribute ID (*1)
  2  CARD16         type of the value (*2)
  2  n              length of im-attribute
  n  STRING8        im-attribute
  p                 unused, p = Pad(2+n)

The im-attribute argument specifies XIM values such as XNQueryInputStyle.

XICATTR
  2  CARD16         attribute ID (*1)
  2  CARD16         type of the value (*2)
  2  n              length of ic-attribute
  n  STRING8        ic-attribute
  p                 unused, p = Pad(2+n)


(*1) XIMATTR and XICATTR are used during the setup stage and  XI-
     MATTRIBUTE and XICATTRIBUTE are used after each attribute ID
     has been recognized by the IM Server and the IM library.


(*2) The value types are defined as follows:

     tab(:);  l l l s s l l l l l l l l l l l l l l l l l l l l l
     l l l l l l l l l l l l l l l l l l l l l l l l l l l l l  l
     l  l l l l l l l l l l l l l l l l l l l l l l l l l l l l l
     l l l l l l l l l l l l l l l l l l l l l l l l l l l s s  l
     l l s s l l l s s l l l s s l l l s s l l l l l.  _
     [1mvalues:data:format[0m
     [1m_[0m
     #0:Separator  of  NestedList:-----  (*3)  #1:byte data:CARD8
     #2:word data:CARD16 #3:long data:CARD32 #4:char data:STRING8
     #5:Window:CARD32 #10:XIMStyles:2:n:number of  XIMStyle  list
     ::2::unused     ::n:CARD32:XIMStyle     list    #11:XRectan-
     gle:2:INT16:X ::2:INT16:Y ::2:CARD16:width ::2:CARD16:height
     #12:XPoint:2:INT16:X ::2:INT16:Y #13:XFontSet:2:n:length  of
     Base  font name ::n:STRING8:Base font name list ::p::unused,
     p = Pad(2+n) #15:XIMHotKeyTriggers:4:n:T{ number of XIMTRIG-
     GERKEY list (*4) T} ::n:XIMTRIGGERKEY:XIMHotkeyTrigger  list
     #16:XIMHotKeyState::XIMHOTKEYSTATE:T{    HotKey   processing
     state  T}  #17:XIMStringConversion:XIMSTRCONVTEXT   #18:XIM-
     PreeditState:XIMPREEDITSTATE #19:XIMResetState:XIMRESETSTATE
     #x7fff:NestedList:-----
     _



                                [1m9[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


(*3) The  IC  value for the separator of NestedList is defined as
     follows,
          #define   XNSeparatorofNestedList    ``separatorofNest-
     edList''
     , which is registered in X Consortium and cannot be used for
     any other purpose.


(*4) LISTofFOO
          A Type name of the form LISTof FOO means a counted list
          of  elements of type FOO.  The size of the length field
          may vary (it is not necessarily  the  same  size  as  a
          FOO), and in some cases, it may be implicit.


XIMTRIGGERKEY
  4  CARD32         keysym
  4  CARD32         modifier
  4  CARD32         modifier mask

ENCODINGINFO
  2  n              length of encoding info
  n  STRING8        encoding info
  p                 unused, p=Pad(2+n)

EXT
  1  CARD8          extension major-opcode
  1  CARD8          extension minor-opcode
  2  n              length of extension name
  n  STRING8        extension name
  p                 unused, p = Pad(n)

XIMATTRIBUTE
  2  CARD16         attribute ID
  2  n              value length
  n                 value
  p                 unused, p = Pad(n)

XICATTRIBUTE
  2  CARD16         attribute ID
  2  n              value length
  n                 value
  p                 unused, p = Pad(n)














                                [1m10[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


XIMSTRCONVTEXT
  2  CARD16                   XIMStringConversionFeedback
     #x0000001                XIMStringConversionLeftEdge
     #x0000002                XIMStringConversionRightEdge
     #x0000004                XIMStringConversionTopEdge
     #x0000008                XIMStringConversionBottomEdge
     #x0000010                XIMStringConversionConvealed
     #x0000020                XIMStringConversionWrapped
  2  n                        byte length of the retrieved string
  n  STRING8                  retrieved string
  p                           unused, p = Pad(n)
  2  m                        byte length of feedback array
  2                           unused
  m  LISTofXIMSTRCONVFEEDBACK feedback array(*1)

(*1) This field is reserved for future use.


XIMFEEDBACK
  4  CARD32         XIMFeedback
     #x000001       XIMReverse
     #x000002       XIMUnderline
     #x000004       XIMHighlight
     #x000008       XIMPrimary
     #x000010       XIMSecondary
     #x000020       XIMTertiary
     #x000040       XIMVisibleToForward
     #x000080       XIMVisibleToBackward
     #x000100       XIMVisibleCenter

XIMHOTKEYSTATE
  4  CARD32         XIMHotKeyState
     #x0000001      XIMHotKeyStateON
     #x0000002      XIMHotKeyStateOFF

XIMPREEDITSTATE
  4  CARD32         XIMPreeditState
     #x0000001      XIMPreeditEnable
     #x0000002      XIMPreeditDisable

XIMRESETSTATE
  4  CARD32         XIMResetState
     #x0000001      XIMInitialState
     #x0000002      XIMPreserveState


[1m4.3.  Error Notification[0m

Both  the IM Server and the IM library return messages instead of
the corresponding reply messages if any errors occur during  data
processing.

At  most one error is generated per request. If more than one er-
ror condition is encountered in processing a request, the  choice



                                [1m11[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


of which error is returned is implementation-dependent.


     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_ERROR (IM Server <--> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID :2:BIT-
     MASK16:flag (*1) ::#0000:Both Input-Method-ID and Input-Con-
     text-ID  are  invalid   ::#0001:Input-Method-ID   is   valid
     ::#0002:Input-Context-ID   is   valid  :2:CARD16:Error  Code
     ::#1:BadAlloc ::#2:BadStyle ::#3:BadClientWindow ::#4:BadFo-
     cusWindow ::#5:BadArea ::#6:BadSpotLocation ::#7:BadColormap
     ::#8:BadAtom  ::#9:BadPixel  ::#10:BadPixmap   ::#11:BadName
     ::#12:BadCursor     ::#13:BadProtocol    ::#14:BadForeground
     ::#15:BadBackground ::#16:LocaleNotSupported ::#999:BadSome-
     thing (*2) :2:n:byte length of error detail.  :2:CARD16:type
     of error detail (*3) :n:STRING8:error  detail  (*4)  :p::un-
     used, p = Pad(n)

     (*1) Before  an  IM is created, both Input-Method-ID and In-
          put-Context-ID are invalid.  Before an IC  is  created,
          only Input-Method-ID is valid.  After that, both of In-
          put-Method-ID and Input-Context-ID are valid.

     (*2) Unspecific error, for example ``language engine died''

     (*3) This field is reserved for future use.

     (*4) Vendor defined detail error message


[1m4.4.  Connection Establishment[0m

message requests to establish a connection over a mutually-under-
stood virtual stream.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_CONNECT (IM library -> IM Server)
     :1::byte order ::#x42 MSB first ::#x6c LSB first  :1::unused
     :2:CARD16:client-major-protocol-version                 (*1)
     :2:CARD16:client-minor-protocol-version (*1)  :2:CARD16:num-
     ber  of  client-auth-protocol-names  :n:LISTofSTRING:client-
     auth-protocol-names

     (*1) Specify the version of IM Protocol that the client sup-
          ports.


A client must send message as the first message  on  the  connec-
tion.   The  list specifies the names of authentication protocols
the sending IM Server is willing to perform.  (If the client need
not authenticate, the list may be omited.)

message is used to send the authentication protocol name and pro-
tocol-specific data.



                                [1m12[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_AUTH_REQUIRED (IM library <--> IM Server)
     :1:CARD8:auth-protocol-index  :3::unused  :2:n:length of au-
     thentication data :2::unused :n:<varies>:data :p::unused,  p
     = Pad(n)

The auth-protocol is specified by an index into the list of names
given in the or message. Any protocol-specific data that might be
required is also sent.

The  IM  library sends message as the reply to message, if the IM
Server is authenticated.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_AUTH_REPLY (IM library -> IM Server)
     :2:n:length of authentication data :2::unused :2:n:length of
     authentication  data :2::unused :n:<varies>:data :p::unused,
     p = Pad(n)

The auth data is specific to the authentication protocol in use.

message requests to send more auth data.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_AUTH_NEXT (IM library <--> IM Server)
     :2:n:length     of     authentication     data    :2::unused
     :n:<varies>:data :p::unused, p = Pad(n)

The auth data is specific to the authentication protocol in use.

The IM Server sends message to authenticate the client.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_AUTH_SETUP (IM Server -> IM library)
     :2:CARD16:number  of  client-auth-protocol-names  :2::unused
     :n:LISTofSTRING:server-auth-protocol-names

The list specifies the  names  of  authentication  protocols  the
client is willing to perform.

message requests to give up the connection.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_AUTH_NG (IM library <--> IM Server)

The IM Server sends message as the reply to or message.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_CONNECT_REPLY (IM Server -> IM library)
     :2:CARD16:server-major-protocol-version                 (*1)
     :2:CARD16:server-minor-protocol-version (*1)

     (*1) Specify the version of IM Protocol that the  IM  Server
          supports.   This  document specifies major version one,



                                [1m13[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          minor version zero.


Here are the state diagrams for the client and the IM Server.

[1mState transitions for the client[0m

     [4minit_status[24m:
          Use authorization function -> [4mclient_ask[0m
          Not use authorization function -> [4mclient_no_check[0m


     [4mstart[24m:
          Send
               If [4mclient_ask[24m -> [4mclient_wait1[0m
               If [4mclient_no_check[24m, client-auth-protocol-names may
               be omited -> [4mclient_wait2[0m


     [4mclient_wait1[24m:
          Receive -> [4mclient_check[0m
          Receive <other> -> [4mclient_NG[0m


     [4mclient_check[24m:
          If no more auth needed, send -> [4mclient_wait2[0m
          If good auth data, send -> [4mclient_wait1[0m
          If bad auth data, send -> give up on this protocol


     [4mclient_wait2[24m:
          Receive -> connect
          Receive -> [4mclient_more[0m
          Receive -> [4mclient_more[0m
          Receive -> give up on this protocol
          Receive <other> -> [4mclient_NG[0m


     [4mclient_more[24m:
          Send -> [4mclient_wait2[0m


     [4mclient_NG[24m:
          Send -> give up on this protocol


[1mState transitions for the IM Server[0m

     [4minit-status[24m:
          Use authorization function -> [4mserver_ask[0m
          Not use authorization function -> [4mserver_no_check[0m






                                [1m14[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     [4mstart[24m:
          Receive -> [4mstart2[0m
          Receive <other> -> [4mserver_NG[0m


     [4mstart2[24m:
          If [4mclient_ask[24m, send -> [4mserver_wait1[0m
          If [4mclient_no_check[24m and [4mserver_ask[24m, send -> [4mserver_wait2[0m
          If [4mclient_no_check[24m and [4mserver_no_check[24m, send -> connect


     [4mserver_wait1[24m:
          Receive -> [4mserver2[0m
          Receive -> [4mserver_more[0m
          Receive <other> -> [4mserver_NG[0m


     [4mserver_more[0m
          Send -> [4mserver_wait1[0m


     [4mserver2[0m
          If [4mserver_ask[24m, send -> [4mserver_wait2[0m
          If [4mserver_no_check[24m, send -> connect


     [4mserver_wait2[0m
          Receive -> [4mserver_check[0m
          Receive <other> -> [4mserver_NG[0m


     [4mserver_check[0m
          If no more auth data, send -> connect
          If bad auth data, send -> give up on this protocol
          If good auth data, send -> [4mserver_wait2[0m


     [4mserver_NG[0m
          Send -> give up on this protocol


message requests to shutdown the connection over  a  mutually-un-
derstood virtual stream.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_DISCONNECT (IM library -> IM Server)

is a synchronous request.  The IM library should  wait  until  it
receives either an packet or an packet.


     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_DISCONNECT_REPLY (IM Server -> IM library)




                                [1m15[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


requests to establish a logical connection between the IM library
and the IM Server.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_OPEN (IM library -> IM Server)
     :n:STR:locale name :p::unused, p = Pad(n)

is  a  synchronous request.  The IM library should wait until re-
ceiving either an packet or an packet.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_OPEN_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID  :2:n:byte length of IM attributes
     supported :n:LISTofXIMATTR:IM attributes supported :2:m:byte
     length   of   IC   attributes   supported   :2:CARD16:unused
     :m:LISTofXICATTR: IC attributes supported

message  returns  all supported IM and IC attributes in LISTofXI-
MATTR and LISTofXICATTR.  These IM and IC attribute IDs are  used
to  reduce  the  amount of data which must be transferred via the
network. In addition, this indicates to the IM library what kinds
of IM/IC attributes can be used in this session, and  what  types
of data will be exchanged. This allows the IM Server provider and
application  writer  to  support  IM system enhancements with new
IM/IC attributes, without modifying Xlib.  The IC value  for  the
separator of NestedList must be included in the LISTofXICATTR.

message  requests  to shutdown the logical connection between the
IM library and the IM Server.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_CLOSE (IM library -> IM Server)
     :2:CARD16:input-method-ID :2::unused

is  a  synchronous request.  The IM library should wait until re-
ceiving either an packet or an packet.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_CLOSE_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2::unused

[1m4.5.  Event Flow Control[0m

An  IM  Server  must  send message to the IM library in order for
events to be forwarded to the IM Server,  since  the  IM  library
initially  doesn't  forward  any  events to the IM Server. In the
protocol, the IM Server will specify masks of X events to be for-
warded and which need to be synchronized by the IM library.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).



                                [1m16[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     XIM_SET_EVENT_MASK (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:EVENTMASK:forward-event-mask  (*1)  :4:EVENTMASK:synchro-
     nous-event-mask (*2)

     (*1) Specify all the events to be forwarded to the IM Server
          by the IM library.

     (*2) Specify  the  events  to  be forwarded with synchronous
          flag on by the IM library.


is an asynchronous request.  The event masks  are  valid  immedi-
ately  after  they  are set until changed by another message.  If
input-context-ID is set to zero, the default value of the  input-
method-ID will be changed to the event masks specified in the re-
quest.   That value will be used for the IC's which have no indi-
vidual values.

Using the Dynamic Event Flow model, an IM Server sends message to
the IM library before sending message.  Or  the  IM  library  may
suppose that the IM Server uses the Static Event Flow model.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_REGISTER_TRIGGERKEYS (IM Server -> IM library)
     :2:CARD16:input-method-ID :2::unused :4:n:byte length of on-
     keys :n:LISTofXIMTRIGGERKEY:on-keys list :4:m:byte length of
     off-keys :m:LISTofXIMTRIGGERKEY:off-keys list

is an asynchronous request.  The IM Server notifys the IM library
of on-keys and off-keys lists with this message.

The IM library notifys the IM Server  with  message  that  a  key
event matching either on-keys or off-keys has been occurred.


     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_TRIGGER_NOTIFY (IM library -> IM Server)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:CARD32:flag    ::#0:on-keys   list   ::#1:off-keys   list
     :4:CARD32:index  of  keys  list  :4:EVENTMASK:client-select-
     event-mask (*1)

     (*1) Specify the events currently selected by the IM library
          with XSelectInput.


is  a  synchronous request.  The IM library should wait until re-
ceiving either an packet or an packet.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_TRIGGER_NOTIFY_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID



                                [1m17[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


[1m4.6.  Encoding Negotiation[0m

message  requests  to decide which encoding to be sent across the
wire.  When the negotiation fails, the fallback default  encoding
is Portable Character Encoding.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_ENCODING_NEGOTIATION (IM library  ->  IM  Server).sp  6p
     :2:CARD16:input-method-ID   :2:n:byte  length  of  encodings
     listed by name :n:LISTofSTR:list of encodings  supported  in
     the  IM library.  :p::unused, p = Pad(n) :2:m:byte length of
     encodings listed by detailed  data  :2::unused  :m:LISTofEN-
     CODINGINFO:list of encordings supported in the IM library

The  IM Server must choose one encoding from the list sent by the
IM library.  If index of the encording determined is -1 to  indi-
cate  that the negotiation is failed, the fallback default encod-
ing is used.  The message must be issued  after  sending  message
via  XOpenIM().   The  name  of encoding may be registered with X
Consortium.

is a synchronous request.  The IM library should wait  until  re-
ceiving either an packet or an packet.


     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_ENCODING_NEGOTIATION_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:category of the encoding
     determined.  ::#0:name ::#1:detailed data :2:INT16:index  of
     the encoding determinated.  :2::unused

[1m4.7.  Query the supported extension protocol list[0m

message  requests  to query the IM extensions supported by the IM
Server to which the client is being connected.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_QUERY_EXTENSION (IM library -> IM Server)
     :2:CARD16:input-method-ID  :2:n:T{ byte length of extensions
     supported by the IM library T} :n:LISTofSTR:extensions  sup-
     ported by the IM library :p::unused, p = Pad(n)

An  example  of  a  supported extension is FrontEnd.  The message
must be issued after sending message via XOpenIM().

If n is 0, the IM library queries the IM Server  for  all  exten-
sions.

If  n is not 0, the IM library queries whether the IM Server sup-
ports the contents specified in the list.

If a client uses an extension request without  previously  having
issued  a message for that extension, the IM Server responds with
a error.  If the IM Server encounters a request with  an  unknown



                                [1m18[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


MAJOR-OPCODE or MINOR-OPCODE, it responds with a error.

is  a  synchronous request.  The IM library should wait until re-
ceiving either an packet or an packet.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_QUERY_EXTENSION_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID  :2:n:T{ byte length of extensions
     supported by both the  IM  library  and  the  IM  Server  T}
     :n:LISTofEXT:T{  list of extensions supported by both the IM
     library and the IM Server T}

message returns the list of extensions supported by both  the  IM
library and the IM Server. If the list passed in message is NULL,
the  IM  Server  returns the full list of extensions supported by
the IM Server.  If the list is not NULL, the  IM  Server  returns
the extensions in the list that are supported by the IM Server.

A  zero-length  string is not a valid extension name.  The IM li-
brary should disregard any zero-length strings that are  returned
in  the extension list.  The IM library does not use the requests
which are not supported by the IM Server.


[1m4.8.  Setting IM Values[0m

requests to set attributes to the IM.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_SET_IM_VALUES (IM library -> IM Server)
     :2:CARD16:input-method-ID  :2:n:byte  length of im-attribute
     :n:LISTofXIMATTRIBUTE:im-attributes

The im-attributes in message  are  specified  as  a  LISTofXIMAT-
TRIBUTE,  specifying  the  attributes to be set. Attributes other
than the ones returned by message should not be specified.

is a synchronous request. The IM library should  wait  until  re-
ceiving  either  an  packet or an packet, because it must receive
the error attribute if message is returned.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_SET_IM_VALUES_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2::unused

message  returns  the input-method-ID to distinguish replies from
multiple IMs.


[1m4.9.  Getting IM Values[0m

requests to query IM values supported by the IM Server  currently
being connected.



                                [1m19[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_GET_IM_VALUES (IM library -> IM Server)
     :2:CARD16:input-method-ID :2:n:byte length of  im-attribute-
     id :n:LISTofCARD16:im-attribute-id :p::unused, p=Pad(n)

is  a  synchronous  request.  The IM library should wait until it
receives either an packet or an packet.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_GET_IM_VALUES_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID  :2:n:byte length of im-attributes
     returned :n:LISTofXIMATTRIBUTE:im-attributes returned

The IM Server returns IM values with message.  The order  of  the
returned  im-attribute values corresponds directly to that of the
list passed with the message.


[1m4.10.  Creating an IC[0m

message requests to create an IC.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_CREATE_IC (IM library -> IM Server)
     :2:CARD16:input-method-ID  :2:n:byte length of ic-attributes
     :n:LISTofXICATTRIBUTE:ic-attributes

The input-context-id is specified by the IM  Server  to  identify
the  client  (IC).   (It  is  not specified by the client in mes-
sage.), and it should not be set to zero.

is a synchronous request which returns the input-context-ID.  The
IM library should wait until it receives either an packet  or  an
packet.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_CREATE_IC_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

[1m4.11.  Destroying the IC[0m

message requests to destroy the IC.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_DESTROY_IC (IM library -> IM Server)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

is  a synchronous request. The IM library should not free its re-
sources until it receives an message because message  may  result
in Callback packets such as and


     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).



                                [1m20[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     XIM_DESTROY_IC_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

[1m4.12.  Setting IC Values[0m

messages requests to set attributes to the IC.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_SET_IC_VALUES (IM library -> IM Server)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :2:n:byte length of ic-attributes :2::unused :n:LISTofXICAT-
     TRIBUTE:ic-attributes

The ic-attributes in message  are  specified  as  a  LISTofXICAT-
TRIBUTE,  specifying  the  attributes to be set. Attributes other
than the ones returned by message should not be specified.

is a synchronous request. The IM library should  wait  until  re-
ceiving  either  an  packet or an packet, because it must receive
the error attribute if message is returned.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_SET_IC_VALUES_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

[1m4.13.  Getting IC Values[0m

message  requests  to  query IC values supported by the IM Server
currently being connected.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_GET_IC_VALUES (IM library -> IM Server)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :2:n:byte length of  ic-attribute-id  :n:LISTofCARD16:ic-at-
     tribute-id :p::unused, p=Pad(2+n)

In  LISTofCARD16,  the  appearance of the ic-attribute-id for the
separator of NestedList shows the end of the heading nested list.

is a synchronous request and returns each attribute with its val-
ues to show the correspondence.  The IM library should wait until
receiving either an packet or an packet.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_GET_IC_VALUES_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :2:n:byte length of ic-attribute :2::unused  :n:LISTofXICAT-
     TRIBUTE:ic-attribute

[1m4.14.  Setting IC Focus[0m

message requests to set the focus to the IC.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).



                                [1m21[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     XIM_SET_IC_FOCUS (IM library -> IM Server)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

is an asynchronous request.


[1m4.15.  Unsetting IC Focus[0m

message requests to unset the focus to the focused IC.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_UNSET_IC_FOCUS (IM library -> IM Server)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

is an asynchronous request.


[1m4.16.  Filtering Events[0m

Event  filtering  is  mainly provided for BackEnd method to allow
input method to capture X events transparently to clients.

X Events are forwarded by message.  This message can be  operated
both synchronously and asynchronously.  If the requester sets the
synchronous  flag, the receiver must send message back to the re-
quester when all the data processing is done.

[1mProtocol flow of BackEnd model[0m


With BackEnd method, the protocol flow can be classified into two
methods in terms of synchronization, depending  on  the  synchro-
nous-eventmask  of message.  One can be called on-demand-synchro-
nous method and another can be called as full-synchronous method.

In on-demand-synchronous method, the IM library  always  receives
or message as a synchronous request. Also, the IM Server needs to
synchronously process the correspondent reply from the IM library
and  the  following  message sent from the IM library when any of
the event causes the IM Server to send or message to the  IM  li-
brary,  so  that  the input service is consistent.  If the IM li-
brary gets the control back from the application after  receiving
the  synchronous request, the IM library replies for the synchro-
nous request before processing any of the events. In  this  time,
the IM Server blocks message which is sent by the IM library, and
handles it after receiving the reply. However, the IM Server han-
dles the other protocols at any time.

In  full-synchronous  method, the IM library always sends message
to the IM Server as a synchronous request. Therefore,  the  reply
to  it from the IM Server will be put between the message and its
message.  In case of sending or message, the IM Server should set
the synchronous flag off. Because the synchronization can be done
by the following message.



                                [1m22[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


[1mSample Protocol flow chart 1[0m

Following chart shows one of the  simplest  protocol  flow  which
only deals with keyevents for preediting operation.

... 0.425 6.888 6.3 10.296 ... 0.000i 3.408i 5.875i 0.000i

               2Xlib API   2IM library              2IM Server
    0Key e_v_e_n-_t-0XNextEvent       ||                  ||
               0XFilter-E-v-e-n-t------|                  |
                                --| 0XIM_FORWARD_EVEN|T
                                 |                --|
    0Key e_v_e_n-_t-0XNextEvent       | 0XIM_FORWARD_E-V-EN|T0synchronous
               0XFilterEvent     | 0or XIM_COMMIT   |0request
                                --| 0(synchronous)   |
                       -----------|--              --|      ___
               0XNextEv-e-nt       |                --|0Pending ||
               0XFilterEvent (ret|urn0sXIFMa_lFsOeR)WARD_EVEN|T         |
         -_-____ 0XmbLookupString  |                  |         |
   0Application moves          --|  0XIM_SYNC     --|         |
   0the focus  0XSetICFo_c_u_s____-_-_|___0_X_I_M___S_Y_N_C___R_E_P_L-_Y-|         |
                                 |-_-________________ |0processe|d
                                 |  0XIM_SET_IC_FOCU|S0(The foc|used
                                 |                --|0IC is ch|anged)
               0XNextEvent       |0XIM_SYNC_REPLY -a-s|0aprroecpelsyse|d
                                --|0of the XIM_FORWAR|D_EVENT   |
                               --|                  |         |
                                 |               -- |0proce-s-s-e-|d



                   Fig.2 Sample Protocol Flow


[1mSample Protocol flow chart 2[0m

Following  chart  shows  one  of the complex protocol flow, which
deals with multiple focus windows and button press event as  well
as  keyevent, and the focus is moved by the application triggered
by both of keyevent and button press event.

















                                [1m23[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


... 0.425 5.575 6.3 10.296 ... 0.000i 4.721i 5.875i 0.000i

               2Xlib API   2IM library              2IM Server
    0Key e_v_e_n-_t-0XNextEvent       ||                  ||
               0XFilter-E-v-e-n-t------|                  |
                                --| 0XIM_FORWARD_EVENT|
                                 |               -- |
    0Key e_v_e_n-_t-0XNextEvent       | 0XIM_FORWARD_EVEN|T0synchronous
               0XFilterEvent     | 0or XIM_COMMIT   |0request
                                --| 0(synchronous)   |
    00Bfuotctuos_n_c_ph-ra-ensg0seXSceatuIsCeFsocus      |                --|0Pendi_n_g_
                        0Pending--|un0tXiIlM_FORWARD_EVEN|T         ||
                        0sync cyc|l-e-is d0oXnIeM_SYNC --|         |
                                 |--                |         |
                                 |-- 0XIM_SYNC_REPLY|         |
               0XNextEv-e-nt      --|-0XIM_SET_IC_FOCUS |is        |
               0XFilterEvent (r||et|ur0npsenFdalbseec)ause anot|her sync c|ycle
         -_-____ 0XmbLookupString| |0is started by XIM|_COMMIT   |
   0Application moves          | |                  |         |
   0the focus  0XSetICFo_c_u_s____-|_-_| 0XIM_SET_IC_FOCUS|         |
                               | |                --|0processe|d
                               | |                --|0(The foc|used
                               | |                  |0IC is ch|anged)
   0Key e_v_e_n_t--0XNextEvent     | |0XIM_SYNC_REPLY as|0aprroecpelsyse|d
                               | |0of the XIM_FORWAR|D_EVENT   |
               0XFilterEvent   -|--|                  |         |
                               -|+|               -- |0proce-s-s-e-|d
                               -+|   0XIM_SET_IC_FOC|US
                                 |               -- |0processed
                                 |               -- |
                                 |0XIM_FORWARD_EVENT|



                Fig.3 Sample Protocol Flow chart



     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_FORWARD_EVENT (IM library <--> IM Server)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID :2:BIT-
     MASK16:flag  ::#0001:synchronous  ::#0002:request  filtering
     (*1) ::#0004:request lookupstring (*2) :2:CARD16:serial num-
     ber ::XEVENT:X event

     (*1) Indicate the receiver should filter events and possible
          preedit may be invoked.

     (*2) Indicate the receiver should only do lookup string. The
          IM Server is expected to just do a  conversion  of  the
          key  event  to  the best candidate. This bit may affect
          the state of the preedit state (e.g.  compose  of  dead
          key sequences).




                                [1m24[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


XEVENT format is same as the X Protocol event format(xEvent).  As
the  value  of xEvent's sequenceNumber is the bottom of 16 bit of
XEvent's xany.serial, the top of 16 bit is sent  by  serial  num-
ber(INT16).

message  is used for forwarding the events from the IM library to
the IM Server in order for IM to be able to filter the event.  On
the  other  hand,  this  message  is also used for forwarding the
events from the IM Server to the IM library  if  the  event  for-
warded from the IM library is not filtered.  The IM Server, which
receives  message without synchronous bit, should set synchronous
bit.  If both ``request event filtering'' and  ``request  lookup-
string''  flag  are set, then both filtering and lookup should be
done for the same event.


[1m4.17.  Synchronizing with the IM Server[0m

message requests to synchronize the IM library and the IM Server.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_SYNC (IM library <--> IM Server)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

This synchronization can be started either on the IM library side
or on the IM Server side.  The side which receives message should
process all XIM requests before replying. The input-context-ID is
necessary to distinguish the IC with which the IM library and the
IM Server are synchronized.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_SYNC_REPLY (IM Server <--> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

The side which receives or any  other  message  with  synchronous
bit,  should  process  all  XIM request before replying, and send
message as the reply to the previous message.


[1m4.18.  Sending a committed string[0m

When the IM Server commits a string, the IM Server  sends  either
the committed string or list of KeySym, or both, by message.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_COMMIT (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID :2:BIT-
     MASK16:flag     ::#0001:synchronous     ::#0002:XLookupChars
     ::#0004:XLookupKeySym  ::#0006: XLookupBoth = XLookupChars |
     XLookupKeySym

     If flag is XLookupKeySym, the arguments continue as follows:

     tab(:); lw(.25i) lw(.25i)  lw(1.75i)  lw(3.5i).   :2::unused



                                [1m25[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     :4:KEYSYM:KeySym

     If flag is XLookupChars, the arguments continue as follows:

     tab(:);  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).  :2:m:byte
     length of committed  string  :m:LISTofBYTE:committed  string
     :p::unused, p = Pad(m)

     If flag is XLookupBoth, the arguments continue as follows:

     tab(:);  lw(.25i)  lw(.25i)  lw(1.75i) lw(3.5i).  :2::unused
     :4:KEYSYM:KeySym  :2:n:byte  length  of   committed   string
     :n:LISTofBYTE:committed string :p::unused, p = Pad(2+n)

The  IM  Server  which  receives  message without synchronous bit
should set synchronous bit.


[1m4.19.  Reset IC[0m

message requests to reset the status of IC in the IM Server.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_RESET_IC (IM library -> IM Server)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

is  a  synchronous  request. The IM library should wait until re-
ceiving either an packet or an packet.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_RESET_IC_REPLY (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :2:n:byte length  of  preedit  string  :n:LISTofBYTE:preedit
     string :p::unused, p = Pad(2+n)

message  returns the input-context-ID to distinguish replies from
multiple ICs.


[1m4.20.  Callbacks[0m

If XIMStyle has XIMPreeditArea or  XIMStatusArea  set,  XIMGeome-
tryCallback may be used, and if XIMPreeditCallback and/or XIMSta-
tusCallback are set, corresponding callbacks may be used.

Any  callback  request  may  be  sent  from an IM Server to an IM
client asynchronously in response to any request previously  sent
by the IM client to the IM Server.

When  an IM Server needs to send a callback request synchronously
with the request previously sent by an IM client, the  IM  Server
sends it before replying to the previous request.




                                [1m26[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


[1m4.20.1.  Negotiating geometry[0m

The  IM  Server  sends  message to start geometry negotiation, if
XIMStyle has XIMPreeditArea or XIMStatusArea set.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_GEOMETRY (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

There  is always a single Focus Window, even if some input fields
have only one IC.


[1m4.20.2.  Converting a string[0m


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_STR_CONVERSION (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :2:CARD16:XIMStringConversionPosition             :2::unused
     :4:CARD32:XIMCaretDirection   ::#0:XIMForwardChar  ::#1:XIM-
     BackwardChar    ::#2:XIMForwardWord     ::#3:XIMBackwardWord
     ::#4:XIMCaretUp ::#5:XIMCaretDown ::#6:XIMNextLine ::#7:XIM-
     CPreviousLine ::#8:XIMLineStart ::#9:XIMLineEnd ::#10:XIMAb-
     solutePosition      ::#11:XIMDontChange     :2:CARD16:factor
     :2:CARD16:XIMStringConversionOperation ::#0001:XIMStringCon-
     versionSubstitution     ::#0002:XIMStringConversionRetrieval
     :2:INT16:T{ byte length to multiply the XIMStringConversion-
     Type T}

message  may  be  used to start the string conversion from the IM
Server.


     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_STR_CONVERSION_REPLY (IM library -> IM Server)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:CARD32:XIMStringConversionFeedback  ::XIMSTRCONVTEXT:XIM-
     StringConversionText


message  returns  the string to be converted and the feedback in-
formation array.


[1m4.20.3.  Preedit Callbacks[0m

The IM Server sends message to call  the  XIMPreeditStartCallback
function.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_PREEDIT_START (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID




                                [1m27[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


The reply to this message must be sent synchronously.  The  reply
forwards  the  return  value from the callback function to the IM
Server.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_PREEDIT_START_REPLY (IM library -> IM Server)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:INT32:return value

message returns the input-context-ID to distinguish replies  from
multiple IC's.  The return value contains the return value of the
function XIMPreeditStartCallback.

The  IM  Server  sends message to call the XIMPreeditDrawCallback
function.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_PREEDIT_DRAW (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:INT32:caret    :4:INT32:chg_first     :4:INT32:chg_length
     :4:BITMASK32:status   ::#x0000001:no  string  ::#x0000002:no
     feedback :2:n:length of  preedit  string  :n:STRING8:preedit
     string :p::unused, p = Pad(2+n) :2:m:byte length of feedback
     array :2::unused :m:LISTofXIMFEEDBACK:feedback array

The fields ``caret'', ``chg_first'' and ``chg_length'' correspond
to  the  fields  of  XIMPreeditDrawCallbackStruct.  When the ``no
string'' bit of the status field is set, the text field  of  XIM-
PreeditDrawCallbackStruct  is NULL.  When the ``no feedback'' bit
of the status field is set, the text feedback field of  XIMPreed-
itDrawCallbackStruct  is  NULL.  When the above bits are not set,
``preedit string'' contains the preedit string to  be  displayed,
and the feedback array contains feedback information.

The  IM  Server  sends  message  to call the PreeditCaretCallback
function.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_PREEDIT_CARET (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:INT32:position  :4:CARD32:direction   ::#0:XIMForwardChar
     ::#1:XIMBackwardChar  ::#2:XIMForwardWord  ::#3:XIMBackward-
     Word  ::#4:XIMCaretUp   ::#5:XIMCaretDown   ::#6:XIMNextLine
     ::#7:XIMCPreviousLine    ::#8:XIMLineStart   ::#9:XIMLineEnd
     ::#10:XIMAbsolutePosition                ::#11:XIMDontChange
     :4:CARD32:style ::#0:XIMInvisible ::#1:XIMCPrimary ::#2:XIM-
     Secondary

Each  entry  corresponds  to  a field of XIMPreeditCaretCallback-
Struct.  Since this callback sets the caret position,  its  reply
must be sent synchronously.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_PREEDIT_CARET_REPLY (IM library -> IM Server)



                                [1m28[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:CARD32:position

The position is the value returned by the callback function after
it has been called.

The  IM  Server  sends message to call the XIMPreeditDoneCallback
function.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_PREEDIT_DONE (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

[1m4.20.4.  Preedit state notify[0m

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_PREEDITSTATE (IM Server -> IM Library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID :4:BIT-
     MASK32:XIMPreeditState         ::#x0000000:XIMPreeditUnknown
     ::#x0000001:XIMPreeditEnable ::#x0000002:XIMPreeditDisable

message  is  used to call the XIMPreeditStateNotifyCallback func-
tion.


[1m4.20.5.  Status Callbacks[0m

The IM Server sends message to  call  the  XIMStatusStartCallback
function.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_STATUS_START (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

The IM Server sends message  to  call  the  XIMStatusDrawCallback
function.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_STATUS_DRAW (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:CARD32:type ::#0:XIMTextType ::#1:XIMBitmapType

     If type is XIMTextType, the arguments continue as follows.

     tab(:);   lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).   :4:BIT-
     MASK32:status ::#x0000001:no string ::#x0000002:no  feedback
     :2:n:length   of   status  string  :n:STRING8:status  string
     :p::unused, p = Pad(2+n) :2:m:byte length of feedback  array
     :2::unused :m:LISTofXIMFEEDBACK:feedback array

     If type is XIMBitmapType, the arguments continue as follows.

     tab(:);     lw(.25i)     lw(.25i)     lw(1.75i)    lw(3.5i).
     :4:PIXMAP:pixmap data



                                [1m29[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


The field ``type'' corresponds to the field in XIMStatusDrawCall-
backStruct.

The IM Server sends message  to  call  the  XIMStatusDoneCallback
function.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_STATUS_DONE (IM Server -> IM library)
     :2:CARD16:input-method-ID :2:CARD16:input-context-ID

[1m5.  Acknowledgements[0m

This document represents the culmination of several years of  de-
bate and experiments done under the auspices of the MIT X Consor-
tium  i18n  working group.  Although this was a group effort, the
author remains responsible for any errors or omissions.

We would like to thank to all members  of  this  group.   And  we
would like to make special thanks to the following people (in al-
phabetical  order) for their participation in the IM Protocol de-
sign, Hector Chan, Takashi Fujiwara, Yoshio Horiuchi, Makoto  In-
ada,  Hiromu Inukai, Mickael Kung, Seiji Kuwari, Franky Ling, Hi-
royuki Machida, Hiroyuki Miyamoto, Frank  Rojas,  Bob  Scheifler,
Makiko   Shimamura,  Shoji  Sugiyama,  Hidetoshi  Tajima,  Masaki
Takeuchi,  Makoto  Wakamatsu,  Masaki  Wakao,  Nobuyuki   Tanaka,
Shigeru Yamada, Katsuhisa Yano, Jinsoo Yoon.


[1m6.  References[0m

All  of the following documents are X Consortium standards avail-
able from MIT:

[1] Scheifler, Robert W., [4m``X[24m [4mWindow[24m [4mSystem[24m [4mProtocol[24m [4mVersion[24m [4m11''[0m

[2] Scheifler, Robert W. etc., [4m``Xlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m [4mInterface''[0m





















                                [1m30[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


                           [1mAppendix A[0m

                        [1mCommon Extensions[0m


Extension opcodes and packet names (e.g.  ) for additional exten-
sions may be registered with X Consortium.  The  following  is  a
commonly well-known extended packet.



[1m(1)  [22mExtension to manipulate the event handling

message  specifies  the  set  of  event masks that the IM library
should manipulate.

     tab(:); lfB s s  s  lw(.25i)  lw(.25i)  lw(1.75i)  lw(3.5i).
     XIM_EXT_SET_EVENT_MASK (IM Server -> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :4:EVENTMASK:filter-event-mask (*1)  :4:EVENTMASK:intercept-
     event-mask    (*2)    :4:EVENTMASK:select-event-mask    (*3)
     :4:EVENTMASK:forward-event-mask  (*4)  :4:EVENTMASK:synchro-
     nous-event-mask (*5)

     (*1) Specify  the  events  to be neglected by the IM library
          via XFilterEvent.

     (*2) Specify the events to be deselected by the  IM  library
          with XSelectInput.

     (*3) Specify  the  events  to  be selected by the IM library
          with XSelectInput.

     (*4) Specify all the events to be forwarded to the IM Server
          by the IM library.

     (*5) Specify the events to  be  forwarded  with  synchronous
          flag on by the IM library.

The  IM library must reply message to the IM Server. This request
is valid after the ic is created.



[1m(2)  [22mExtension for improvement of performance

The following requests may be used  for  improvement  of  perfor-
mance.

message may be used instead of message.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_EXT_FORWARD_KEYEVENT (IM Server <--> IM library)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID



                                [1m31[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     :2:BITMASK16:flag   ::#0001:synchronous   :2:CARD16:sequence
     number        :1:BYTE:xEvent.u.u.type        :1:BYTE:keycode
     :2:CARD16:state :4:CARD32:time :4:CARD32:window

message  may  be  used  to  change  the  spot location instead of
XIM_SET_IC_VALUES message.  It is effective only  if  the  client
specified XIMPreeditPosition.

     tab(:);  lfB  s  s  s  lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
     XIM_EXT_MOVE (IM library -> IM Server)
     :2:CARD16:input-method-ID         :2:CARD16:input-context-ID
     :2:INT16:X :2:INT16:Y

message is a asynchronous request.











































                                [1m32[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


                           [1mAppendix B[0m

[1mThe list of transport specific IM Server address format registered[0m


The  following  format  represents the ATOM contained in property
and the string returned from  the  request  converting  selection
target LOCALES and TRANSPORT.

          ``{@[4mcategory[24m=[[4mvalue[24m,...]}...''

The following categories are currently registered.

     tab(;); l l.  [1mserver[22m;: IM Server name (used for XIM_SERVERS)
     [1mlocale[22m;:  XPG4  locale name (LOCALES) [1mtransport[22m;: transport-
     specific name (TRANSPORT)

The preregistered formats for  transport-specific  names  are  as
follows:

     [1mTCP/IP Names[0m

          The following syntax should be used for system internal
          domain names:

               <[4mlocal[24m [4mname[24m>  ::= ``local/''<[4mhostname[24m>``:''<[4mpathname[24m>

          Where <[4mpathname[24m> is a path name of socket address.

          IM  Server's  name  should  be set to <[4mpathname[24m> to run
          multiple IM Server at the same time

          The following syntax should be used for Internet domain
          names:

               <[4mTCP[24m [4mname[24m>  ::=  ``tcp/''<[4mhostname[24m>``:''<[4mipportnumber[24m>

          where  <[4mhostname[24m>   is   either   symbolic   (such   as
          expo.lcs.mit.edu)   or   numeric   decimal   (such   as
          18.30.0.212).  The <[4mipportnumber[24m> is the port on  which
          the  IM Server is listening for connections.  For exam-
          ple:

               tcp/expo.lcs.mit.edu:8012
               tcp/18.30.0.212:7890

     [1mDECnet Names[0m

          The following syntax should be used for DECnet names:

               <[4mDECnet[24m [4mname[24m>  ::=  ``decnet/''<[4mnodename[24m>``::IMSERVER$''<[4mobjname[24m>

          where <[4mnodename[24m> is either symbolic (such as SRVNOD) or
          the numeric decimal form of the DECnet address (such as



                                [1m33[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          44.70).  The <[4mobjname[24m> is normal, case-insensitive DEC-
          net object name. For example:

               DECNET/SRVNOD::IMSERVER$DEFAULT
               decnet/44.70::IMSERVER$other

     [1mX Names[0m

          The following syntax should be used for X names:

               <[4mX[24m [4mname[24m>  ::=  ``X/''

If a given category has multiple values, the value  is  evaluated
in order of setting.











































                                [1m34[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


                           [1mAppendix C[0m

                         [1mProtocol number[0m


[1mMajor Protocol number[0m

center,   tab(:);  lw(9c)  l.   XIM_CONNECT:#001  XIM_CONNECT_RE-
PLY:#002 XIM_DISCONNECT:#003 XIM_DISCONNECT_REPLY:#004

XIM_AUTH_REQUIRED:#010   XIM_AUTH_REPLY:#011   XIM_AUTH_NEXT:#012
XIM_AUTH_SETUP:#013 XIM_AUTH_NG:#014

XIM_ERROR:#020

XIM_OPEN:#030  XIM_OPEN_REPLY:#031  XIM_CLOSE:#032  XIM_CLOSE_RE-
PLY:#033  XIM_REGISTER_TRIGGERKEYS:#034   XIM_TRIGGER_NOTIFY:#035
XIM_TRIGGER_NOTIFY_REPLY:#036  XIM_SET_EVENT_MASK:#037 XIM_ENCOD-
ING_NEGOTIATION:#038          XIM_ENCODING_NEGOTIATION_REPLY:#039
XIM_QUERY_EXTENSION:#040           XIM_QUERY_EXTENSION_REPLY:#041
XIM_SET_IM_VALUES:#042               XIM_SET_IM_VALUES_REPLY:#043
XIM_GET_IM_VALUES:#044 XIM_GET_IM_VALUES_REPLY:#045

XIM_CREATE_IC:#050  XIM_CREATE_IC_REPLY:#051  XIM_DESTROY_IC:#052
XIM_DESTROY_IC_REPLY:#053 XIM_SET_IC_VALUES:#054  XIM_SET_IC_VAL-
UES_REPLY:#055    XIM_GET_IC_VALUES:#056    XIM_GET_IC_VALUES_RE-
PLY:#057 XIM_SET_IC_FOCUS:#058  XIM_UNSET_IC_FOCUS:#059  XIM_FOR-
WARD_EVENT:#060 XIM_SYNC:#061 XIM_SYNC_REPLY:#062 XIM_COMMIT:#063
XIM_RESET_IC:#064 XIM_RESET_IC_REPLY:#065

XIM_GEOMETRY:#070  XIM_STR_CONVERSION:#071 XIM_STR_CONVERSION_RE-
PLY:#072   XIM_PREEDIT_START:#073    XIM_PREEDIT_START_REPLY:#074
XIM_PREEDIT_DRAW:#075                      XIM_PREEDIT_CARET:#076
XIM_PREEDIT_CARET_REPLY:#077    XIM_PREEDIT_DONE:#078    XIM_STA-
TUS_START:#079      XIM_STATUS_DRAW:#080     XIM_STATUS_DONE:#081
XIM_PREEDITSTATE:#082

(*) The IM Server's extension protocol number should be more than
#128.


















                                [1m35[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


                           [1mAppendix D[0m

                       [1mImplementation Tips[0m



[1m(1)  [22mFrontEnd Method

FrontEnd method is recognized as a  performance  acceleration  by
the trade off of the variety of the reliability.

In  order  to  use the FrontEnd method, the IM library must query
the IM Server to see if the FrontEnd extension is available.  The
query is made by using the message. The IM Server may  send  mes-
sage  with intercept-event-mask, forward-event-mask, and synchro-
nous-event-mask values set after replying message.

FrontEnd method can be implemented in a couple of ways  depending
on how the IM Server utilize message.

One  approach is to update both of the input mask and the filter-
event-mask depending on the preeidting state. The sample protocol
sequence using the static event flow is as follows:


... 1.675 6.888 6.237 10.296 ... 0.000i 3.408i 4.562i 0.000i

                   2IM library                 2IM Server
          0Keys in the on-||key-list             ||
                ________-_-|__0_X_I_M___F_O_R_W_A_R_D___E_V-_E-NT |
                          |-_-________________   |
                          |0XIM_EXT_SET_EVENT_M|ASK
            0event mask is|ch0ainngteedrcept-event-m|a0sekveinstsmeatsk is changed
            0to deselect t|he event             |0to select the event
                          |                    |
                          |                    |-_-______
                          |                    |--
                          |                    | 0X events directly come
                          |                    | 0to the IM Server.
                          |                    | 0when preediting is turning off
                          |-_-________________   |
            0event mask is|0cXhIaMn_gEeXdT_SET_EVENT_M|AS0Kevent mask is changed
            0to select the|ev0esnetlect-event-mask|i0stosedteselect the event
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          |                    |



To pursuit a maximum performance  regardless  of  the  preediting
mode,  the IM Server may use the dynamic event flow with the fol-
lowing sample protocol sequence.



                                [1m36[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


... 1.675 6.888 6.237 10.296 ... 0.000i 3.408i 4.562i 0.000i

                   2IM library                 2IM Server
          0Keys in the on-||key-list             ||
                ________-_-|__0_X_I_M___T_R_I_G_G_E_R___N_O-_T-IFY|
                          |-_-________________   |
                          |0XIM_EXT_SET_EVENT_M|ASK
            0event mask is|ch0ainngteedrcept-event-m|a0sekveinstsmeatsk is changed
            0to deselect t|h0eXIeMv_eTnRtIGGER_NOTIFY_|R0EtPoLYselect the event
                          |-_-________________   |
                          |                    |-_-______
                          |                    |--
                          |                    | 0X events directly come
                          |                    | 0to the IM Server.
                          |                    | 0when preediting is turning off
                          |-_-________________   |
            0event mask is|0cXhIaMn_gEeXdT_SET_EVENT_M|AS0Kevent mask is changed
            0to select the|ev0esnetlect-event-mask|i0stosedteselect the event
                          |                    |
                          |                    |
                          |                    |
                          |                    |
                          |                    |


This method can reduce the XIM protocol traffic  dramatically  by
updating  intercept-event-mask and select-event-mask accordingly.
The tradeoff of this performance  improvement  is  that  the  key
events  may  be  lost or disordered in some particular situation,
such as when the user types the keyboard  in  following  sequence
really fast:
     <preediting on key>``some strings''<preediting off key>``an-
     other string''
Since this method requires the input mask updates to the both the
IM  Server  and  Xlib when turning on and off the preediting, and
there is a time lag till the requests take effect when two client
issues the input mask updates simultaneously.

Another approach of the FrontEnd method is to update the  filter-
event-mask  depending  on  the preediting state and not to update
the input mask.  The IM Server must register both of the preedit-
ing on key list and off key list by  message.   In  this  method,
Both  the  IM  Server and the IM client select the same events on
the same client's window, so that the  events  are  delivered  to
both  of  the IM Server and the client. The preediting on and off
states are expressed by whether the key events  are  filtered  or
not.  The sample protocol sequence are as follows:










                                [1m37[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


<<Using static event flow>>


... 1.488 7.325 6.487 10.358 ... 0.000i 3.033i 4.999i 0.000i

                  2IM library                 2IM Server

       0Keys in__t_h_e__o_n_--_k-||ey_-_l0_iX_sI_tM___F_O_R_W_A_R_D___E_V-_E-NT ||-_-__0_K_e_y_s__i_n the on-key-list
                        | -_-_______________-_-  |--
                        | 0XIM_EXT_SET_EVENT_M|ASK
             0the specif|ied 0efvielnttesr-event-mask|i0sthseetspecified events
             0are being |filtered              | 0are being processed
                        |                     |
                        |                     |
        0Keys in the off|-key-list             |  0Keys in the off-key-list
               ________-_-|                     |-_-_________
                        |  -_-________________  |
                        | 0XI0Mf_iElXtTe_rS-EeTv_eEnVtE-NmTa_sMk|ASiKs set
                        |                     |
             0the specif|ied events            | 0the specified events
             0are being |processed             | 0are being discarded
                        |                     |
                        |                     |
                        |                     |
                        |                     |

<<Using the dynamic event flow>>

... 1.488 7.325 6.487 10.358 ... 0.000i 3.033i 4.999i 0.000i

                  2IM library                 2IM Server

       0Keys in__t_h_e__o_n_--_k-||ey_-_0l_Xi_Is_Mt___T_R_I_G_G_E_R___N_O-_T-IFY||-_-__0_K_e_y_s__i_n the on-key-list
                        | -_-_______________-_-  |--
                        | 0XIM_EXT_SET_EVENT_M|ASK
             0the specif|ied 0efvielnttesr-event-mask|i0sthseetspecified events
             0are being |filtered              | 0are being processed
                        | 0XIM_TRIGGER_NOTIFY_|REPLY
                        | -_-________________   |
        0Keys in the off|-key-list             |  0Keys in the off-key-list
               ________-_-|                     |-_-_________
                        |  -_-________________  |
                        | 0XI0Mf_iElXtTe_rS-EeTv_eEnVtE-NmTa_sMk|ASiKs set
                        |                     |
             0the specif|ied events            | 0the specified events
             0are being |processed             | 0are being discarded
                        |                     |
                        |                     |
                        |                     |
                        |                     |


This  method does not have the problem of the time lag when going
across the preediting on and off mode, however, the amount of the



                                [1m38[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


performance acceleration is not as good as the  method  described
above.

In  general, the FrontEnd method requires some synchronization to
some of the X protocols, such as the ChangeWindowAttribute proto-
col for the event mask change or the GrabKey protocol,  since  it
relies  on  the  X's principal event dispatching mechanism. Any X
protocol bindings do not consider the synchronization might cause
some mis-synchronization  between  the  IM  clients  and  the  IM
Server.















































                                [1m39[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


[1m(2)  [22mTransport Layer

The  Xlib  XIM  implementation is layered into three functions, a
protocol layer, an interface layer and  a  transport  layer.  The
purpose  of  this layering is to make the protocol independent of
transport implementation.  Each function of these layers are:

     [4mThe[24m [4mprotocol[24m [4mlayer[0m
          implements overall function of XIM and calls the inter-
          face layer functions when it needs to communicate to IM
          Server.

     [4mThe[24m [4minterface[24m [4mlayer[0m
          separates the implementation  of  the  transport  layer
          from  the  protocol  layer, in other words, it provides
          implementation independent hook for the transport layer
          functions.

     [4mThe[24m [4mtransport[24m [4mlayer[0m
          handles actual data communication with IM Server. It is
          done by a set of several functions named transporters.

The interface layer and the transport layer make various communi-
cation channels usable such as  X  Protocol,  TCP/IP,  DECnet  or
STREAM.   The following is a sample implementation for the trans-
porter using the X connection.  Refer to "xtrans" for the  trans-
porter using Socket Transport.

At the beginning of the X Transport connection for the XIM trans-
port  mechanism,  two different windows must be created either in
an Xlib XIM or in an IM Server, with which the Xlib  and  the  IM
Server  exchange  the  XIM  transports by using the ClientMessage
events and Window Properties.  In the following, the window  cre-
ated  by  the  Xlib is referred as the "client communication win-
dow", and on the other hand, the window created by the IM  Server
is referred as the "IMS communication window".

[1mConnection[0m

     In  order  to establish a connection, a communication window
     is created.  A ClientMessage in the following event's format
     is sent to the owner window of XIM_SERVER  selection,  which
     the IM Server has created.

     Refer  to  "The  Input  Method  Protocol" for the XIM_SERVER
     atom.

         Table D-1; The ClientMessage sent to the IMS window.

     tab(:); l s|l l l|l.  _
     [1mStructure Member:Contents[0m
     [1m_[0m
     int:type:ClientMessage u_long:serial:Set  by  the  X  Window
     System   Bool:send_event:Set   by   the   X   Window  System



                                [1m40[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


     tab(:); l s|l l l|l.  _
     [1mStructure Member:Contents[0m
     [1m_[0m
     Display:*display:The display to which  connects  Window:win-
     dow:IMS   Window  ID  Atom:message_type:XInternAtom(display,
     ``_XIM_XCONNECT'',           False)            int:format:32
     long:data.l[0]:client      communication      window      ID
     long:data.l[1]:client-major-transport-version           (*1)
     long:data.l[2]:client-major-transport-version (*1)
     _

     In  order  to  establish  the  connection  (to notify the IM
     Server  communication  window),  the  IM  Server   sends   a
     ClientMessage  in the following event's format to the client
     communication window.










































                                [1m41[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


           Table D-2; The ClientMessage sent by IM Server.

     tab(:); l s | l l l | l.  _
     [1mStructure Member:Contents[0m
     [1m_[0m
     int:type:ClientMessage u_long:serial:Set  by  the  X  Window
     System  Bool:send_event:Set  by  the  X  Window  System Dis-
     play:*display:The  display  to  which  connects  Window:win-
     dow:client communication window ID Atom:message_type:XInter-
     nAtom(display,   ``_XIM_XCONNECT'',   False)   int:format:32
     long:data.l[0]:IMS       communication       window       ID
     long:data.l[1]:server-major-transport-version           (*1)
     long:data.l[2]:server-minor-transport-version           (*1)
     long:data.l[3]:dividing size between ClientMessage and Prop-
     erty (*2)
     _

     (*1) major/minor-transport-version
               The  read/write  method is decided by the combina-
               tion of major/minor-transport-version, as follows:

          Table D-3; The read/write method and the major/minor-transport-version

          center, tab(:); | c s | l | | c | c | l |.  _
          [1mTransport-version:read/write[0m
          [1m_[0m
          [1mmajor:minor:[0m
          [1m_[0m
          0:0:only-CM & Property-with-CM  :1:only-CM  &  multi-CM
          :2:only-CM & multi-CM & Property-with-CM
          _
          1:0:PropertyNotify
          _
          2:0:only-CM  &  PropertyNotify  :1:only-CM & multi-CM &
          PropertyNotify
          _

               center, tab(;); l n l.  only-CM;:;data is sent via
               a ClientMessage multi-CM;:;data is sent via multi-
               ple ClientMessages Property-with-CM;:;T{  data  is
               written  in  Property,  and  its  Atom is send via
               ClientMessage T} PropertyNotify;:;T{ data is writ-
               ten in Property, and its Atom is send via  Proper-
               tyNotify T}

          The  method  to decide major/minor-transport-version is
          as follows:


          (1)  The client sends 0  as  major/minor-transport-ver-
               sion  to  the  IM Server.  The client must support
               all methods in Table D-3.  The client may send an-
               other number as  major/minor-transport-version  to
               use other method than the above in the future.



                                [1m42[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          (2)  The IM Server sends its major/minor-transport-ver-
               sion  number  to the client. The client sends data
               using the method specified by the IM Server.

          (3)  If  major/minor-transport-version  number  is  not
               available, it is regarded as 0.


     (*2) dividing size between ClientMessage and Property
               If data is sent via both of multi-CM and Property,
               specify  the  dividing  size between ClientMessage
               and Property. The data, which is smaller than this
               size, is sent via multi-CM (or only-CM),  and  the
               data,  which  is lager than this size, is sent via
               Property.



[1mread/write[0m

     The data is transferred via either ClientMessage  or  Window
     Property in the X Window System.

     [1mFormat for the data from the Client to the IM Server[0m

          [1mClientMessage[0m

          If  data is sent via ClientMessage event, the format is
          as follows:

          Table D-4; The ClientMessage event's format (first or middle)

          tab(;); l s | l l l | l.  _
          [1mStructure Member;Contents[0m
          [1m_[0m
          int;type;ClientMessage u_long;serial;Set by the X  Win-
          dow  System  Bool;send_event;Set by the X Window System
          Display;*display;The display  to  which  connects  Win-
          dow;window;IMS   communication   window   ID  Atom;mes-
          sage_type;XInternAtom(display,       ``_XIM_MOREDATA'',
          False)  int;format;8 char;data.b[20];(read/write DATA :
          20 byte)
          _

          Table D-5; The ClientMessage event's format (only or last)

          tab(;); l s | l l l | l.  _
          [1mStructure Member;Contents[0m
          [1m_[0m
          int;type;ClientMessage u_long;serial;Set by the X  Win-
          dow  System  Bool;send_event;Set by the X Window System
          Display;*display;The display  to  which  connects  Win-
          dow;window;IMS   communication   window   ID  Atom;mes-
          sage_type;XInternAtom(display,       ``_XIM_PROTOCOL'',



                                [1m43[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          tab(;); l s | l l l | l.  _
          [1mStructure Member;Contents[0m
          [1m_[0m
          False)  int;format;8 char;data.b[20];(read/write DATA :
          MAX 20 byte)  (*1)
          _

          (*1) If the data is smaller  than  20  byte,  all  data
               other than available data must be 0.

          [1mProperty[0m

          In  the  case  of large data, data will be sent via the
          Window Property for the efficiency.  There are the fol-
          lowing two methods to notify Property,  and  transport-
          version is decided which method is used.


          (1)  The XChangeProperty function is used to store data
               in  the  client  communication window, and Atom of
               the stored data is notified to the IM  Server  via
               ClientMessage event.

          (2)  The XChangeProperty function is used to store data
               in  the  client  communication window, and Atom of
               the stored data is notified to the IM  Server  via
               PropertyNotify event.

          The arguments of the XChangeProperty are as follows:




























                                [1m44[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


               Table D-6; The XChangeProperty event's format

          tab(:); l s | l l l | l.  _
          [1mArgument:Contents[0m
          [1m_[0m
          Display:*display:The  display  to  which  connects Win-
          dow:window:IMS  communication  window   ID   Atom:prop-
          erty:read/write  property Atom (*1) Atom:type:XA_STRING
          int:format:8                    int:mode:PropModeAppend
          u_char:*data:read/write  DATA  int:nelements:length  of
          DATA
          _

          (*1) The read/write property ATOM allocates the follow-
               ing strings by [1mXInternAtom[22m.
                    ``_clientXXX''

          The client changes the property with the mode of  Prop-
          ModeAppend  and  the  IM  Server  will read it with the
          delete mode i.e. (delete = True).

          If Atom is notified via ClientMessage event, the format
          of the ClientMessage is as follows:

          Table D-7; The ClientMessage  event's  format  to  send
                             Atom of property

          tab(:); l s | l l l | l.  _
          [1mStructure Member:Contents[0m
          [1m_[0m
          int:type:ClientMessage  u_long:serial:Set by the X Win-
          dow System Bool:send_event:Set by the X  Window  System
          Display:*display:The  display  to  which  connects Win-
          dow:window:IMS  communication   window   ID   Atom:mes-
          sage_type:XInternAtom(display,       ``_XIM_PROTOCOL'',
          False)    int:format:32    long:data.l[0]:length     of
          read/write   property   Atom  long:data.l[1]:read/write
          property Atom
          _

     [1mFormat for the data from the IM Server to the Client[0m

          [1mClientMessage[0m

          The format of the ClientMessage is as follows:

          Table D-8; The ClientMessage event's format (first or middle)

          tab(;); l s | l l l | l.  _
          [1mStructure Member;Contents[0m
          [1m_[0m
          int;type;ClientMessage u_long;serial;Set by the X  Win-
          dow  System Bool;send_event ;Set by the X Window System
          Display;*display;The   display   to   which    connects



                                [1m45[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          tab(;); l s | l l l | l.  _
          [1mStructure Member;Contents[0m
          [1m_[0m
          Window;window;client  communication window ID Atom;mes-
          sage_type;XInternAtom(display,       ``_XIM_MOREDATA'',
          False)  int;format;8 char;data.b[20];(read/write DATA :
          20 byte)
          _

          Table D-9; The ClientMessage event's format (only or last)

          tab(;); l s | l l l | l.  _
          [1mStructure Member;Contents[0m
          [1m_[0m
          int;type;ClientMessage u_long;serial;Set by the X  Win-
          dow  System Bool;send_event ;Set by the X Window System
          Display;*display;The display  to  which  connects  Win-
          dow;window;client  communication  window  ID  Atom;mes-
          sage_type;XInternAtom(display,       ``_XIM_PROTOCOL'',
          False)  int;format;8 char;data.b[20];(read/write DATA :
          MAX 20 byte) (*1)
          _

          (*1) If the data size is smaller  than  20  bytes,  all
               data other than available data must be 0.

          [1mProperty[0m

          In  the  case  of large data, data will be sent via the
          Window Property for the efficiency. There are the  fol-
          lowing  two  methods to notify Property, and transport-
          version is decided which method is used.


          (1)  The XChangeProperty function is used to store data
               in the IMS communication window, and Atom  of  the
               property is sent via the ClientMessage event.

          (2)  The XChangeProperty function is used to store data
               in  the  IMS communication window, and Atom of the
               property is sent via PropertyNotify event.

          The arguments of the XChangeProperty are as follows:

              Table D-10; The XChangeProperty event's format

          tab(:); l s | l l l | l.  _
          [1mArgument:Contents[0m
          [1m_[0m
          Display:*display:The display  which  to  connects  Win-
          dow:window:client  communication  window  ID Atom:prop-
          erty:read/write property Atom (*1)  Atom:type:XA_STRING
          int:format:8                    int:mode:PropModeAppend
          u_char:*data:read/write  DATA  int:nelements:length  of



                                [1m46[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          tab(:); l s | l l l | l.  _
          [1mArgument:Contents[0m
          [1m_[0m
          DATA
          _

          (*1) The   read/write   property  ATOM  allocates  some
               strings, which are not allocated by the client, by
               [1mXInternAtom[22m.

          The IM Server changes the property  with  the  mode  of
          PropModeAppend  and the client reads it with the delete
          mode, i.e. (delete = True).

          If Atom is notified via ClientMessage event, the format
          of the ClientMessage is as follows:









































                                [1m47[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m


          Table D-11; The ClientMessage event's  format  to  send
                             Atom of property

          tab(:); l s | l l l | l.  _
          [1mStructure Member:Contents[0m
          [1m_[0m
          int:type:ClientMessage  u_long:serial:Set by the X Win-
          dow System Bool:send_event:Set by the X  Window  System
          Display:*display:The  display  to  which  connects Win-
          dow:window:client  communication  window  ID  Atom:mes-
          sage_type:XInternAtom(display,       ``_XIM_PROTOCOL'',
          False)    int:format:32    long:data.l[0]:length     of
          read/write   property   ATOM  long:data.l[1]:read/write
          property ATOM
          _

[1mClosing Connection[0m

     If the client disconnect with the IM Server, shutdown  func-
     tion  should  free  the  communication window properties and
     etc..




































                                [1m48[0m





[1mX Input Method Protocol                          X11, Release 6.1[0m



                        [1mTable of Contents[0m


1. Introduction . . . . . . . . . . . . . . . . . . . . . . .   1
1.1. Scope  . . . . . . . . . . . . . . . . . . . . . . . . .   1
1.2. Background . . . . . . . . . . . . . . . . . . . . . . .   1
1.3. Input Method Styles  . . . . . . . . . . . . . . . . . .   2
2. Architecture . . . . . . . . . . . . . . . . . . . . . . .   3
2.1. Implementation Model . . . . . . . . . . . . . . . . . .   3
2.2. Structure of IM  . . . . . . . . . . . . . . . . . . . .   3
2.3. Event Handling Model . . . . . . . . . . . . . . . . . .   4
2.3.1. BackEnd Method . . . . . . . . . . . . . . . . . . . .   4
2.3.2. FrontEnd Method  . . . . . . . . . . . . . . . . . . .   4
2.4. Event Flow Control . . . . . . . . . . . . . . . . . . .   6
3. Default Preconnection Convention . . . . . . . . . . . . .   7
4. Protocol . . . . . . . . . . . . . . . . . . . . . . . . .   7
4.1. Basic Requests Packet Format . . . . . . . . . . . . . .   7
4.2. Data Types . . . . . . . . . . . . . . . . . . . . . . .   8
4.3. Error Notification . . . . . . . . . . . . . . . . . . .  11
4.4. Connection Establishment . . . . . . . . . . . . . . . .  12
4.5. Event Flow Control . . . . . . . . . . . . . . . . . . .  16
4.6. Encoding Negotiation . . . . . . . . . . . . . . . . . .  18
4.7. Query the supported extension protocol list  . . . . . .  18
4.8. Setting IM Values  . . . . . . . . . . . . . . . . . . .  19
4.9. getting IM Values  . . . . . . . . . . . . . . . . . . .  19
4.10. Creating an IC  . . . . . . . . . . . . . . . . . . . .  20
4.11. Destroying the IC . . . . . . . . . . . . . . . . . . .  20
4.12. Setting IC Values . . . . . . . . . . . . . . . . . . .  21
4.13. Getting IC Values . . . . . . . . . . . . . . . . . . .  21
4.14. Setting IC Focus  . . . . . . . . . . . . . . . . . . .  21
4.15. Unsetting IC Focus  . . . . . . . . . . . . . . . . . .  22
4.16. Filtering Events  . . . . . . . . . . . . . . . . . . .  22
4.17. Synchronizing with the IM Server  . . . . . . . . . . .  25
4.18. Sending a committed string  . . . . . . . . . . . . . .  25
4.19. Reset IC  . . . . . . . . . . . . . . . . . . . . . . .  26
4.20. Callbacks . . . . . . . . . . . . . . . . . . . . . . .  26
4.20.1. Negotiating geometry  . . . . . . . . . . . . . . . .  27
4.20.2. Converting a string . . . . . . . . . . . . . . . . .  27
4.20.3. Preedit Callbacks . . . . . . . . . . . . . . . . . .  27
4.20.4. Preedit state notify  . . . . . . . . . . . . . . . .  29
4.20.5. Status Callbacks  . . . . . . . . . . . . . . . . . .  29
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . .  30
6. References . . . . . . . . . . . . . . . . . . . . . . . .  30
Appendix A - Common Extensions  . . . . . . . . . . . . . . .  31
Appendix B - The list of transport specific IM Server names reg-
istered . . . . . . . . . . . . . . . . . . . . . . . . . . .  33
Appendix C - Protocol number  . . . . . . . . . . . . . . . .  35
Appendix D - Implementation Tips  . . . . . . . . . . . . . .  36











