

















                    [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


         +


                            ____________________
                            ||                   ||
                            |  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 re-
duced, resulting in improved performance.  The IM Server can send
message in order to switch the event flow in  the  Dynamic  Event



                                [1m6[0m





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


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.


               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


               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).

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



                                [1m24[0m





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


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
     :4:KEYSYM:KeySym




                                [1m25[0m





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


     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:



                   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


                   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>>



                  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>>


                  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
performance  acceleration  is not as good as the method described
above.



                                [1m38[0m





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


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











