[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 trans-
port 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 applications
within the stand-alone distributed environment.
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
obtaining a copy of this software and associated documenta-
tion files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, 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 PUR-
POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSOR-
TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, 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 Con-
sortium shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software
without prior written 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 docu-
mentation 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 representations about the suitability for any pur-
pose of the information in this document. This documenta-
tion is provided as is without express or implied warranty.
[1m1. Introduction[0m
[1m1.1. Scope[0m
The internationalization in the X Window System Version 11,
Release 5 (X11R5) provides a common API which application
developers can use to create portable internationalized pro-
grams and to adapt them to the requirements of different
native languages, local customs, and character string encod-
ings (this is called ``localization''). As one of its
internationalization mechanisms X11R5 has defined a func-
tional interface for internationalized text input, called
XIM (X Input Method).
When a client-server model is used with an IM (Input Method)
implementation, a protocol must be established between the
client and the server. However, the protocol used to inter-
face 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-specific input methods, decreased the
user's choice of available input methods, and made it more
difficult for developers to create portable applications.
This paper describes the Input Method Protocol 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 oth-
ers. English, for instance, uses an alphabet of a manage-
able 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
accents, which require the addition of special key combina-
tions in order to enter text. These input methods may
require ``dead-keys'' or ``compose-keys'' which, when fol-
lowed by different combinations of key strokes, generate
different characters.
Text input for ideographic languages is much less simple.
In these languages, characters represent actual objects
[1m1[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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 dictionary for possible
ideographic equivalents (of which there may be many). The
input method then presents the candidate characters 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. Several 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 prefer-
ence has been established, the input method does the substi-
tution directly.
These complicated input methods must present state informa-
tion (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 computer 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 input method which dis-
plays into them directly.
- 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
[1m2[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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. 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 implementation model.
- Client/Server model:
A separate process, the IM Server,
processes input and handles preed-
iting, converting, and committing.
The IM library within the applica-
tion, acting as client to the IM
Server, simply receives the commit-
ted 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
languages, are implemented using the Client/Server IM model.
Other languages which need only dead key or compose key pro-
cessing, 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
remembers 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 lan-
guages.
[1m3[0m
[1mX Input Method Protocol X11, Release 6.1[0m
In addition, the supported IM type can be obtained using
XGetIMValues().
The client usually holds multiple input (text) fields. Xlib
provides 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 XDestroyIC().
The IC can specify the type of IM which is supported by XIM
for each input field, so each input field can handle a dif-
ferent 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 XSet-
ICFocus(). (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 FrontEnd method as an optional IM Server exten-
sion.
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
delivered to the IM library, which then passes them to the
IM Server. Events are handled serially in the order deliv-
ered, and therefore there is no synchronization problem
between the IM library 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
[1m4[0m
[1mX Input Method Protocol X11, Release 6.1[0m
the IM library. 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 prob-
lems between 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 sup-
ported, and the FrontEnd method is made available as an
extension for performance purposes. (Refer to Appendix A for
more information.)
[1m5[0m
[1mX Input Method Protocol X11, Release 6.1[0m
... 0.05 6.513 4.737 10.45 ... 0.000i 3.937i 4.687i 0.000i
+
____________________
|| ||
| Application |
| |
| _______ |
| || |
| || _||__|__________|
| | | | Library |||
| || _|__|__________||
_|__||_______|__________||
||| |
| ||
| ___|__________________
| || ||
| | IM Ser|ver |
| _|__________|__________|
BackEnd Method|(Core) |||FrontEnd Method (Extension)
| |
___|_______________|__
|| ||
| X Server |
_|___________________|
Fig.1 The Flow of Events
[1m2.4. Event Flow Control[0m
This protocol supports two event flow models for communica-
tion 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 necessary 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
[1m6[0m
[1mX Input Method Protocol X11, Release 6.1[0m
is significantly reduced, and the number of context switches
is also reduced, resulting in improved performance. The IM
Server can send message in order to switch the event flow in
the Dynamic Event Flow.
The protocol for this process is described in section 4.5.
``Event Flow Control''.
[1m3. Default Preconnection Convention[0m
IM Servers are strongly encouraged to register their sym-
bolic names as the ATOM names into the IM Server directory
property, on the root window of the screen_number 0. This
property can contain a list of ATOMs, and the each ATOM rep-
resents 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
address(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
multiple 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
transport-specific name. The preregistered formats for
transport-specific names are listed in Appendix B. Addi-
tional transport-specific 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 con-
vention 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 syn-
chronous/asynchronous request/reply/error model and is spec-
ified using the same conventions outlined in Section 2 of
the core X Window 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.
[1m7[0m
[1mX Input Method Protocol X11, Release 6.1[0m
The basic request packet header format is as follows.
major-opcode: CARD8
minor-opcode: CARD8
length: CARD16
The MAJOR-OPCODE specifies which core request or extension
package this packet represents. If the MAJOR-OPCODE corre-
sponds to a core request, the MINOR-OPCODE contains 8 bits
of request-specific data. (If the MINOR-OPCODE is not used,
it is 0.) Otherwise, the MAJOR-OPCODE and the MINOR-OPCODE
are specified by message. (Refer to 4.7. Query the sup-
ported 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
protocol:
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
XIMATTRIBUTE 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:XIM-
Styles:2:n:number of XIMStyle list ::2::unused
::n:CARD32:XIMStyle list #11:XRectangle: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
XIMTRIGGERKEY list (*4) T} ::n:XIMTRIG-
GERKEY:XIMHotkeyTrigger list
[1m9[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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
#16:XIMHotKeyState::XIMHOTKEYSTATE:T{ HotKey processing
state T} #17:XIMStringConversion:XIMSTRCONVTEXT
#18:XIMPreeditState:XIMPREEDITSTATE #19:XIMReset-
State:XIMRESETSTATE #x7fff:NestedList:-----
_
(*3) The IC value for the separator of NestedList is defined
as follows,
#define XNSeparatorofNestedList ``separato-
rofNestedList''
, 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)
[1m10[0m
[1mX Input Method Protocol X11, Release 6.1[0m
XICATTRIBUTE
2 CARD16 attribute ID
2 n value length
n value
p unused, p = Pad(n)
[1m11[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
error condition is encountered in processing a request, the
[1m12[0m
[1mX Input Method Protocol X11, Release 6.1[0m
choice of which error is returned is implementation-depen-
dent.
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:BITMASK16:flag (*1) ::#0000:Both Input-Method-ID and
Input-Context-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:BadFocusWindow ::#5:BadArea ::#6:BadSpotLocation
::#7:BadColormap ::#8:BadAtom ::#9:BadPixel ::#10:Bad-
Pixmap ::#11:BadName ::#12:BadCursor ::#13:BadProtocol
::#14:BadForeground ::#15:BadBackground
::#16:LocaleNotSupported ::#999:BadSomething (*2)
:2:n:byte length of error detail. :2:CARD16:type of
error detail (*3) :n:STRING8:error detail (*4)
:p::unused, p = Pad(n)
(*1) Before an IM is created, both Input-Method-ID and
Input-Context-ID are invalid. Before an IC is
created, only Input-Method-ID is valid. After
that, both of Input-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-
understood 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:number of client-auth-protocol-names
:n:LISTofSTRING:client-auth-protocol-names
(*1) Specify the version of IM Protocol that the client
supports.
[1m13[0m
[1mX Input Method Protocol X11, Release 6.1[0m
A client must send message as the first message on the con-
nection. 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
protocol-specific data.
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
authentication 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.
[1m14[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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, 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
[1m15[0m
[1mX Input Method Protocol X11, Release 6.1[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
[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
[1m16[0m
[1mX Input Method Protocol X11, Release 6.1[0m
[4mserver_NG[0m
Send -> give up on this protocol
message requests to shutdown the connection over a mutually-
understood 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)
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
receiving 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 sup-
ported
message returns all supported IM and IC attributes in
LISTofXIMATTR 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 sup-
port IM system enhancements with new IM/IC attributes, with-
out modifying Xlib. The IC value for the separator of Nest-
edList must be included in the LISTofXICATTR.
message requests to shutdown the logical connection between
the IM library and the IM Server.
[1m17[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_CLOSE (IM library -> IM Server)
:2:CARD16:input-method-ID :2::unused
is a synchronous request. 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_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 forwarded 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).
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:syn-
chronous-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 synchro-
nous flag on by the IM library.
is an asynchronous request. The event masks are valid imme-
diately 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 request. That value will be used for the IC's which
have no individual values.
Using the Dynamic Event Flow model, an IM Server sends mes-
sage 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)
[1m18[0m
[1mX Input Method Protocol X11, Release 6.1[0m
: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:LISTofXIMTRIG-
GERKEY: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
receiving 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
[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 encod-
ings listed by name :n:LISTofSTR:list of encodings sup-
ported in the IM library. :p::unused, p = Pad(n)
:2:m:byte length of encodings listed by detailed data
:2::unused :m:LISTofENCODINGINFO: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
[1m19[0m
[1mX Input Method Protocol X11, Release 6.1[0m
to indicate that the negotiation is failed, the fallback
default encoding 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
receiving 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 exten-
sions supported by the IM library T} :n:LISTof-
STR:extensions supported by the IM library :p::unused,
p = Pad(n)
An example of a supported extension is FrontEnd. The mes-
sage must be issued after sending message via XOpenIM().
If n is 0, the IM library queries the IM Server for all
extensions.
If n is not 0, the IM library queries whether the IM Server
supports 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 MAJOR-OPCODE or MINOR-OPCODE, it
responds with a error.
is a synchronous request. 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_QUERY_EXTENSION_REPLY (IM Server -> IM library)
:2:CARD16:input-method-ID :2:n:T{ byte length of
[1m20[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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
library 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 speci-
fied.
is a synchronous request. The IM library should wait until
receiving 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 cur-
rently being connected.
tab(:); lfB s s s lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
XIM_GET_IM_VALUES (IM library -> IM Server)
[1m21[0m
[1mX Input Method Protocol X11, Release 6.1[0m
: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 iden-
tify the client (IC). (It is not specified by the client in
message.), 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
[1m22[0m
[1mX Input Method Protocol X11, Release 6.1[0m
is a synchronous request. The IM library should not free its
resources 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).
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:LISTofXICATTRIBUTE: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 speci-
fied.
is a synchronous request. The IM library should wait until
receiving 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-
attribute-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.
[1m23[0m
[1mX Input Method Protocol X11, Release 6.1[0m
is a synchronous request and returns each attribute with its
values 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:LISTofX-
ICATTRIBUTE: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).
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 requester 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 synchronous-eventmask of message. One can be called on-
[1m24[0m
[1mX Input Method Protocol X11, Release 6.1[0m
demand-synchronous 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 library, so that the
input service is consistent. If the IM library gets the
control back from the application after receiving the syn-
chronous request, the IM library replies for the synchronous
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 handles the other protocols at any time.
In full-synchronous method, the IM library always sends mes-
sage 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.
[1mSample Protocol flow chart 1[0m
Following chart shows one of the simplest protocol flow
which only deals with keyevents for preediting operation.
... 0.425 6.888 6.3 10.296 ... 0.000i 3.408i 5.875i 0.000i
Xlib API IM library IM Server
Key ev_e_n_t-_-XNextEvent || ||
XFilterE-v-e-n-t-------| |
--| XIM_FORWARD_EVENT|
| --|
Key ev_e_n_t-_-XNextEvent | XIM_FORWARD_EV-E-NT|synchronous
XFilterEvent | or XIM_COMMIT |request
--| (synchronous) |
-----------|-- --| ___
XNextEve-n-t | --|Pending ||
XFilterEvent (retu|rnsXIFMa_lFsOeR)WARD_EVENT| |
-_-____ XmbLookupString | | |
Application moves --| XIM_SYNC --| |
the focus XSetICFoc_u_s_____-_-_|___X_I_M___S_Y_N_C___R_E_P_L_Y-_-| |
|-_-________________ |processed|
| XIM_SET_IC_FOCUS|(The focu|sed
| --|IC is cha|nged)
XNextEvent |XIM_SYNC_REPLY a-s-|aprroecpelsysed|
--|of the XIM_FORWARD|_EVENT |
--| | |
| -- |proces-s-e-d-|
[1m25[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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.
[1m26[0m
[1mX Input Method Protocol X11, Release 6.1[0m
... 0.425 5.575 6.3 10.296 ... 0.000i 4.721i 5.875i 0.000i
Xlib API IM library IM Server
Key ev_e_n_t-_-XNextEvent || ||
XFilterE-v-e-n-t-------| |
--| XIM_FORWARD_EVENT|
| -- |
Key ev_e_n_t-_-XNextEvent | XIM_FORWARD_EVENT|synchronous
XFilterEvent | or XIM_COMMIT |request
--| (synchronous) |
Bfuotctuosn_c_ph_ra-en-sgseXSceatuIsCeFsocus | --|Pendin_g__
Pending -u-|ntXiIlM_FORWARD_EVENT| ||
sync cycl|e--is doXnIeM_SYNC --| |
|-- | |
|-- XIM_SYNC_REPLY | |
XNextEve-n-t --|-XIM_SET_IC_FOCUS i|s |
XFilterEvent (re||tu|rnpsenFdalbseec)ause anoth|er sync cy|cle
-_-____ XmbLookupString | |is started by XIM_|COMMIT |
Application moves | | | |
the focus XSetICFoc_u_s_____-|_-_| XIM_SET_IC_FOCUS | |
| | --|processed|
| | --|(The focu|sed
| | |IC is cha|nged)
Key ev_e_n_t_--XNextEvent | |XIM_SYNC_REPLY as |aprroecpelsysed|
| |of the XIM_FORWARD|_EVENT |
XFilterEvent -|--| | |
-|+| -- |proces-s-e-d-|
-+| XIM_SET_IC_FOCU|S
| -- |processed
| -- |
|XIM_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:BITMASK16:flag ::#0001:synchronous ::#0002:request
filtering (*1) ::#0004:request lookupstring (*2)
:2:CARD16:serial number ::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
[1m27[0m
[1mX Input Method Protocol X11, Release 6.1[0m
(e.g. compose of dead key sequences).
XEVENT format is same as the X Protocol event for-
mat(xEvent). As the value of xEvent's sequenceNumber is the
bottom of 16 bit of XEvent's xany.serial, the top of 16 bit
is sent by serial number(INT16).
message is used for forwarding the events from the IM
library to the IM Server in order for IM to be able to fil-
ter 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 forwarded 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 lookupstring''
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 mes-
sage 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 synchro-
nous 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
[1m28[0m
[1mX Input Method Protocol X11, Release 6.1[0m
:2:BITMASK16: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
If flag is XLookupChars, the arguments continue as fol-
lows:
tab(:); lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
:2:m:byte length of committed string :m:LISTofBYTE:com-
mitted string :p::unused, p = Pad(m)
If flag is XLookupBoth, the arguments continue as fol-
lows:
tab(:); lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
:2::unused :4:KEYSYM:KeySym :2:n:byte length of commit-
ted 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
receiving 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:LISTof-
BYTE:preedit string :p::unused, p = Pad(2+n)
[1m29[0m
[1mX Input Method Protocol X11, Release 6.1[0m
message returns the input-context-ID to distinguish replies
from multiple ICs.
[1m4.20. Callbacks[0m
If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGe-
ometryCallback may be used, and if XIMPreeditCallback and/or
XIMStatusCallback 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 syn-
chronously with the request previously sent by an IM client,
the IM Server sends it before replying to the previous
request.
[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:XIMBackwardChar ::#2:XIMForwardWord ::#3:XIMBack-
wardWord ::#4:XIMCaretUp ::#5:XIMCaretDown ::#6:XIM-
NextLine ::#7:XIMCPreviousLine ::#8:XIMLineStart
::#9:XIMLineEnd ::#10:XIMAbsolutePosition ::#11:XIM-
DontChange :2:CARD16:factor :2:CARD16:XIMStringConver-
sionOperation ::#0001:XIMStringConversionSubstitution
::#0002:XIMStringConversionRetrieval :2:INT16:T{ byte
length to multiply the XIMStringConversionType T}
[1m30[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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 ::XIMSTRCONV-
TEXT:XIMStringConversionText
message returns the string to be converted and the feedback
information array.
[1m4.20.3. Preedit Callbacks[0m
The IM Server sends message to call the XIMPreeditStartCall-
back 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
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 XIMPreeditDrawCall-
back 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
[1m31[0m
[1mX Input Method Protocol X11, Release 6.1[0m
The fields ``caret'', ``chg_first'' and ``chg_length'' cor-
respond to the fields of XIMPreeditDrawCallbackStruct. When
the ``no string'' bit of the status field is set, the text
field of XIMPreeditDrawCallbackStruct is NULL. When the
``no feedback'' bit of the status field is set, the text
feedback field of XIMPreeditDrawCallbackStruct 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:XIMForward-
Char ::#1:XIMBackwardChar ::#2:XIMForwardWord ::#3:XIM-
BackwardWord ::#4:XIMCaretUp ::#5:XIMCaretDown
::#6:XIMNextLine ::#7:XIMCPreviousLine ::#8:XIMLineS-
tart ::#9:XIMLineEnd ::#10:XIMAbsolutePosition
::#11:XIMDontChange :4:CARD32:style ::#0:XIMInvisible
::#1:XIMCPrimary ::#2:XIMSecondary
Each entry corresponds to a field of XIMPreeditCaretCall-
backStruct. 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)
: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 XIMPreeditDoneCall-
back 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:BITMASK32:XIMPreeditState ::#x0000000:XIMPreeditUn-
known ::#x0000001:XIMPreeditEnable
[1m32[0m
[1mX Input Method Protocol X11, Release 6.1[0m
::#x0000002:XIMPreeditDisable
message is used to call the XIMPreeditStateNotifyCallback
function.
[1m4.20.5. Status Callbacks[0m
The IM Server sends message to call the XIMStatusStartCall-
back 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 XIMStatusDrawCall-
back 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 fol-
lows.
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
The field ``type'' corresponds to the field in XIMStatus-
DrawCallbackStruct.
The IM Server sends message to call the XIMStatusDoneCall-
back function.
tab(:); lfB s s s lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
XIM_STATUS_DONE (IM Server -> IM library)
[1m33[0m
[1mX Input Method Protocol X11, Release 6.1[0m
:2:CARD16:input-method-ID :2:CARD16:input-context-ID
[1m34[0m
[1mX Input Method Protocol X11, Release 6.1[0m
[1m5. Acknowledgements[0m
This document represents the culmination of several years of
debate and experiments done under the auspices of the MIT X
Consortium 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 alphabetical order) for their participation in the IM
Protocol design, Hector Chan, Takashi Fujiwara, Yoshio Hori-
uchi, Makoto Inada, Hiromu Inukai, Mickael Kung, Seiji
Kuwari, Franky Ling, Hiroyuki Machida, Hiroyuki Miyamoto,
Frank Rojas, Bob Scheifler, Makiko Shimamura, Shoji
Sugiyama, Hidetoshi Tajima, Masaki Takeuchi, Makoto Waka-
matsu, Masaki Wakao, Nobuyuki Tanaka, Shigeru Yamada, Kat-
suhisa Yano, Jinsoo Yoon.
[1m6. References[0m
All of the following documents are X Consortium standards
available from MIT:
[1] Scheifler, Robert W., [4m``X[24m [4mWindow[24m [4mSystem[24m [4mProtocol[24m [4mVersion[0m
[4m11''[0m
[2] Scheifler, Robert W. etc., [4m``Xlib[24m [4m-[24m [4mC[24m [4mLanguage[24m [4mX[24m [4mInter-[0m
[4mface''[0m
[1m35[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
extensions may be registered with X Consortium. The follow-
ing 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:inter-
cept-event-mask (*2) :4:EVENTMASK:select-event-mask
(*3) :4:EVENTMASK:forward-event-mask (*4) :4:EVENT-
MASK:synchronous-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 synchro-
nous 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 per-
formance.
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)
[1m36[0m
[1mX Input Method Protocol X11, Release 6.1[0m
:2:CARD16:input-method-ID :2:CARD16:input-context-ID
: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
[1m37[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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.
[1m38[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 prop-
erty 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) [1mtrans-[0m
[1mport[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 example:
tcp/expo.lcs.mit.edu:8012
tcp/18.30.0.212:7890
[1mDECnet Names[0m
The following syntax should be used for DECnet
names:
[1m39[0m
[1mX Input Method Protocol X11, Release 6.1[0m
<[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 44.70). The <[4mobjname[24m> is normal,
case-insensitive DECnet 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 evalu-
ated in order of setting.
[1m40[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_CON-
NECT_REPLY:#002 XIM_DISCONNECT:#003 XIM_DISCON-
NECT_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_REPLY:#033 XIM_REGISTER_TRIGGERKEYS:#034 XIM_TRIG-
GER_NOTIFY:#035 XIM_TRIGGER_NOTIFY_REPLY:#036
XIM_SET_EVENT_MASK:#037 XIM_ENCODING_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_VALUES_REPLY:#055
XIM_GET_IC_VALUES:#056 XIM_GET_IC_VALUES_REPLY:#057
XIM_SET_IC_FOCUS:#058 XIM_UNSET_IC_FOCUS:#059 XIM_FOR-
WARD_EVENT:#060 XIM_SYNC:#061 XIM_SYNC_REPLY:#062 XIM_COM-
MIT:#063 XIM_RESET_IC:#064 XIM_RESET_IC_REPLY:#065
XIM_GEOMETRY:#070 XIM_STR_CONVERSION:#071 XIM_STR_CONVER-
SION_REPLY:#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_STATUS_START:#079 XIM_STA-
TUS_DRAW:#080 XIM_STATUS_DONE:#081 XIM_PREEDITSTATE:#082
(*) The IM Server's extension protocol number should be more
than #128.
[1m41[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 message with intercept-event-mask, forward-
event-mask, and synchronous-event-mask values set after
replying message.
FrontEnd method can be implemented in a couple of ways
depending on how the IM Server utilize message.
One approach is to update both of the input mask and the
filter-event-mask depending on the preeidting state. The
sample protocol sequence using the static event flow is as
follows:
... 1.675 6.888 6.237 10.296 ... 0.000i 3.408i 4.562i 0.000i
IM library IM Server
Keys in the on-k||ey-list ||
________-_-|__X_I_M___F_O_R_W_A_R_D___E_V_E-_N-T |
|-_-________________ |
|XIM_EXT_SET_EVENT_MA|SK
event mask is |chainngteedrcept-event-ma|sekveinstsmeatsk is changed
to deselect th|e event |to select the event
| |
| |-_-______
| |--
| | X events directly come
| | to the IM Server.
| | when preediting is turning off
|-_-________________ |
event mask is |cXhIaMn_gEeXdT_SET_EVENT_MA|SKevent mask is changed
to select the |evesnetlect-event-mask |istosedteselect the event
| |
| |
| |
| |
| |
[1m42[0m
[1mX Input Method Protocol X11, Release 6.1[0m
To pursuit a maximum performance regardless of the preedit-
ing mode, the IM Server may use the dynamic event flow with
the following sample protocol sequence.
[1m43[0m
[1mX Input Method Protocol X11, Release 6.1[0m
... 1.675 6.888 6.237 10.296 ... 0.000i 3.408i 4.562i 0.000i
IM library IM Server
Keys in the on-k||ey-list ||
________-_-|__X_I_M___T_R_I_G_G_E_R___N_O_T-_I-FY |
|-_-________________ |
|XIM_EXT_SET_EVENT_MA|SK
event mask is |chainngteedrcept-event-ma|sekveinstsmeatsk is changed
to deselect th|eXIeMv_eTnRtIGGER_NOTIFY_R|EtPoLYselect the event
|-_-________________ |
| |-_-______
| |--
| | X events directly come
| | to the IM Server.
| | when preediting is turning off
|-_-________________ |
event mask is |cXhIaMn_gEeXdT_SET_EVENT_MA|SKevent mask is changed
to select the |evesnetlect-event-mask |istosedteselect 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 key-
board in following sequence really fast:
<preediting on key>``some strings''<preediting off
key>``another 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 simul-
taneously.
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 preediting 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 pro-
tocol sequence are as follows:
[1m44[0m
[1mX Input Method Protocol X11, Release 6.1[0m
<<Using static event flow>>
... 1.488 7.325 6.487 10.358 ... 0.000i 3.033i 4.999i 0.000i
IM library IM Server
Keys in _t_h_e__o_n_-_k-_e-||y-_l_iX_sI_tM___F_O_R_W_A_R_D___E_V_E-_N-T ||-_-__K_e_y_s__i_n_the on-key-list
| -_-_______________-_- |--
| XIM_EXT_SET_EVENT_MA|SK
the specifi|ed efvielnttesr-event-mask |isthseetspecified events
are being f|iltered | are being processed
| |
| |
Keys in the off-|key-list | Keys in the off-key-list
________-_-| |-_-_________
| -_-________________ |
| XIMf_iElXtTe_rS-EeTv_eEnVtE-NmTa_sMkA|SiKs set
| |
the specifi|ed events | the specified events
are being p|rocessed | are being discarded
| |
| |
| |
| |
<<Using the dynamic event flow>>
... 1.488 7.325 6.487 10.358 ... 0.000i 3.033i 4.999i 0.000i
IM library IM Server
Keys in _t_h_e__o_n_-_k-_e-||y-_l_Xi_Is_Mt___T_R_I_G_G_E_R___N_O_T-_I-FY ||-_-__K_e_y_s__i_n_the on-key-list
| -_-_______________-_- |--
| XIM_EXT_SET_EVENT_MA|SK
the specifi|ed efvielnttesr-event-mask |isthseetspecified events
are being f|iltered | are being processed
| XIM_TRIGGER_NOTIFY_R|EPLY
| -_-________________ |
Keys in the off-|key-list | Keys in the off-key-list
________-_-| |-_-_________
| -_-________________ |
| XIMf_iElXtTe_rS-EeTv_eEnVtE-NmTa_sMkA|SiKs set
| |
the specifi|ed events | the specified events
are being p|rocessed | are being discarded
| |
| |
| |
| |
This method does not have the problem of the time lag when
going across the preediting on and off mode, however, the
[1m45[0m
[1mX Input Method Protocol X11, Release 6.1[0m
amount of the performance acceleration is not as good as the
method described above.
In general, the FrontEnd method requires some synchroniza-
tion to some of the X protocols, such as the ChangeWindowAt-
tribute protocol for the event mask change or the GrabKey
protocol, since it relies on the X's principal event dis-
patching mechanism. Any X protocol bindings do not consider
the synchronization might cause some mis-synchronization
between the IM clients and the IM Server.
[1m46[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 inde-
pendent of transport implementation. Each function of these
layers are:
[4mThe[24m [4mprotocol[24m [4mlayer[0m
implements overall function of XIM and calls the
interface layer functions when it needs to commu-
nicate 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
communication channels usable such as X Protocol, TCP/IP,
DECnet or STREAM. The following is a sample implementation
for the transporter using the X connection. Refer to
"xtrans" for the transporter using Socket Transport.
At the beginning of the X Transport connection for the XIM
transport 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 fol-
lowing, the window created by the Xlib is referred as the
"client communication window", and on the other hand, the
window created by the IM Server is referred as the "IMS com-
munication 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.
[1m47[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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 Window ID Atom:message_type:XInter-
nAtom(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.
[1m48[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 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_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
Property (*2)
_
(*1) major/minor-transport-version
The read/write method is decided by the com-
bination 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 multiple ClientMessages Property-
with-CM;:;T{ data is written in Property, and
its Atom is send via ClientMessage T} Proper-
tyNotify;:;T{ data is written in Property,
and its Atom is send via PropertyNotify T}
The method to decide major/minor-transport-version
is as follows:
[1m49[0m
[1mX Input Method Protocol X11, Release 6.1[0m
(1) The client sends 0 as major/minor-transport-
version to the IM Server. The client must
support all methods in Table D-3. The client
may send another number as major/minor-trans-
port-version to use other method than the
above in the future.
(2) The IM Server sends its major/minor-trans-
port-version 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 for-
mat 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
Window System Bool;send_event;Set by the X Window
System Display;*display;The display to which con-
nects Window;window;IMS communication window ID
Atom;message_type;XInternAtom(display,
``_XIM_MOREDATA'', False) int;format;8
char;data.b[20];(read/write DATA : 20 byte)
_
[1m50[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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
Window System Bool;send_event;Set by the X Window
System Display;*display;The display to which con-
nects Window;window;IMS communication window ID
Atom;message_type;XInternAtom(display, ``_XIM_PRO-
TOCOL'', 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 following 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 fol-
lows:
[1m51[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
Window:window:IMS communication window ID
Atom:property:read/write property Atom (*1)
Atom:type:XA_STRING int:format:8 int:mode:PropMod-
eAppend u_char:*data:read/write DATA int:nele-
ments:length of DATA
_
(*1) The read/write property ATOM allocates the
following strings by [1mXInternAtom[22m.
``_clientXXX''
The client changes the property with the mode of
PropModeAppend 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
Window System Bool:send_event:Set by the X Window
System Display:*display:The display to which con-
nects Window:window:IMS communication window ID
Atom:message_type:XInternAtom(display, ``_XIM_PRO-
TOCOL'', 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)
[1m52[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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 Display;*display;The display to which con-
nects Window;window;client communication window ID
Atom;message_type;XInternAtom(display,
``_XIM_MOREDATA'', False) int;format;8
char;data.b[20];(read/write DATA : 20 byte)
_
[1m53[0m
[1mX Input Method Protocol X11, Release 6.1[0m
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
Window System Bool;send_event ;Set by the X Window
System Display;*display;The display to which con-
nects Window;window;client communication window ID
Atom;message_type;XInternAtom(display, ``_XIM_PRO-
TOCOL'', 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 following 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 PropertyNo-
tify event.
The arguments of the XChangeProperty are as fol-
lows:
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
Window:window:client communication window ID
Atom:property:read/write property Atom (*1)
Atom:type:XA_STRING int:format:8 int:mode:PropMod-
eAppend u_char:*data:read/write DATA int:nele-
ments:length of DATA
_
[1m54[0m
[1mX Input Method Protocol X11, Release 6.1[0m
(*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:
[1m55[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
Window System Bool:send_event:Set by the X Window
System Display:*display:The display to which con-
nects Window:window:client communication window ID
Atom:message_type:XInternAtom(display, ``_XIM_PRO-
TOCOL'', 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
function should free the communication window proper-
ties and etc..
[1m56[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 . . . . . . . . . . . . . . . . 12
4.4. Connection Establishment . . . . . . . . . . . . . 13
4.5. Event Flow Control . . . . . . . . . . . . . . . . 18
4.6. Encoding Negotiation . . . . . . . . . . . . . . . 19
4.7. Query the supported extension protocol list . . . . 20
4.8. Setting IM Values . . . . . . . . . . . . . . . . . 21
4.9. getting IM Values . . . . . . . . . . . . . . . . . 21
4.10. Creating an IC . . . . . . . . . . . . . . . . . . 22
4.11. Destroying the IC . . . . . . . . . . . . . . . . 22
4.12. Setting IC Values . . . . . . . . . . . . . . . . 23
4.13. Getting IC Values . . . . . . . . . . . . . . . . 23
4.14. Setting IC Focus . . . . . . . . . . . . . . . . . 24
4.15. Unsetting IC Focus . . . . . . . . . . . . . . . . 24
4.16. Filtering Events . . . . . . . . . . . . . . . . . 24
4.17. Synchronizing with the IM Server . . . . . . . . . 28
4.18. Sending a committed string . . . . . . . . . . . . 28
4.19. Reset IC . . . . . . . . . . . . . . . . . . . . . 29
4.20. Callbacks . . . . . . . . . . . . . . . . . . . . 30
4.20.1. Negotiating geometry . . . . . . . . . . . . . . 30
4.20.2. Converting a string . . . . . . . . . . . . . . 30
4.20.3. Preedit Callbacks . . . . . . . . . . . . . . . 31
4.20.4. Preedit state notify . . . . . . . . . . . . . . 32
4.20.5. Status Callbacks . . . . . . . . . . . . . . . . 33
5. Acknowledgements . . . . . . . . . . . . . . . . . . 35
6. References . . . . . . . . . . . . . . . . . . . . . 35
Appendix A - Common Extensions . . . . . . . . . . . . . 36
Appendix B - The list of transport specific IM
Server names registered . . . . . . . . . . . . . . . . 39
Appendix C - Protocol number . . . . . . . . . . . . . . 41
Appendix D - Implementation Tips . . . . . . . . . . . . 42
