TThhee IInnppuutt MMeetthhoodd PPrroottooccooll VVeerrssiioonn 11..00 XX CCoonnssoorrttiiuumm SSttaannddaarrdd XX VVeerrssiioonn 1111,, RReelleeaassee 77 lliibbXX1111 11..33..22 Masahiko Narita FUJITSU Limited. Hideki Hiura SunSoft, Inc. _A_B_S_T_R_A_C_T 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 © 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 © 1993, 1994 by FUJITSU LIMITED Copyright © 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. _1_. _I_n_t_r_o_d_u_c_t_i_o_n _1_._1_. _S_c_o_p_e 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. _1_._2_. _B_a_c_k_g_r_o_u_n_d 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 11 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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. _1_._3_. _I_n_p_u_t _M_e_t_h_o_d _S_t_y_l_e_s 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 22 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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. _2_. _A_r_c_h_i_t_e_c_t_u_r_e _2_._1_. _I_m_p_l_e_m_e_n_t_a_t_i_o_n _M_o_d_e_l 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. _2_._2_. _S_t_r_u_c_t_u_r_e _o_f _I_M 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. 33 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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.) _2_._3_. _E_v_e_n_t _H_a_n_d_l_i_n_g _M_o_d_e_l 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) _2_._3_._1_. _B_a_c_k_E_n_d _M_e_t_h_o_d 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’’). _2_._3_._2_. _F_r_o_n_t_E_n_d _M_e_t_h_o_d In the FrontEnd method, client window input events are delivered by the X server directly to both the IM Server and 44 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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.) 55 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 ... 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 _2_._4_. _E_v_e_n_t _F_l_o_w _C_o_n_t_r_o_l 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 is significantly reduced, and the number of context switches is also reduced, resulting in improved performance. The IM 66 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 Server can send _X_I_M___R_E_G_I_S_T_E_R___T_R_I_G_G_E_R_K_E_Y_S 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’’. _3_. _D_e_f_a_u_l_t _P_r_e_c_o_n_n_e_c_t_i_o_n _C_o_n_v_e_n_t_i_o_n IM Servers are strongly encouraged to register their sym‐ bolic names as the ATOM names into the IM Server directory property, _X_I_M___S_E_R_V_E_R_S_, on the root window of the screen_num‐ ber 0. This property can contain a list of ATOMs, and the each ATOM represents each possible IM Server. IM Server names are restricted to POSIX Portable Filename Character Set. To discover if the IM Server is active, see if there is an owner for the selection with that atom name. To learn the address of that IM Server, convert the selection target _T_R_A_N_S_P_O_R_T_, which will return a string form of the transport address(es). To learn the supported locales of that IM Server, convert the selection target _L_O_C_A_L_E_S_, 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 _X_I_M___S_E_R_V_E_R_S property, is first fit if the IM Server name is not given as a X modifier’s category _i_m_. The address information retrievable from the _T_R_A_N_S_P_O_R_T tar‐ get is a transport‐specific name. The preregistered formats for transport‐specific names are listed in Appendix B. Additional 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). _4_. _P_r_o_t_o_c_o_l 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]: _4_._1_. _B_a_s_i_c _R_e_q_u_e_s_t_s _P_a_c_k_e_t _F_o_r_m_a_t This section describes the requests that may be exchanged between the client and the IM Server. 77 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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 _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N message. (Refer to 4.7. Query the supported extension protocol list.) The LENGTH field specifies the number of 4 bytes elements fol‐ lowing the header. If no additional data is followed by the header, the LENGTH field will be 0. _4_._2_. _D_a_t_a _T_y_p_e_s 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 88 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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: ────────────────────────────────────────────────────────────────────────────────────────── _v_a_l_u_e_s _d_a_t_a _f_o_r_m_a_t ────────────────────────────────────────────────────────────────────────────────────────── #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 99 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 ────────────────────────────────────────────────────────────────────────────────────────── _v_a_l_u_e_s _d_a_t_a _f_o_r_m_a_t ────────────────────────────────────────────────────────────────────────────────────────── 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 #16 XIMHotKeyState 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 ‘‘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 1100 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 p unused, p = Pad(n) XICATTRIBUTE 2 CARD16 attribute ID 2 n value length n value p unused, p = Pad(n) 1111 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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 _4_._3_. _E_r_r_o_r _N_o_t_i_f_i_c_a_t_i_o_n Both the IM Server and the IM library return _X_I_M___E_R_R_O_R mes‐ sages 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 1122 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 choice of which error is returned is implementation‐depen‐ dent. XXIIMM__EERRRROORR ((IIMM SSeerrvveerr ←←→→ IIMM lliibbrraarryy)) 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 _4_._4_. _C_o_n_n_e_c_t_i_o_n _E_s_t_a_b_l_i_s_h_m_e_n_t _X_I_M___C_O_N_N_E_C_T message requests to establish a connection over a mutually‐understood virtual stream. 1133 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__CCOONNNNEECCTT ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 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 _X_I_M___C_O_N_N_E_C_T message as the first message on the connection. The list specifies the names of authen‐ tication protocols the sending IM Server is willing to per‐ form. (If the client need not authenticate, the list may be omited.) _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D message is used to send the authentication protocol name and protocol‐specific data. XXIIMM__AAUUTTHH__RREEQQUUIIRREEDD ((IIMM lliibbrraarryy ←←→→ IIMM SSeerrvveerr)) 1 CARD8 auth‐protocol‐index 3 unused 2 n length of authentication data 2 unused n data p unused, p = Pad(n) The auth‐protocol is specified by an index into the list of names given in the _X_I_M___C_O_N_N_E_C_T or _X_I_M___A_U_T_H___S_E_T_U_P message. Any protocol‐specific data that might be required is also sent. The IM library sends _X_I_M___A_U_T_H___R_E_P_L_Y message as the reply to _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D message, if the IM Server is authenti‐ cated. XXIIMM__AAUUTTHH__RREEPPLLYY ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 n length of authentication data 2 unused 2 n length of authentication data 2 unused n data p unused, p = Pad(n) The auth data is specific to the authentication protocol in use. 1144 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 _X_I_M___A_U_T_H___N_E_X_T message requests to send more auth data. XXIIMM__AAUUTTHH__NNEEXXTT ((IIMM lliibbrraarryy ←←→→ IIMM SSeerrvveerr)) 2 n length of authentication data 2 unused n data p unused, p = Pad(n) The auth data is specific to the authentication protocol in use. The IM Server sends _X_I_M___A_U_T_H___S_E_T_U_P message to authenticate the client. XXIIMM__AAUUTTHH__SSEETTUUPP ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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. _X_I_M___A_U_T_H___N_G message requests to give up the connection. XXIIMM__AAUUTTHH__NNGG ((IIMM lliibbrraarryy ←←→→ IIMM SSeerrvveerr)) The IM Server sends _X_I_M___C_O_N_N_E_C_T___R_E_P_L_Y message as the reply to _X_I_M___C_O_N_N_E_C_T or _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D message. XXIIMM__CCOONNNNEECCTT__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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. _S_t_a_t_e _t_r_a_n_s_i_t_i_o_n_s _f_o_r _t_h_e _c_l_i_e_n_t _i_n_i_t___s_t_a_t_u_s: Use authorization function → _c_l_i_e_n_t___a_s_k Not use authorization function → _c_l_i_e_n_t___n_o___c_h_e_c_k _s_t_a_r_t: 1155 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 Send _X_I_M___C_O_N_N_E_C_T If _c_l_i_e_n_t___a_s_k → _c_l_i_e_n_t___w_a_i_t_1 If _c_l_i_e_n_t___n_o___c_h_e_c_k, client‐auth‐protocol‐ names may be omited → _c_l_i_e_n_t___w_a_i_t_2 _c_l_i_e_n_t___w_a_i_t_1: Receive _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D → _c_l_i_e_n_t___c_h_e_c_k Receive → _c_l_i_e_n_t___N_G _c_l_i_e_n_t___c_h_e_c_k: If no more auth needed, send _X_I_M___A_U_T_H___R_E_P_L_Y → _c_l_i_e_n_t___w_a_i_t_2 If good auth data, send _X_I_M___A_U_T_H___N_E_X_T → _c_l_i_e_n_t___w_a_i_t_1 If bad auth data, send _X_I_M___A_U_T_H___N_G → give up on this protocol _c_l_i_e_n_t___w_a_i_t_2: Receive _X_I_M___C_O_N_N_E_C_T___R_E_P_L_Y → connect Receive _X_I_M___A_U_T_H___S_E_T_U_P → _c_l_i_e_n_t___m_o_r_e Receive _X_I_M___A_U_T_H___N_E_X_T → _c_l_i_e_n_t___m_o_r_e Receive _X_I_M___A_U_T_H___N_G → give up on this protocol Receive → _c_l_i_e_n_t___N_G _c_l_i_e_n_t___m_o_r_e: Send _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D → _c_l_i_e_n_t___w_a_i_t_2 _c_l_i_e_n_t___N_G: Send _X_I_M___A_U_T_H___N_G → give up on this protocol _S_t_a_t_e _t_r_a_n_s_i_t_i_o_n_s _f_o_r _t_h_e _I_M _S_e_r_v_e_r _i_n_i_t_‐_s_t_a_t_u_s: Use authorization function → _s_e_r_v_e_r___a_s_k Not use authorization function → _s_e_r_v_e_r___n_o___c_h_e_c_k _s_t_a_r_t: Receive _X_I_M___C_O_N_N_E_C_T → _s_t_a_r_t_2 Receive → _s_e_r_v_e_r___N_G _s_t_a_r_t_2: If _c_l_i_e_n_t___a_s_k, send _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D → _s_e_r_v_e_r___w_a_i_t_1 If _c_l_i_e_n_t___n_o___c_h_e_c_k and _s_e_r_v_e_r___a_s_k, send _X_I_M___A_U_T_H___S_E_T_U_P → _s_e_r_v_e_r___w_a_i_t_2 If _c_l_i_e_n_t___n_o___c_h_e_c_k and _s_e_r_v_e_r___n_o___c_h_e_c_k, send 1166 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 _X_I_M___C_O_N_N_E_C_T___R_E_P_L_Y → connect _s_e_r_v_e_r___w_a_i_t_1: Receive _X_I_M___A_U_T_H___R_E_P_L_Y → _s_e_r_v_e_r_2 Receive _X_I_M___A_U_T_H___N_E_X_T → _s_e_r_v_e_r___m_o_r_e Receive → _s_e_r_v_e_r___N_G _s_e_r_v_e_r___m_o_r_e Send _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D → _s_e_r_v_e_r___w_a_i_t_1 _s_e_r_v_e_r_2 If _s_e_r_v_e_r___a_s_k, send _X_I_M___A_U_T_H___S_E_T_U_P → _s_e_r_v_e_r___w_a_i_t_2 If _s_e_r_v_e_r___n_o___c_h_e_c_k, send _X_I_M___C_O_N_N_E_C_T___R_E_P_L_Y → con‐ nect _s_e_r_v_e_r___w_a_i_t_2 Receive _X_I_M___A_U_T_H___R_E_Q_U_I_R_E_D → _s_e_r_v_e_r___c_h_e_c_k Receive → _s_e_r_v_e_r___N_G _s_e_r_v_e_r___c_h_e_c_k If no more auth data, send _X_I_M___C_O_N_N_E_C_T___R_E_P_L_Y → connect If bad auth data, send _X_I_M___A_U_T_H___N_G → give up on this protocol If good auth data, send _X_I_M___A_U_T_H___N_E_X_T → _s_e_r_v_e_r___w_a_i_t_2 _s_e_r_v_e_r___N_G Send _X_I_M___A_U_T_H___N_G → give up on this protocol _X_I_M___D_I_S_C_O_N_N_E_C_T message requests to shutdown the connection over a mutually‐understood virtual stream. XXIIMM__DDIISSCCOONNNNEECCTT ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) _X_I_M___D_I_S_C_O_N_N_E_C_T is a synchronous request. The IM library should wait until it receives either an _X_I_M___D_I_S_C_O_N_N_E_C_T___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__DDIISSCCOONNNNEECCTT__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) _X_I_M___O_P_E_N requests to establish a logical connection between the IM library and the IM Server. 1177 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__OOPPEENN ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) n STR locale name p unused, p = Pad(n) _X_I_M___O_P_E_N is a synchronous request. The IM library should wait until receiving either an _X_I_M___O_P_E_N___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__OOPPEENN__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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 _X_I_M___O_P_E_N___R_E_P_L_Y 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 indi‐ cates 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 applica‐ tion 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 LISTofXI‐ CATTR. _X_I_M___C_L_O_S_E message requests to shutdown the logical connec‐ tion between the IM library and the IM Server. XXIIMM__CCLLOOSSEE ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 unused _X_I_M___C_L_O_S_E is a synchronous request. The IM library should wait until receiving either an _X_I_M___C_L_O_S_E___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__CCLLOOSSEE__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 unused _4_._5_. _E_v_e_n_t _F_l_o_w _C_o_n_t_r_o_l An IM Server must send _X_I_M___S_E_T___E_V_E_N_T___M_A_S_K message to the IM library in order for events to be forwarded to the IM 1188 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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. XXIIMM__SSEETT__EEVVEENNTT__MMAASSKK ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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 synchro‐ nous flag on by the IM library. _X_I_M___S_E_T___E_V_E_N_T___M_A_S_K is an asynchronous request. The event masks are valid immediately after they are set until changed by another _X_I_M___S_E_T___E_V_E_N_T___M_A_S_K 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 individ‐ ual values. Using the Dynamic Event Flow model, an IM Server sends _X_I_M___R_E_G_I_S_T_E_R___T_R_I_G_G_E_R_K_E_Y_S message to the IM library before sending _X_I_M___O_P_E_N___R_E_P_L_Y message. Or the IM library may sup‐ pose that the IM Server uses the Static Event Flow model. XXIIMM__RREEGGIISSTTEERR__TTRRIIGGGGEERRKKEEYYSS ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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 _X_I_M___R_E_G_I_S_T_E_R___T_R_I_G_G_E_R_K_E_Y_S 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 _X_I_M___T_R_I_G_G_E_R___N_O_T_I_F_Y message that a key event matching either on‐keys or off‐keys has been occurred. XXIIMM__TTRRIIGGGGEERR__NNOOTTIIFFYY ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 1199 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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. _X_I_M___T_R_I_G_G_E_R___N_O_T_I_F_Y is a synchronous request. The IM library should wait until receiving either an _X_I_M___T_R_I_G_‐ _G_E_R___N_O_T_I_F_Y___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__TTRRIIGGGGEERR__NNOOTTIIFFYY__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _4_._6_. _E_n_c_o_d_i_n_g _N_e_g_o_t_i_a_t_i_o_n _X_I_M___E_N_C_O_D_I_N_G___N_E_G_O_T_I_A_T_I_O_N message requests to decide which encoding to be sent across the wire. When the negotiation fails, the fallback default encoding is Portable Character Encoding. XXIIMM__EENNCCOODDIINNGG__NNEEGGOOTTIIAATTIIOONN ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr))..sspp 66pp 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 _X_I_M___O_P_E_N message via XOpenIM(). The name of encod‐ ing may be registered with X Consortium. _X_I_M___E_N_C_O_D_I_N_G___N_E_G_O_T_I_A_T_I_O_N is a synchronous request. The IM library should wait until receiving either an _X_I_M___E_N_C_O_D_‐ _I_N_G___N_E_G_O_T_I_A_T_I_O_N___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. 2200 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__EENNCCOODDIINNGG__NNEEGGOOTTIIAATTIIOONN__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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 _4_._7_. _Q_u_e_r_y _t_h_e _s_u_p_p_o_r_t_e_d _e_x_t_e_n_s_i_o_n _p_r_o_t_o_c_o_l _l_i_s_t _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N message requests to query the IM exten‐ sions supported by the IM Server to which the client is being connected. XXIIMM__QQUUEERRYY__EEXXTTEENNSSIIOONN ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 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 mes‐ sage must be issued after sending _X_I_M___O_P_E_N 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 _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N message for that exten‐ sion, the IM Server responds with a _B_a_d_P_r_o_t_o_c_o_l error. If the IM Server encounters a request with an unknown MAJOR‐ OPCODE or MINOR‐OPCODE, it responds with a _B_a_d_P_r_o_t_o_c_o_l error. _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N is a synchronous request. The IM library should wait until receiving either an _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__QQUUEERRYY__EEXXTTEENNSSIIOONN__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 n byte length of extensions supported by both the IM library and the IM Server 2211 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 n LISTofEXT list of extensions supported by both the IM library and the IM Server _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N___R_E_P_L_Y message returns the list of exten‐ sions supported by both the IM library and the IM Server. If the list passed in _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N 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. _4_._8_. _S_e_t_t_i_n_g _I_M _V_a_l_u_e_s _X_I_M___S_E_T___I_M___V_A_L_U_E_S requests to set attributes to the IM. XXIIMM__SSEETT__IIMM__VVAALLUUEESS ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 n byte length of im‐attribute n LISTofXIMATTRIBUTE im‐attributes The im‐attributes in _X_I_M___S_E_T___I_M___V_A_L_U_E_S message are specified as a LISTofXIMATTRIBUTE, specifying the attributes to be set. Attributes other than the ones returned by _X_I_M___O_P_E_N___R_E_P_L_Y message should not be specified. _X_I_M___S_E_T___I_M___V_A_L_U_E_S is a synchronous request. The IM library should wait until receiving either an _X_I_M___S_E_T___I_M___V_A_L_‐ _U_E_S___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet, because it must receive the error attribute if _X_I_M___E_R_R_O_R message is returned. XXIIMM__SSEETT__IIMM__VVAALLUUEESS__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 unused _X_I_M___S_E_T___I_M___V_A_L_U_E_S___R_E_P_L_Y message returns the input‐method‐ID to distinguish replies from multiple IMs. _4_._9_. _G_e_t_t_i_n_g _I_M _V_a_l_u_e_s _X_I_M___G_E_T___I_M___V_A_L_U_E_S requests to query IM values supported by the IM Server currently being connected. 2222 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__GGEETT__IIMM__VVAALLUUEESS ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 n byte length of im‐attribute‐id n LISTofCARD16 im‐attribute‐id p unused, p=Pad(n) _X_I_M___G_E_T___I_M___V_A_L_U_E_S is a synchronous request. The IM library should wait until it receives either an _X_I_M___G_E_T___I_M___V_A_L_‐ _U_E_S___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__GGEETT__IIMM__VVAALLUUEESS__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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 _X_I_M___G_E_T___I_M___V_A_L_U_E_S___R_E_P_L_Y message. The order of the returned im‐attribute values cor‐ responds directly to that of the list passed with the _X_I_M___G_E_T___I_M___V_A_L_U_E_S message. _4_._1_0_. _C_r_e_a_t_i_n_g _a_n _I_C _X_I_M___C_R_E_A_T_E___I_C message requests to create an IC. XXIIMM__CCRREEAATTEE__IICC ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 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 _X_I_M___C_R_E_A_T_E___I_C message.), and it should not be set to zero. _X_I_M___C_R_E_A_T_E___I_C is a synchronous request which returns the input‐context‐ID. The IM library should wait until it receives either an _X_I_M___C_R_E_A_T_E___I_C___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__CCRREEAATTEE__IICC__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _4_._1_1_. _D_e_s_t_r_o_y_i_n_g _t_h_e _I_C _X_I_M___D_E_S_T_R_O_Y___I_C message requests to destroy the IC. 2233 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__DDEESSTTRROOYY__IICC ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _X_I_M___D_E_S_T_R_O_Y___I_C is a synchronous request. The IM library should not free its resources until it receives an _X_I_M___D_E_S_T_R_O_Y___I_C___R_E_P_L_Y message because _X_I_M___D_E_S_T_R_O_Y___I_C message may result in Callback packets such as _X_I_M___P_R_E_E_D_I_T___D_R_A_W and _X_I_M___P_R_E_E_D_I_T___D_O_N_E_. XXIIMM__DDEESSTTRROOYY__IICC__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _4_._1_2_. _S_e_t_t_i_n_g _I_C _V_a_l_u_e_s _X_I_M___S_E_T___I_C___V_A_L_U_E_S messages requests to set attributes to the IC. XXIIMM__SSEETT__IICC__VVAALLUUEESS ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 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 _X_I_M___S_E_T___I_C___V_A_L_U_E_S message are specified as a LISTofXICATTRIBUTE, specifying the attributes to be set. Attributes other than the ones returned by _X_I_M___O_P_E_N___R_E_P_L_Y message should not be specified. _X_I_M___S_E_T___I_C___V_A_L_U_E_S is a synchronous request. The IM library should wait until receiving either an _X_I_M___S_E_T___I_C___V_A_L_‐ _U_E_S___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet, because it must receive the error attribute if _X_I_M___E_R_R_O_R message is returned. XXIIMM__SSEETT__IICC__VVAALLUUEESS__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _4_._1_3_. _G_e_t_t_i_n_g _I_C _V_a_l_u_e_s _X_I_M___G_E_T___I_C___V_A_L_U_E_S message requests to query IC values sup‐ ported by the IM Server currently being connected. 2244 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__GGEETT__IICC__VVAALLUUEESS ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 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. _X_I_M___G_E_T___I_C___V_A_L_U_E_S is a synchronous request and returns each attribute with its values to show the correspondence. The IM library should wait until receiving either an _X_I_M___G_E_T___I_C___V_A_L_U_E_S___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. XXIIMM__GGEETT__IICC__VVAALLUUEESS__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 2 n byte length of ic‐attribute 2 unused n LISTofXICATTRIBUTE ic‐attribute _4_._1_4_. _S_e_t_t_i_n_g _I_C _F_o_c_u_s _X_I_M___S_E_T___I_C___F_O_C_U_S message requests to set the focus to the IC. XXIIMM__SSEETT__IICC__FFOOCCUUSS ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _X_I_M___S_E_T___I_C___F_O_C_U_S is an asynchronous request. _4_._1_5_. _U_n_s_e_t_t_i_n_g _I_C _F_o_c_u_s _X_I_M___U_N_S_E_T___I_C___F_O_C_U_S message requests to unset the focus to the focused IC. XXIIMM__UUNNSSEETT__IICC__FFOOCCUUSS ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _X_I_M___U_N_S_E_T___I_C___F_O_C_U_S is an asynchronous request. 2255 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 _4_._1_6_. _F_i_l_t_e_r_i_n_g _E_v_e_n_t_s Event filtering is mainly provided for BackEnd method to allow input method to capture X events transparently to clients. X Events are forwarded by _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T message. This message can be operated both synchronously and asyn‐ chronously. If the requester sets the synchronous flag, the receiver must send _X_I_M___S_Y_N_C___R_E_P_L_Y message back to the requester when all the data processing is done. _P_r_o_t_o_c_o_l _f_l_o_w _o_f _B_a_c_k_E_n_d _m_o_d_e_l With BackEnd method, the protocol flow can be classified into two methods in terms of synchronization, depending on the synchronous‐eventmask of _X_I_M___S_E_T___E_V_E_N_T___M_A_S_K 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 _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T or _X_I_M___C_O_M_M_I_T message as a syn‐ chronous request. Also, the IM Server needs to synchronously process the correspondent reply from the IM library and the following _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T message sent from the IM library when any of the event causes the IM Server to send _X_I_M___F_O_R_‐ _W_A_R_D___E_V_E_N_T or _X_I_M___C_O_M_M_I_T 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 _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T 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 _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T message to the IM Server as a synchronous request. Therefore, the reply to it from the IM Server will be put between the _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T message and its _X_I_M___S_Y_N_C___R_E_P_L_Y message. In case of sending _X_I_M___F_O_R_‐ _W_A_R_D___E_V_E_N_T or _X_I_M___C_O_M_M_I_T message, the IM Server should set the synchronous flag off. Because the synchronization can be done by the following _X_I_M___S_Y_N_C___R_E_P_L_Y message. _S_a_m_p_l_e _P_r_o_t_o_c_o_l _f_l_o_w _c_h_a_r_t _1 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 2266 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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─ENT│synchronous XFilterEvent │ or XIM_COMMIT │request ─│ (synchronous) │ ───────────│─ ─ │ ___ XNextEve─nt │ ─ │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─│ Fig.2 Sample Protocol Flow _S_a_m_p_l_e _P_r_o_t_o_c_o_l _f_l_o_w _c_h_a_r_t _2 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. 2277 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 ... 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─ensgseXSceatuIsCeFsocus │ ─ │Pendin_g__ Pending ─u│ntXiIlM_FORWARD_EVENT│ ││ sync cycl│e─is doXnIeM_SYNC ─ │ │ │─ │ │ │─ XIM_SYNC_REPLY │ │ XNextEve─nt ──│─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 XXIIMM__FFOORRWWAARRDD__EEVVEENNTT ((IIMM lliibbrraarryy ←←→→ IIMM SSeerrvveerr)) 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. 2288 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 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 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). _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T 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 _X_I_M___F_O_R_‐ _W_A_R_D___E_V_E_N_T message without synchronous bit, should set syn‐ chronous bit. If both ‘‘request event filtering’’ and ‘‘request lookupstring’’ flag are set, then both filtering and lookup should be done for the same event. _4_._1_7_. _S_y_n_c_h_r_o_n_i_z_i_n_g _w_i_t_h _t_h_e _I_M _S_e_r_v_e_r _X_I_M___S_Y_N_C message requests to synchronize the IM library and the IM Server. XXIIMM__SSYYNNCC ((IIMM lliibbrraarryy ←←→→ IIMM SSeerrvveerr)) 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 _X_I_M___S_Y_N_C 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 syn‐ chronized. XXIIMM__SSYYNNCC__RREEPPLLYY ((IIMM SSeerrvveerr ←←→→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID The side which receives _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T_, _X_I_M___C_O_M_M_I_T or any other message with synchronous bit, should process all XIM request before replying, and send _X_I_M___S_Y_N_C___R_E_P_L_Y message as the reply to the previous message. _4_._1_8_. _S_e_n_d_i_n_g _a _c_o_m_m_i_t_t_e_d _s_t_r_i_n_g When the IM Server commits a string, the IM Server sends either the committed string or list of KeySym, or both, by _X_I_M___C_O_M_M_I_T message. 2299 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__CCOOMMMMIITT ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 2 BITMASK16 flag #0001 synchronous #0002 XLookupChars #0004 XLookupKeySym #0006 XLookupBoth = XLookupChars | XLookupKeySym If flag is XLookupKeySym, the arguments continue as follows: 2 unused 4 KEYSYM KeySym If flag is XLookupChars, the arguments continue as fol‐ lows: 2 m byte length of committed string m LISTofBYTE committed string p unused, p = Pad(m) If flag is XLookupBoth, the arguments continue as fol‐ lows: 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 _X_I_M___C_O_M_M_I_T message without syn‐ chronous bit should set synchronous bit. _4_._1_9_. _R_e_s_e_t _I_C _X_I_M___R_E_S_E_T___I_C message requests to reset the status of IC in the IM Server. XXIIMM__RREESSEETT__IICC ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _X_I_M___R_E_S_E_T___I_C is a synchronous request. The IM library should wait until receiving either an _X_I_M___R_E_S_E_T___I_C___R_E_P_L_Y packet or an _X_I_M___E_R_R_O_R packet. 3300 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__RREESSEETT__IICC__RREEPPLLYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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) _X_I_M___R_E_S_E_T___I_C___R_E_P_L_Y message returns the input‐context‐ID to distinguish replies from multiple ICs. _4_._2_0_. _C_a_l_l_b_a_c_k_s 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. _4_._2_0_._1_. _N_e_g_o_t_i_a_t_i_n_g _g_e_o_m_e_t_r_y The IM Server sends _X_I_M___G_E_O_M_E_T_R_Y message to start geometry negotiation, if XIMStyle has XIMPreeditArea or XIMStatusArea set. XXIIMM__GGEEOOMMEETTRRYY ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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. _4_._2_0_._2_. _C_o_n_v_e_r_t_i_n_g _a _s_t_r_i_n_g XXIIMM__SSTTRR__CCOONNVVEERRSSIIOONN ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 2 CARD16 XIMStringConversionPosition 2 unused 4 CARD32 XIMCaretDirection 3311 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 #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 XIM‐ StringConversionType _X_I_M___S_T_R___C_O_N_V_E_R_S_I_O_N message may be used to start the string conversion from the IM Server. XXIIMM__SSTTRR__CCOONNVVEERRSSIIOONN__RREEPPLLYY ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 4 CARD32 XIMStringConversionFeedback XIMSTRCONVTEXT XIMStringConversionText _X_I_M___S_T_R___C_O_N_V_E_R_S_I_O_N___R_E_P_L_Y message returns the string to be converted and the feedback information array. _4_._2_0_._3_. _P_r_e_e_d_i_t _C_a_l_l_b_a_c_k_s The IM Server sends _X_I_M___P_R_E_E_D_I_T___S_T_A_R_T message to call the XIMPreeditStartCallback function. XXIIMM__PPRREEEEDDIITT__SSTTAARRTT ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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. XXIIMM__PPRREEEEDDIITT__SSTTAARRTT__RREEPPLLYY ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 3322 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 2 CARD16 input‐context‐ID 4 INT32 return value _X_I_M___P_R_E_E_D_I_T___S_T_A_R_T___R_E_P_L_Y message returns the input‐context‐ID to distinguish replies from multiple IC’s. The return value contains the return value of the function XIMPreeditStart‐ Callback. The IM Server sends _X_I_M___P_R_E_E_D_I_T___D_R_A_W message to call the XIMPreeditDrawCallback function. XXIIMM__PPRREEEEDDIITT__DDRRAAWW ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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’’ 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 _X_I_M___P_R_E_E_D_I_T___C_A_R_E_T message to call the PreeditCaretCallback function. XXIIMM__PPRREEEEDDIITT__CCAARREETT ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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 3333 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 #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 XIMPreeditCaretCall‐ backStruct. Since this callback sets the caret position, its reply must be sent synchronously. XXIIMM__PPRREEEEDDIITT__CCAARREETT__RREEPPLLYY ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 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 _X_I_M___P_R_E_E_D_I_T___D_O_N_E message to call the XIMPreeditDoneCallback function. XXIIMM__PPRREEEEDDIITT__DDOONNEE ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID _4_._2_0_._4_. _P_r_e_e_d_i_t _s_t_a_t_e _n_o_t_i_f_y XXIIMM__PPRREEEEDDIITTSSTTAATTEE ((IIMM SSeerrvveerr →→ IIMM LLiibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 4 BITMASK32 XIMPreeditState #x0000000 XIMPreeditUnknown #x0000001 XIMPreeditEnable #x0000002 XIMPreeditDisable _X_I_M___P_R_E_E_D_I_T_S_T_A_T_E message is used to call the XIMPreedit‐ StateNotifyCallback function. _4_._2_0_._5_. _S_t_a_t_u_s _C_a_l_l_b_a_c_k_s The IM Server sends _X_I_M___S_T_A_T_U_S___S_T_A_R_T message to call the 3344 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XIMStatusStartCallback function. XXIIMM__SSTTAATTUUSS__SSTTAARRTT ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID The IM Server sends _X_I_M___S_T_A_T_U_S___D_R_A_W message to call the XIM‐ StatusDrawCallback function. XXIIMM__SSTTAATTUUSS__DDRRAAWW ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 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. 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 XIMStatus‐ DrawCallbackStruct. The IM Server sends _X_I_M___S_T_A_T_U_S___D_O_N_E message to call the XIM‐ StatusDoneCallback function. XXIIMM__SSTTAATTUUSS__DDOONNEE ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 3355 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 _5_. _A_c_k_n_o_w_l_e_d_g_e_m_e_n_t_s 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. _6_. _R_e_f_e_r_e_n_c_e_s All of the following documents are X Consortium standards available from MIT: [1] Scheifler, Robert W., _‘_‘_X _W_i_n_d_o_w _S_y_s_t_e_m _P_r_o_t_o_c_o_l _V_e_r_s_i_o_n _1_1_’_’ [2] Scheifler, Robert W. etc., _‘_‘_X_l_i_b _− _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_‐ _f_a_c_e_’_’ 3366 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 AAppppeennddiixx AA CCoommmmoonn EExxtteennssiioonnss Extension opcodes and packet names (e.g. _X_I_M___E_X_T___S_E_T___E_V_E_N_T___M_A_S_K ) for additional extensions may be registered with X Consortium. The following is a commonly well‐known extended packet. ((11)) EExxtteennssiioonn ttoo mmaanniippuullaattee tthhee eevveenntt hhaannddlliinngg _X_I_M___E_X_T___S_E_T___E_V_E_N_T___M_A_S_K message specifies the set of event masks that the IM library should manipulate. XXIIMM__EEXXTT__SSEETT__EEVVEENNTT__MMAASSKK ((IIMM SSeerrvveerr →→ IIMM lliibbrraarryy)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 4 EVENTMASK filter‐event‐mask (*1) 4 EVENTMASK intercept‐event‐mask (*2) 4 EVENTMASK select‐event‐mask (*3) 4 EVENTMASK forward‐event‐mask (*4) 4 EVENTMASK 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 _X_I_M___S_Y_N_C___R_E_P_L_Y message to the IM Server. This request is valid after the ic is created. ((22)) EExxtteennssiioonn ffoorr iimmpprroovveemmeenntt ooff ppeerrffoorrmmaannccee The following requests may be used for improvement of per‐ formance. _X_I_M___E_X_T___F_O_R_W_A_R_D___K_E_Y_E_V_E_N_T message may be used instead of _X_I_M___F_O_R_W_A_R_D___E_V_E_N_T message. 3377 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XXIIMM__EEXXTT__FFOORRWWAARRDD__KKEEYYEEVVEENNTT ((IIMM SSeerrvveerr ←←→→ IIMM lliibbrraarryy)) 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 3388 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 _X_I_M___E_X_T___M_O_V_E 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. XXIIMM__EEXXTT__MMOOVVEE ((IIMM lliibbrraarryy →→ IIMM SSeerrvveerr)) 2 CARD16 input‐method‐ID 2 CARD16 input‐context‐ID 2 INT16 X 2 INT16 Y _X_I_M___E_X_T___M_O_V_E message is a asynchronous request. 3399 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 AAppppeennddiixx BB TThhee lliisstt ooff ttrraannssppoorrtt ssppeecciiffiicc IIMM SSeerrvveerr aaddddrreessss ffoorrmmaatt rreeggiisstteerreedd The following format represents the ATOM contained in _X_I_M___S_E_R_V_E_R_S property and the string returned from the request converting selection target LOCALES and TRANSPORT. ‘‘{@_c_a_t_e_g_o_r_y=[_v_a_l_u_e,...]}...’’ The following categories are currently registered. sseerrvveerr : IM Server name (used for XIM_SERVERS) llooccaallee : XPG4 locale name (LOCALES) ttrraannssppoorrtt : transport‐specific name (TRANSPORT) The preregistered formats for transport‐specific names are as follows: TTCCPP//IIPP NNaammeess The following syntax should be used for system internal domain names: <_l_o_c_a_l _n_a_m_e> ::= ‘‘local/’’<_h_o_s_t_n_a_m_e>‘‘:’’<_p_a_t_h_n_a_m_e> Where <_p_a_t_h_n_a_m_e> is a path name of socket address. IM Server’s name should be set to <_p_a_t_h_n_a_m_e> to run multiple IM Server at the same time The following syntax should be used for Internet domain names: <_T_C_P _n_a_m_e> ::= ‘‘tcp/’’<_h_o_s_t_n_a_m_e>‘‘:’’<_i_p_p_o_r_t_n_u_m_b_e_r> where <_h_o_s_t_n_a_m_e> is either symbolic (such as expo.lcs.mit.edu) or numeric decimal (such as 18.30.0.212). The <_i_p_p_o_r_t_n_u_m_b_e_r> 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 DDEECCnneett NNaammeess The following syntax should be used for DECnet names: 4400 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 <_D_E_C_n_e_t _n_a_m_e> ::= ‘‘decnet/’’<_n_o_d_e_n_a_m_e>‘‘::IMSERVER$’’<_o_b_j_n_a_m_e> where <_n_o_d_e_n_a_m_e> is either symbolic (such as SRVNOD) or the numeric decimal form of the DECnet address (such as 44.70). The <_o_b_j_n_a_m_e> is normal, case‐insensitive DECnet object name. For example: DECNET/SRVNOD::IMSERVER$DEFAULT decnet/44.70::IMSERVER$other XX NNaammeess The following syntax should be used for X names: <_X _n_a_m_e> ::= ‘‘X/’’ If a given category has multiple values, the value is evalu‐ ated in order of setting. 4411 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 AAppppeennddiixx CC PPrroottooccooll nnuummbbeerr MMaajjoorr PPrroottooccooll nnuummbbeerr XIM_CONNECT #001 XIM_CONNECT_REPLY #002 XIM_DISCONNECT #003 XIM_DISCONNECT_REPLY #004 XIM_AUTH_REQUIRED #010 XIM_AUTH_REPLY #011 XIM_AUTH_NEXT #012 XIM_AUTH_SETUP #013 XIM_AUTH_NG #014 XIM_ERROR #020 XIM_OPEN #030 XIM_OPEN_REPLY #031 XIM_CLOSE #032 XIM_CLOSE_REPLY #033 XIM_REGISTER_TRIGGERKEYS #034 XIM_TRIGGER_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_FORWARD_EVENT #060 XIM_SYNC #061 XIM_SYNC_REPLY #062 XIM_COMMIT #063 XIM_RESET_IC #064 XIM_RESET_IC_REPLY #065 4422 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 XIM_GEOMETRY #070 XIM_STR_CONVERSION #071 XIM_STR_CONVERSION_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_STATUS_DRAW #080 XIM_STATUS_DONE #081 XIM_PREEDITSTATE #082 (*) The IM Server’s extension protocol number should be more than #128. 4433 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 AAppppeennddiixx DD IImmpplleemmeennttaattiioonn TTiippss ((11)) FFrroonnttEEnndd MMeetthhoodd 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 _X_I_M___Q_U_E_R_Y___E_X_T_E_N_‐ _S_I_O_N message. The IM Server may send _X_I_M___E_X_T___S_E_T___E_V_E_N_T___M_A_S_K message with intercept‐event‐mask, forward‐event‐mask, and synchronous‐event‐mask values set after replying _X_I_M___Q_U_E_R_Y___E_X_T_E_N_S_I_O_N___R_E_P_L_Y message. FrontEnd method can be implemented in a couple of ways depending on how the IM Server utilize _X_I_M___E_X_T___S_E_T___E_V_E_N_T___M_A_S_K 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─_NT │ │─_________________ │ │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 │ │ │ │ │ │ │ │ │ │ To pursuit a maximum performance regardless of the 4444 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 preediting mode, the IM Server may use the dynamic event flow with the following sample protocol sequence. 4455 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 ... 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─_IFY │ │─_________________ │ │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: ‘‘some strings’’‘‘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 _X_I_M___R_E_G_I_S_‐ _T_E_R___T_R_I_G_G_E_R_K_E_Y_S message. In this method, Both the IM Server and the IM client select the same events on the same client’s window, so that the events are delivered to both of the IM Server and the client. The preediting on and off states are expressed by whether the key events are filtered or not. The sample protocol sequence are as follows: 4466 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 <> ... 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─_NT ││─___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 │ │ │ │ │ │ │ │ <> ... 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─_IFY ││─___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 amount of the performance acceleration is not as good as the method described above. In general, the FrontEnd method requires some 4477 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 synchronization to some of the X protocols, such as the ChangeWindowAttribute protocol for the event mask change or the GrabKey protocol, since it relies on the X’s principal event dispatching mechanism. Any X protocol bindings do not consider the synchronization might cause some mis‐synchro‐ nization between the IM clients and the IM Server. 4488 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 ((22)) TTrraannssppoorrtt LLaayyeerr 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: _T_h_e _p_r_o_t_o_c_o_l _l_a_y_e_r implements overall function of XIM and calls the interface layer functions when it needs to commu‐ nicate to IM Server. _T_h_e _i_n_t_e_r_f_a_c_e _l_a_y_e_r separates the implementation of the transport layer from the protocol layer, in other words, it provides implementation independent hook for the transport layer functions. _T_h_e _t_r_a_n_s_p_o_r_t _l_a_y_e_r 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". _C_o_n_n_e_c_t_i_o_n 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. ──────────────────────────────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r _C_o_n_t_e_n_t_s 4499 │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ lliibbXX1111 11..33..22 │ │ ───────────────────────┼──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼──────────────────────────────────────────────── ───────────────────────┼──────────────────────────────────────────────── 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 connects Window window │ IMS Window ID Atom message_type │ XInternAtom(display, ‘‘_XIM_XCONNECT’’, False) int format │ 32 long data.l[0] │ client communication window ID long data.l[1] │ client‐major‐transport‐version (*1) long data.l[2] │ client‐major‐transport‐version (*1) ───────────────────────┴──────────────────────────────────────────────── In order to establish the connection (to notify the IM Server communication window), the IM Server sends a ClientMessage in the following event’s format to the client communication window. 5500 │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ lliibbXX1111 11..33..22 │ │ Table D‐2; The Clie│ntMessage sent by IM Server. │ ───────────────────────┼─────────────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼─────────────────────────────────────────────────────── 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 connects Window window │ client communication window ID Atom message_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 ┌──────────────────┬───────────────────────────────────────┐ │_T_r_a_n_s_p_o_r_t_‐_v_e_r_s_i_o_n │ _r_e_a_d_/_w_r_i_t_e │ ├────────┬─────────┼───────────────────────────────────────┤ │ _m_a_j_o_r │ _m_i_n_o_r │ │ ├────────┼─────────┼───────────────────────────────────────┤ │ 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 │ └────────┴─────────┴───────────────────────────────────────┘ only‐CM : data is sent via a ClientMessage multi‐CM : data is sent via multiple ClientMessages Property‐with‐CM : data is written in Property, and its Atom is send via ClientMessage PropertyNotify : data is written in Property, and its Atom is send via PropertyNotify The method to decide major/minor‐transport‐version is as follows: 5511 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 (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. _r_e_a_d_/_w_r_i_t_e The data is transferred via either ClientMessage or Window Property in the X Window System. _F_o_r_m_a_t _f_o_r _t_h_e _d_a_t_a _f_r_o_m _t_h_e _C_l_i_e_n_t _t_o _t_h_e _I_M _S_e_r_v_e_r _C_l_i_e_n_t_M_e_s_s_a_g_e If data is sent via ClientMessage event, the for‐ mat is as follows: Table D‐4; The ClientMessage event’s format (first or middle) ───────────────────────┬──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼──────────────────────────────────────────────── 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 connects 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) ───────────────────────┴──────────────────────────────────────────────── 5522 │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ lliibbXX1111 11..33..22 │ │ Table D‐5; The ClientMe│ssage event’s format (only or│last) │ ───────────────────────┼──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼──────────────────────────────────────────────── 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 connects Window window │ IMS communication window ID Atom message_type │ XInternAtom(display, ‘‘_XIM_PROTOCOL’’, 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. _P_r_o_p_e_r_t_y 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: 5533 │ │ │ │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ │ lliibbXX1111 11..33..22 │ │ │ │ Table D‐6; The XCh│ang│eProperty event’s format │ │ ────────────────────┼──┼───────────────────────────── _A_r_g_u_m_e_n_t │ _C│_o_n_t_e_n_t_s ────────────────────┼──┼───────────────────────────── Display *display │ T│he display to which connects Window window │ I│MS communication window ID Atom property │ r│ead/write property Atom (*1) Atom type │ X│A_STRING int format │ 8│ int mode │ P│ropModeAppend u_char *data │ r│ead/write DATA int nelements │ l│ength of DATA ────────────────────┴──┼───────────────────────────── │ │ │ (*1) The read/write pro│perty ATOM allocates the following strings │by XXIInntteerrnnAAttoomm. ‘‘_clientXXX’│’ │ The client changes the │property with the mode of PropModeAppend and the │IM Server will read it with the delete mode i.e. (d│elete = True). │ If Atom is notified via│ClientMessage event, the format of the ClientMes│sage is as follows: │ Table D‐7; The ClientMe│ssage event’s format to send Atom│of property │ ───────────────────────┼──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼──────────────────────────────────────────────── 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 connects Window window │ IMS communication window ID Atom message_type │ XInternAtom(display, ‘‘_XIM_PROTOCOL’’, False) int format │ 32 long data.l[0] │ length of read/write property Atom long data.l[1] │ read/write property Atom ───────────────────────┴──────────────────────────────────────────────── _F_o_r_m_a_t _f_o_r _t_h_e _d_a_t_a _f_r_o_m _t_h_e _I_M _S_e_r_v_e_r _t_o _t_h_e _C_l_i_e_n_t _C_l_i_e_n_t_M_e_s_s_a_g_e The format of the ClientMessage is as follows: Table D‐8; The ClientMessage event’s format (first or middle) 5544 │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ lliibbXX1111 11..33..22 │ │ ───────────────────────┼──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼──────────────────────────────────────────────── 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 connects 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) ───────────────────────┴──────────────────────────────────────────────── 5555 │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ lliibbXX1111 11..33..22 │ │ Table D‐9; The Clien│tMessage event’s format (only │or last) │ ────────────────────┼──┬──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ │ _C_o_n_t_e_n_t_s ────────────────────┼──┼──────────────────────────────────────────────── 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 connects Window window │ │ client communication window ID Atom message_ty│pe │ XInternAtom(display, ‘‘_XIM_PROTOCOL’’, False) int format │ │ 8 char data.b[20]│ │ (read/write DATA : MAX 20 byte) (*1) ────────────────────┼──┴──────────────────────────────────────────────── │ │ │ (*1) If the data siz│e is smaller than 20 bytes, all data other │than available data must be 0. │ _P_r_o_p_e_r_t_y │ │ In the case of large│data, data will be sent via the Window Property │for the efficiency. There are the following two me│thods to notify Property, and transport‐version is│decided which method is used. │ │ (1) The XChangeProp│erty function is used to store data in the IMS│communication window, and Atom of the pro│perty is sent via the ClientMessage e│vent. │ (2) The XChangeProp│erty function is used to store data in the IMS│communication window, and Atom of the pro│perty is sent via PropertyNo‐ tify event. │ │ The arguments of the│XChangeProperty are as fol‐ lows: │ │ Table D‐10; The XC│hangeProperty event’s format │ ────────────────────┼────────────────────────────────── _A_r_g_u_m_e_n_t │ _C_o_n_t_e_n_t_s ────────────────────┼────────────────────────────────── 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 │ PropModeAppend 5566 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 ─────────────────────────────────────────────────────── _A_r_g_u_m_e_n_t _C_o_n_t_e_n_t_s ────────────────────┬────────────────────────────────── u_char *data │ read/write DATA int nelements │ length of DATA ────────────────────┴────────────────────────────────── (*1) The read/write property ATOM allocates some strings, which are not allocated by the client, by XXIInntteerrnnAAttoomm. 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: 5577 │ │ │ XX IInnppuutt MMeetthhoodd PPrroottooccooll │ lliibbXX1111 11..33..22 │ │ Table D‐11; The ClientM│essage event’s format to send Atom│of property │ ───────────────────────┼──────────────────────────────────────────────── _S_t_r_u_c_t_u_r_e _M_e_m_b_e_r │ _C_o_n_t_e_n_t_s ───────────────────────┼──────────────────────────────────────────────── 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 connects Window window │ client communication window ID Atom message_type │ XInternAtom(display, ‘‘_XIM_PROTOCOL’’, False) int format │ 32 long data.l[0] │ length of read/write property ATOM long data.l[1] │ read/write property ATOM ───────────────────────┴──────────────────────────────────────────────── _C_l_o_s_i_n_g _C_o_n_n_e_c_t_i_o_n If the client disconnect with the IM Server, shutdown function should free the communication window proper‐ ties and etc.. 5588 XX IInnppuutt MMeetthhoodd PPrroottooccooll lliibbXX1111 11..33..22 TTaabbllee ooff CCoonntteennttss 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 ............................. 20 4.7. Query the supported extension protocol list ...... 21 4.8. Setting IM Values ................................ 22 4.9. getting IM Values ................................ 22 4.10. Creating an IC .................................. 23 4.11. Destroying the IC ............................... 23 4.12. Setting IC Values ............................... 24 4.13. Getting IC Values ............................... 24 4.14. Setting IC Focus ................................ 25 4.15. Unsetting IC Focus .............................. 25 4.16. Filtering Events ................................ 26 4.17. Synchronizing with the IM Server ................ 29 4.18. Sending a committed string ...................... 29 4.19. Reset IC ........................................ 30 4.20. Callbacks ....................................... 31 4.20.1. Negotiating geometry .......................... 31 4.20.2. Converting a string ........................... 31 4.20.3. Preedit Callbacks ............................. 32 4.20.4. Preedit state notify .......................... 34 4.20.5. Status Callbacks .............................. 34 5. Acknowledgements ................................... 36 6. References ......................................... 36 Appendix A − Common Extensions ........................ 37 Appendix B − The list of transport specific IM Server names registered ............................... 40 Appendix C − Protocol number .......................... 42 Appendix D − Implementation Tips ...................... 44