DocsThe protocol described below uses the bi-directional synchronous/asynchronous request/reply/error model and is specified using the same conventions outlined in Section 2 of the core X Window System protocol [1]:
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.
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 corresponds 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
XIM_QUERY_EXTENSION
message. (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.
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
Pad(N) = (4 - (N mod 4)) mod 4
LPCE
1 A character from the4 X Portable Character Set in Latin Portable
Character Encoding
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:
| values | data | format | ||
|---|---|---|---|---|
| #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 | 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 | number of XIMTRIGGERKEY list (*4) |
| n | XIMTRIGGERKEY | XIMHotkeyTrigger list | ||
| n | XIMHOTKEYSTATE | HotKey processing state | ||
| #17 | XIMStringConversion | XIMSTRCONVTEXT | ||
| #18 | XIMPreeditState | XIMPREEDITSTATE | ||
| #19 | XIMResetState | XIMRESETSTATE | ||
| #x7fff | NestedList | ----- |
(*3) The IC value for the separator of NestedList is defined as follows,
#define XNSeparatorofNestedList "separatorofNestedList"
, 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)
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)
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(*3) The IC value for the separator of NestedList is defined as follows,
#define XNSeparatorofNestedList "separatorofNestedList"
, 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)
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)
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
Both the IM Server and the IM library return
XIM_ERROR
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 choice of which error is returned is implementation-dependent.
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 BadPixmap
#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
XIM_CONNECT
message requests to establish a connection over a mutually-understood virtual
stream.
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.
A client must send
XIM_CONNECT
message as the first message on the connection.
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.)
XIM_AUTH_REQUIRED
message is used to send the authentication protocol name and protocol-specific
data.
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
XIM_CONNECT
or
XIM_AUTH_SETUP
message. Any protocol-specific data that might be required is also sent.
The IM library sends
XIM_AUTH_REPLY
message as the reply to
XIM_AUTH_REQUIRED
message, if the IM Server is authenticated.
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.
XIM_AUTH_NEXT
message requests to send more auth data.
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
XIM_AUTH_SETUP
message to authenticate the client.
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.
XIM_AUTH_NG
message requests to give up the connection.
XIM_AUTH_NG (IM library <--> IM Server)
The IM Server sends
XIM_CONNECT_REPLY
message as the reply to
XIM_CONNECT
or
XIM_AUTH_REQUIRED
message.
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.
State transitions for the client
init_status: | Use authorization function -> client_ask Not use authorization function -> client_no_check |
start: |
Send If client_ask -> client_wait1 If client_no_check, client-auth-protocol-names may be omited -> client_wait2 |
client_wait1: |
Receive Receive <other> -> client_NG |
client_check: |
If no more auth needed, send
If good auth data, send
If bad auth data, send |
client_wait2: |
Receive
Receive
Receive Receive <other> -> client_NG |
client_more: |
Send |
client_NG: |
Send |
State transitions for the IM Server
init_status: | Use authorization function -> server_ask Not use authorization function -> server_no_check |
start: |
Receive -> start2 Receive <other> -> server_NG |
start2: |
If client_ask, send
If client_no_check and
server_ask, send
If client_no_check and
server_no_check, send
|
server_wait1: |
Receive
Receive
Receive <other> -> server_NG |
server_more |
Send
|
server2 |
If server_ask, send
If server_no_check, send
|
server_wait2 |
Receive
Receive <other> -> server_NG |
server_check |
If no more auth data, send
If bad auth data, send
If good auth data, send
|
server_NG |
Send
|
XIM_DISCONNECT
message requests to shutdown the connection over a mutually-understood
virtual stream.
XIM_DISCONNECT (IM library -> IM Server)
XIM_DISCONNECT
is a synchronous request. The IM library should wait until it receives
either an
XIM_DISCONNECT_REPLY
packet or an XIM_ERROR packet.
XIM_DISCONNECT_REPLY (IM Server -> IM library)
XIM_OPEN
requests to establish a logical connection between the IM library and the IM
Server.
XIM_OPEN (IM library -> IM Server)
n STR locale name
p unused, p = Pad(n)
XIM_OPEN
is a synchronous request. The IM library should wait until receiving
either an XIM_OPEN_REPLY
packet or an XIM_ERROR packet.
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
XIM_OPEN_REPLY
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 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.
XIM_CLOSE
message requests to shutdown the logical connection between the IM library
and the IM Server.
XIM_CLOSE (IM library -> IM Server)
2 CARD16 input-method-ID
2 unused
XIM_CLOSE
is a synchronous request. The IM library should wait until receiving
either an XIM_CLOSE_REPLY
packet or an XIM_ERROR packet.
XIM_CLOSE_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 unused
An IM Server must send
XIM_SET_EVENT_MASK
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.
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 synchronous-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.
XIM_SET_EVENT_MASK
is an asynchronous request. The event masks are valid immediately after
they are set until changed by another
XIM_SET_EVENT_MASK
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
XIM_REGISTER_TRIGGERKEYS
message to the IM library before sending
XIM_OPEN_REPLY
message.
Or the IM library may suppose that the IM Server uses the Static Event Flow
model.
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
XIM_REGISTER_TRIGGERKEYS
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
XIM_TRIGGER_NOTIFY
message that a key event matching either on-keys or off-keys has been occurred.
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.
XIM_TRIGGER_NOTIFY
is a synchronous request. The IM library should wait until receiving
either an XIM_TRIGGER_NOTIFY_REPLY
packet or an XIM_ERROR packet.
XIM_TRIGGER_NOTIFY_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_ENCODING_NEGOTIATION
message requests to decide which encoding to be sent across the wire.
When the negotiation fails, the fallback default encoding is Portable
Character Encoding.
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 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 to indicate that the negotiation
is failed, the fallback default encoding is used.
The message must be issued after sending
XIM_OPEN message via XOpenIM().
The name of encoding may be registered with X Consortium.
XIM_ENCODING_NEGOTIATION
is a synchronous request. The IM library should wait until receiving
either an XIM_ENCODING_NEGOTIATION_REPLY
packet or an XIM_ERROR packet.
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
XIM_QUERY_EXTENSION
message requests to query the IM extensions supported by the IM Server to
which the client is being connected.
XIM_QUERY_EXTENSION (IM library -> IM Server)
2 CARD16 input-method-ID
2 n byte length of extensions supported by the IM library
n LISTofSTR extensions supported by the IM library
p unused, p = Pad(n)
An example of a supported extension is FrontEnd.
The message must be issued after sending
XIM_OPEN 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
XIM_QUERY_EXTENSION
message for that extension, the IM Server responds with a
BadProtocol
error. If the IM Server encounters a request with an unknown MAJOR-OPCODE
or MINOR-OPCODE, it responds with a
BadProtocol error.
XIM_QUERY_EXTENSION
is a synchronous request. The IM library should wait until receiving
either an XIM_QUERY_EXTENSION_REPLY
packet or an XIM_ERROR packet.
XIM_QUERY_EXTENSION_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 n byte length of extensions supported by both the IM library and the IM Server
n LISTofEXT list of extensions supported by both the IM library and the IM Server
XIM_QUERY_EXTENSION_REPLY
message returns the list of extensions supported by both the IM library and
the IM Server. If the list passed in
XIM_QUERY_EXTENSION
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.
XIM_SET_IM_VALUES
requests to set attributes to the IM.
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
XIM_SET_IM_VALUES
message are specified as a LISTofXIMATTRIBUTE, specifying the attributes
to be set. Attributes other than the ones returned by
XIM_OPEN_REPLY
message should not be specified.
XIM_SET_IM_VALUES
is a synchronous request. The IM library should wait until receiving
either an
XIM_SET_IM_VALUES_REPLY
packet or an
XIM_ERROR
packet, because it must receive the error attribute if
XIM_ERROR message is returned.
XIM_SET_IM_VALUES_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 unused
XIM_SET_IM_VALUES_REPLY
message returns the input-method-ID to distinguish replies from multiple IMs.
XIM_GET_IM_VALUES
requests to query IM values supported by the IM Server currently being
connected.
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)
XIM_GET_IM_VALUES
is a synchronous request. The IM library should wait until it receives
either an
XIM_GET_IM_VALUES_REPLY
packet or an XIM_ERROR packet.
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
XIM_GET_IM_VALUES_REPLY
message. The order of the returned im-attribute values corresponds directly
to that of the list passed with the
XIM_GET_IM_VALUES message.
XIM_CREATE_IC message requests to create an IC.
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
XIM_CREATE_IC
message.), and it should not be set to zero.
XIM_CREATE_IC
is a synchronous request which returns the input-context-ID.
The IM library should wait until it receives either an
XIM_CREATE_IC_REPLY
packet or an
XIM_ERROR
packet.
XIM_CREATE_IC_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_DESTROY_IC
message requests to destroy the IC.
XIM_DESTROY_IC (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_DESTROY_IC
is a synchronous request. The IM library should not free its resources
until it receives an
XIM_DESTROY_IC_REPLY
message because XIM_DESTROY_IC
message may result in Callback packets such as
XIM_PREEDIT_DRAW
and XIM_PREEDIT_DONE.
XIM_DESTROY_IC_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_SET_IC_VALUES
messages requests to set attributes to the IC.
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
XIM_SET_IC_VALUES
message are specified as a LISTofXICATTRIBUTE, specifying the attributes
to be set. Attributes other than the ones returned by
XIM_OPEN_REPLY message should not be specified.
XIM_SET_IC_VALUES
is a synchronous request. The IM library should wait until receiving
either an XIM_SET_IC_VALUES_REPLY
packet or an XIM_ERROR
packet, because it must receive the error attribute if
XIM_ERROR message is returned.
XIM_SET_IC_VALUES_REPLY (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_GET_IC_VALUES
message requests to query IC values supported by the IM Server currently
being connected.
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.
XIM_GET_IC_VALUES
is a synchronous request and returns each attribute with its values to
show the correspondence. The IM library should wait until receiving
either an XIM_GET_IC_VALUES_REPLY
packet or an XIM_ERROR packet.
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 LISTofXICATTRIBUTE ic-attribute
XIM_SET_IC_FOCUS
message requests to set the focus to the IC.
XIM_SET_IC_FOCUS (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_SET_IC_FOCUS is an asynchronous request.
XIM_UNSET_IC_FOCUS
message requests to unset the focus to the focused IC.
XIM_UNSET_IC_FOCUS (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_UNSET_IC_FOCUS
is an asynchronous request.
Event filtering is mainly provided for BackEnd method to allow input method to capture X events transparently to clients.
X Events are forwarded by
XIM_FORWARD_EVENT message.
This message can be operated both synchronously and asynchronously.
If the requester sets the synchronous flag, the receiver must send
XIM_SYNC_REPLY
message back to the requester when all the data processing is done.
Protocol flow of BackEnd model
With BackEnd method, the protocol flow can be classified into two
methods in terms of synchronization, depending on the synchronous-eventmask
of XIM_SET_EVENT_MASK
message. One can be called on-demand-synchronous method and another
can be called as full-synchronous method.
In on-demand-synchronous method, the IM library always receives
XIM_FORWARD_EVENT
or
XIM_COMMIT
message as a synchronous request. Also, the IM Server needs to synchronously
process the correspondent reply from the IM library and the following
XIM_FORWARD_EVENT
message sent from the IM library when any of the event causes the IM Server
to send
XIM_FORWARD_EVENT
or
XIM_COMMIT
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
synchronous request, the IM library replies for the synchronous request before
processing any of the events. In this time, the IM Server blocks
XIM_FORWARD_EVENT
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
XIM_FORWARD_EVENT
message to the IM Server as a synchronous request. Therefore, the reply to it
from the IM Server will be put between the
XIM_FORWARD_EVENT message and its
XIM_SYNC_REPLY message. In case of sending
XIM_FORWARD_EVENT or
XIM_COMMIT
message, the IM Server should set the synchronous flag off. Because the
synchronization can be done by the following
XIM_SYNC_REPLY message.
Following chart shows one of the simplest protocol flow which only deals with keyevents for preediting operation.
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.
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 (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 XEvent's xany.serial, the top of 16 bit is sent by serial number(INT16).
XIM_FORWARD_EVENT
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 forwarded from the IM library is not filtered.
The IM Server, which receives
XIM_FORWARD_EVENT
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.
XIM_SYNC
message requests to synchronize the IM library and the IM Server.
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
XIM_SYNC
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.
XIM_SYNC_REPLY (IM Server <--> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
The side which receives
XIM_FORWARD_EVENT,
XIM_COMMIT
or any other message with synchronous bit, should process all XIM request
before replying, and send
XIM_SYNC_REPLY
message as the reply to the previous message.
When the IM Server commits a string, the IM Server sends either the committed
string or list of KeySym, or both, by
XIM_COMMIT
message.
XIM_COMMIT (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 BITMASK16 flag
#0001 synchronous
#0002 XLookupChars
#0004 XLookupKeySym
#0006 XLookupBoth = XLookupChars | XLookupKeySymXIM_COMMIT (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
2 BITMASK16 flag
#0001 synchronous
#0002 XLookupChars
#0004 XLookupKeySym
#0006 XLookupBoth = XLookupChars | XLookupKeySymIf flag is XLookupKeySym, the arguments continue as follows:
2 unused
4 KEYSYM KeySym
If flag is XLookupChars, the arguments continue as follows
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
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
XIM_COMMIT
message without synchronous bit should set synchronous bit.
XIM_RESET_IC
message requests to reset the status of IC in the IM Server.
XIM_RESET_IC (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_RESET_IC
is a synchronous request. The IM library should wait until receiving either an
XIM_RESET_IC_REPLY packet or an
XIM_ERROR packet.
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)
XIM_RESET_IC_REPLY
message returns the input-context-ID to distinguish replies from multiple ICs.
If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGeometryCallback 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 synchronously with the request previously sent by an IM client, the IM Server sends it before replying to the previous request.
The IM Server sends
XIM_GEOMETRY
message to start geometry negotiation, if XIMStyle has XIMPreeditArea or
XIMStatusArea set.
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.
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 XIMBackwardWord
#4 XIMCaretUp
#5 XIMCaretDown
#6 XIMNextLine
#7 XIMCPreviousLine
#8 XIMLineStart
#9 XIMLineEnd
#10 XIMAbsolutePosition
#11 XIMDontChange
2 CARD16 factor
2 CARD16 XIMStringConversionOperation
#0001 XIMStringConversionSubstitution
#0002 XIMStringConversionRetrieval
2 INT16 byte length to multiply the XIMStringConversionType
XIM_STR_CONVERSION
message may be used to start the string conversion from the IM Server.
XIM_STR_CONVERSION_REPLY (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 CARD32 XIMStringConversionFeedback
XIMSTRCONVTEXT XIMStringConversionText
XIM_STR_CONVERSION_REPLY
message returns the string to be converted and the feedback information array.
The IM Server sends
XIM_PREEDIT_START
message to call the XIMPreeditStartCallback function.
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.
XIM_PREEDIT_START_REPLY (IM library -> IM Server)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 INT32 return value
XIM_PREEDIT_START_REPLY
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
XIM_PREEDIT_DRAW
message to call the XIMPreeditDrawCallback function.
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 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
XIM_PREEDIT_CARET
message to call the PreeditCaretCallback function.
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 XIMBackwardWord
#4 XIMCaretUp
#5 XIMCaretDown
#6 XIMNextLine
#7 XIMCPreviousLine
#8 XIMLineStart
#9 XIMLineEnd
#10 XIMAbsolutePosition
#11 XIMDontChange
4 CARD32 style
#0 XIMInvisible
#1 XIMCPrimary
#2 XIMSecondary
Each entry corresponds to a field of XIMPreeditCaretCallbackStruct. Since this callback sets the caret position, its reply must be sent synchronously.
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
XIM_PREEDIT_DONE
message to call the XIMPreeditDoneCallback function.
XIM_PREEDIT_DONE (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
XIM_PREEDITSTATE (IM Server -> IM Library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
4 BITMASK32 XIMPreeditState
#x0000000 XIMPreeditUnknown
#x0000001 XIMPreeditEnable
#x0000002 XIMPreeditDisable
XIM_PREEDITSTATE
message is used to call the XIMPreeditStateNotifyCallback function.
The IM Server sends
XIM_STATUS_START
message to call the XIMStatusStartCallback function.
XIM_STATUS_START (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID
The IM Server sends
XIM_STATUS_DRAW
message to call the XIMStatusDrawCallback function.
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.
4 BITMASK32 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.
4 PIXMAP pixmap data
The field "type" corresponds to the field in XIMStatusDrawCallbackStruct.
The IM Server sends
XIM_STATUS_DONE
message to call the XIMStatusDoneCallback function.
XIM_STATUS_DONE (IM Server -> IM library)
2 CARD16 input-method-ID
2 CARD16 input-context-ID