1mThe XIM Transport Specification0m 1mRevision 0.10m 1mX Version 11, Release 6.40m 4mTakashi24m 4mFujiwara0m FUJITSU LIMITED 4mABSTRACT0m This specification describes the transport layer interfaces between Xlib and IM Server, which makes various channels usable such as X protocol or, TCP/IP, DECnet and etc. Copyright © 1994 by FUJITSU LIMITED 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 makes no representa- tions about the suitability for any purpose of the informa- tion in this document. This documentation is provided as is without express or implied warranty. Copyright © 1994 X Consortium 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 with- out 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 fol- lowing 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. 4mX24m 4mWindow24m 4mSystem24m is a trademark of X Consortium, Inc. 1m1. Introduction0m 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: 4mThe24m 4mprotocol24m 4mlayer0m implements overall function of XIM and calls the interface layer functions when it needs to commu- nicate to IM Server. 4mThe24m 4minterface24m 4mlayer0m separates the implementation of the transport layer from the protocol layer, in other words, it provides implementation independent hook for the transport layer functions. 4mThe24m 4mtransport24m 4mlayer0m handles actual data communication with IM Server. It is done by a set of several functions named transporters. This specification describes the interface layer and the transport layer, which makes various communication channels usable such as X protocol or, TCP/IP, DECnet, STREAM, etc., and provides the information needed for adding another new transport layer. In addition, sample implementations for the transporter using the X connection is described in sec- tion 4. 1m2. Initialization0m 1m2.1. Registering structure to initialize0m The structure typed as TransportSW contains the list of the transport layer the specific implementations supports. typedef struct { char *transport_name; Bool (*config); } TransportSW; 4mtransport_name24m name of transport(*1) 4mconfig24m initial configuration function ----------- (*1) Refer to "The Input Method Protocol: Appendix B" 1m10m 1mXIM Transport Specification X11, Release 6.40m A sample entry for the Xlib supporting transporters is shown below: TransportSW _XimTransportRec[] = { /* char 4m*:0m 4m*24m 4mtransport_name24m, Bool 4m(*config)()0m */ ``X'', _XimXConf, ``tcp'', _XimTransConf, ``local'', _XimTransConf, ``decnet'', _XimTransConf, ``streams'', _XimTransConf, (char *)NULL, (Bool (*)())NULL, }; 1m2.2. Initialization function0m The following function will be called once when Xlib config- ures the transporter functions. Bool (*config)(4mim24m, 4mtransport_data24m) XIM 4mim24m; char 4m*transport_data24m; 4mim24m Specifies XIM structure address. 4mtransport_data0m Specifies the data specific to the transporter, in IM Server address. (*1) This function must setup the transporter function pointers. The actual 4mconfig24m function will be chosen by IM Server at the pre-connection time, matching by the 4mtransport_name0m specified in the 1m_XimTransportRec 22marray; The specific mem- bers of XimProto structure listed below must be initialized so that point they appropriate transporter functions. If the specified transporter has been configured success- fully, this function returns True. There is no Alternative Entry for config function itself. The structure XimProto contains the following function pointers: ----------- (*1) Refer to "The Input Method Protocol: Appendix B" 1m20m 1mXIM Transport Specification X11, Release 6.40m Bool (*connect)(); /* Open connection */ Bool (*shutdown)(); /* Close connection */ Bool (*write)(); /* Write data */ Bool (*read)(); /* Read data */ Bool (*flush)(); /* Flush data buffer */ Bool (*register_dispatcher)();/* Register asynchronous data handler */ Bool (*call_dispatcher)();/* Call dispatcher */ These functions are called when Xlib needs to communicate the IM Server. These functions must process the appropriate procedure described below. 1m3. The interface/transport layer functions0m Following functions are used for the transport interface. Table 3-1; The Transport Layer Functions. +-----------------------+---------------------+----------+ | 1mAlternative Entry 22m| 1mXimProto member 22m| 1mSection 22m| | 1m(Interface Layer) 22m| 1m(Transport Layer) 22m| | +-----------------------+---------------------+----------+ |1m_XimConnect 22m| connect | 3.1 | +-----------------------+---------------------+----------+ |1m_XimShutdown 22m| shutdown | 3.2 | +-----------------------+---------------------+----------+ |1m_XimWrite 22m| write | 3.3 | +-----------------------+---------------------+----------+ |1m_XimRead 22m| read | 3.4 | +-----------------------+---------------------+----------+ |1m_XimFlush 22m| flush | 3.5 | +-----------------------+---------------------+----------+ |1m_XimRegisterDispatcher 22m| register_dispatcher | 3.6 | +-----------------------+---------------------+----------+ |1m_XimCallDispatcher 22m| call_dispatcher | 3.7 | +-----------------------+---------------------+----------+ The Protocol layer calls the above functions using the Alternative Entry in the left column. The transport imple- mentation defines XimProto member function in the right col- umn. The Alternative Entry is provided so as to make easier to implement the Protocol Layer. 1m3.1. Opening connection0m When 1mXOpenIM 22mis called, the following function is called to connect with the IM Server. Bool (*connect)(4mim24m) XIM 4mim24m; 1m30m 1mXIM Transport Specification X11, Release 6.40m 4mim24m Specifies XIM structure address. This function must establishes the connection to the IM Server. If the connection is established successfully, this function returns True. The Alternative Entry for this func- tion is: Bool _XimConnect(4mim24m) XIM 4mim24m; 4mim24m Specifies XIM structure address. 1m3.2. Closing connection0m When 1mXCloseIM 22mis called, the following function is called to disconnect the connection with the IM Server. The Alterna- tive Entry for this function is: Bool (*shutdown)(4mim24m) XIM 4mim24m; 4mim24m Specifies XIM structure address. This function must close connection with the IM Server. If the connection is closed successfully, this function returns True. The Alternative Entry for this function is: Bool _XimShutdown(4mim24m) XIM 4mim24m; 4mim24m Specifies XIM structure address. 1m3.3. Writing data0m The following function is called, when Xlib needs to write data to the IM Server. Bool (*write)(4mim24m, 4mlen24m, 4mdata24m) XIM 4mim24m; INT16 4mlen24m; XPointer 4mdata24m; 4mim24m Specifies XIM structure address. 4mlen24m Specifies the length of writing data. 4mdata24m Specifies the writing data. 1m40m 1mXIM Transport Specification X11, Release 6.40m This function writes the 4mdata24m to the IM Server, regardless of the contents. The number of bytes is passed to 4mlen24m. The writing data is passed to 4mdata24m. If data is sent success- fully, the function returns True. Refer to "The Input Method Protocol" for the contents of the writing data. The Alterna- tive Entry for this function is: Bool _XimWrite(4mim24m, 4mlen24m, 4mdata24m) XIM 4mim24m; INT16 4mlen24m; XPointer 4mdata24m; 4mim24m Specifies XIM structure address. 4mlen24m Specifies the length of writing data. 4mdata24m Specifies the writing data. 1m3.4. Reading data0m The following function is called when Xlib waits for response from IM server synchronously. Bool (*read)(4mim24m, 4mread_buf24m, 4mbuf_len24m, 4mret_len24m) XIM 4mim24m; XPointer 4mread_buf24m; int 4mbuf_len24m; int 4m*ret_len24m; 4mim24m Specifies XIM structure address. 4mread_buf24m Specifies the buffer to store data. 4mbuf_len24m Specifies the size of the 4mbuffer0m 4mret_len24m Specifies the length of stored data. This function stores the read data in 4mread_buf24m, which size is specified as 4mbuf_len24m. The size of data is set to 4mret_len24m. This function return True, if the data is read normally or reading data is completed. The Alternative Entry for this function is: 1m50m 1mXIM Transport Specification X11, Release 6.40m Bool _XimRead(4mim24m, 4mret_len24m, 4mbuf24m, 4mbuf_len24m, 4mpredicate24m, 4mpredicate_arg24m) XIM 4mim24m; INT16 4m*ret_len24m; XPointer 4mbuf24m; int 4mbuf_len24m; Bool 4m(*predicate)()24m; XPointer 4mpredicate_arg24m; 4mim24m Specifies XIM structure address. 4mret_len24m Specifies the size of the 4mdata24m buffer. 4mbuf24m Specifies the buffer to store data. 4mbuf_len24m Specifies the length of 4mbuffer24m. 4mpredicate24m Specifies the predicate for the XIM data. 4mpredicate_arg0m Specifies the predicate specific data. The predicate procedure indicates whether the 4mdata24m is for the XIM or not. 4mlen24m This function stores the read data in 4mbuf24m, which size is specified as 4mbuf_len24m. The size of data is set to 4mret_len24m. If 4mpreedicate()24m returns True, this function returns True. If not, it calls the registered callback function. The procedure and its arguments are: Bool (*predicate)(4mim24m, 4mlen24m, 4mdata24m, 4mpredicate_arg24m) XIM 4mim24m; INT16 4mlen24m; XPointer 4mdata24m; XPointer 4mpredicate_arg24m; 4mim24m Specifies XIM structure address. 4mlen24m Specifies the size of the 4mdata24m buffer. 4mdata24m Specifies the buffer to store data. 4mpredicate_arg0m Specifies the predicate specific data. 1m3.5. Flushing buffer0m The following function is called when Xlib needs to flush the data. 1m60m 1mXIM Transport Specification X11, Release 6.40m void (*flush)(4mim24m) XIM 4mim24m; 4mim24m Specifies XIM structure address. This function must flush the data stored in internal buffer on the transport layer. If data transfer is completed, the function returns True. The Alternative Entry for this func- tion is: void _XimFlush(4mim24m) XIM 4mim24m; 4mim24m Specifies XIM structure address. 1m3.6. Registering asynchronous data handler0m Xlib needs to handle asynchronous response from IM Server. This is because some of the XIM data occur asynchronously to X events. Those data will be handled in the 4mFilter24m, and the 4mFilter0m will call asynchronous data handler in the protocol layer. Then it calls dispatchers in the transport layer. The dis- patchers are implemented by the protocol layer. This func- tion must store the information and prepare for later call of the dispatchers using 1m_XimCallDispatcher22m. When multiple dispatchers are registered, they will be called sequentially in order of registration, on arrival of asynchronous data. The register_dispatcher is declared as following: Bool (*register_dispatcher)(4mim24m, 4mdispatcher24m, 4mcall_data24m) XIM 4mim24m; Bool 4m(*dispatcher)()24m; XPointer 4mcall_data24m; 4mim24m Specifies XIM structure address. 4mdispatcher0m Specifies the dispatcher function to register. 4mcall_data24m Specifies a parameter for the 4mdispatcher24m. The dispatcher is a function of the following type: 1m70m 1mXIM Transport Specification X11, Release 6.40m Bool (*dispatcher)(4mim24m, 4mlen24m, 4mdata24m, 4mcall_data24m) XIM 4mim24m; INT16 4mlen24m; XPointer 4mdata24m; XPointer 4mcall_data24m; 4mim24m Specifies XIM structure address. 4mlen24m Specifies the size of the 4mdata24m buffer. 4mdata24m Specifies the buffer to store data. 4mcall_data24m Specifies a parameter passed to the register_dis- patcher. The dispatcher is provided by the protocol layer. They are called once for every asynchronous data, in order of regis- tration. If the data is used, it must return True. other- wise, it must return False. If the dispatcher function returns True, the Transport Layer assume that the data has been processed by the upper layer. The Alternative Entry for this function is: Bool _XimRegisterDispatcher(4mim24m, 4mdispatcher24m, 4mcall_data24m) XIM 4mim24m; Bool 4m(*dispatcher)()24m; XPointer 4mcall_data24m; 4mim24m Specifies XIM structure address. 4mdispatcher0m Specifies the dispatcher function to register. 4mcall_data24m Specifies a parameter for the 4mdispatcher24m. 1m3.7. Calling dispatcher0m The following function is used to call the registered dis- patcher function, when the asynchronous response from IM Server has arrived. Bool (*call_dispatcher)(4mim24m, 4mlen24m, 4mdata24m) XIM 4mim24m; INT16 4mlen24m; XPointer 4mdata24m; 4mim24m Specifies XIM structure address. 1m80m 1mXIM Transport Specification X11, Release 6.40m 4mlen24m Specifies the size of 4mdata24m buffer. 4mdata24m Specifies the buffer to store data. The call_dispatcher must call the dispatcher function, in order of their registration. 4mlen24m and 4mdata24m are the data passed to register_dispatcher. The return values are checked at each invocation, and if it finds True, it immediately return with true for its return value. It is depend on the upper layer whether the read data is XIM Protocol packet unit or not. The Alternative Entry for this function is: Bool _XimCallDispatcher(4mim24m, 4mlen24m, 4mdata24m) XIM 4mim24m; INT16 4mlen24m; XPointer 4mcall_data24m; 1m90m 1mXIM Transport Specification X11, Release 6.40m 1m4. Sample implementations for the Transport Layer0m Sample implementations for the transporter using the X con- nection is described here. 1m4.1. X Transport0m 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". 1m4.1.1. Connection0m 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 4-1; The ClientMessage sent to the IMS window. -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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. Table 4-2; The ClientMessage sent by IM Server. 1m100m 1mXIM Transport Specification X11, Release 6.40m -----------------------+------------------------------------------------------- 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------------- 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 combina- tion of major/minor-transport-version, as follows: Table 4-3; The read/write method and the major/minor-transport-version +------------------+---------------------------------------+ |1mTransport-version 22m| 1mread/write 22m| +--------+---------+---------------------------------------+ | 1mmajor 22m| 1mminor 22m| | +--------+---------+---------------------------------------+ | 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: 1m110m 1mXIM Transport Specification X11, Release 6.40m (1) The client sends 0 as major/minor-transport-ver- sion to the IM Server. The client must support all methods in Table 4-3. The client may send another number as major/minor-transport-version to use other method than the above in the future. (2) The IM Server sends its major/minor-transport-ver- sion number to the client. The client sends data using the method specified by the IM Server. (3) If major/minor-transport-version number is not available, it is regarded as 0. (*2) dividing size between ClientMessage and Property If data is sent via both of multi-CM and Property, specify the dividing size between ClientMessage and Property. The data, which is smaller than this size, is sent via multi-CM (or only-CM), and the data, which is lager than this size, is sent via Property. 1m4.1.2. read/write0m The data is transferred via either ClientMessage or Window Property in the X Window System. 1m4.1.2.1. Format for the data from the Client to the IM0m 1mServer0m 1mClientMessage0m If data is sent via ClientMessage event, the format is as follows: Table 4-4; The ClientMessage event's format (first or middle) -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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) -----------------------+------------------------------------------------ 1m120m 1mXIM Transport Specification X11, Release 6.40m Table 4-5; The ClientMessage event's format (only or last) -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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. 1mProperty0m In the case of large data, data will be sent via the Window Property for the efficiency. There are the fol- lowing two methods to notify Property, and transport- version is decided which method is used. (1) The XChangeProperty function is used to store data in the client communication window, and Atom of the stored data is notified to the IM Server via ClientMessage event. (2) The XChangeProperty function is used to store data in the client communication window, and Atom of the stored data is notified to the IM Server via PropertyNotify event. The arguments of the XChangeProperty are as follows: Table 4-6; The XChangeProperty event's format --------------------+-------------------------------- 1mArgument 22m| 1mContents0m --------------------+-------------------------------- Display *display | The display to which connects Window window | IMS communication window ID Atom property | read/write property Atom (*1) Atom type | XA_STRING int format | 8 int mode | PropModeAppend u_char *data | read/write DATA int nelements | length of DATA --------------------+-------------------------------- 1m130m 1mXIM Transport Specification X11, Release 6.40m (*1) The read/write property ATOM allocates the follow- ing strings by 1mXInternAtom22m. ``_clientXXX'' The client changes the property with the mode of Prop- ModeAppend and the IM Server will read it with the delete mode i.e. (delete = True). If Atom is notified via ClientMessage event, the format of the ClientMessage is as follows: Table 4-7; The ClientMessage event's format to send Atom of property -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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 -----------------------+------------------------------------------------ 1m4.1.2.2. Format for the data from the IM Server to the0m 1mClient0m 1mClientMessage0m The format of the ClientMessage is as follows: Table 4-8; The ClientMessage event's format (first or middle) -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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) -----------------------+------------------------------------------------ 1m140m 1mXIM Transport Specification X11, Release 6.40m Table 4-9; The ClientMessage event's format (only or last) -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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 | 8 char data.b[20] | (read/write DATA : MAX 20 byte) (*1) -----------------------+------------------------------------------------ (*1) If the data size is smaller than 20 bytes, all data other than available data must be 0. 1mProperty0m In the case of large data, data will be sent via the Window Property for the efficiency. There are the fol- lowing two methods to notify Property, and transport- version is decided which method is used. (1) The XChangeProperty function is used to store data in the IMS communication window, and Atom of the property is sent via the ClientMessage event. (2) The XChangeProperty function is used to store data in the IMS communication window, and Atom of the property is sent via PropertyNotify event. The arguments of the XChangeProperty are as follows: Table 4-10; The XChangeProperty event's format --------------------+---------------------------------- 1mArgument 22m| 1mContents0m --------------------+---------------------------------- 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 u_char *data | read/write DATA int nelements | length of DATA --------------------+---------------------------------- 1m150m 1mXIM Transport Specification X11, Release 6.40m (*1) The read/write property ATOM allocates some strings, which are not allocated by the client, by 1mXInternAtom22m. 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: Table 4-11; The ClientMessage event's format to send Atom of property -----------------------+------------------------------------------------ 1mStructure Member 22m| 1mContents0m -----------------------+------------------------------------------------ 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 -----------------------+------------------------------------------------ 1m4.1.3. Closing Connection0m If the client disconnect with the IM Server, shutdown func- tion should free the communication window properties and etc.. 1m5. References0m [1] Masahiko Narita and Hideki Hiura, 4m``The24m 4mInput24m 4mMethod0m 4mProtocol''0m 1m160m