The XIM Transport Specification Revision 0.1 X Version 11, Release 6.4

Takashi Fujiwara
FUJITSU LIMITED

ABSTRACT

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.

Permission to use, copy, modify, and distribute this documentation 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 representations about the suitability for any purpose of the information in this document. This documentation is provided as is without express or implied warranty.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation 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 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM 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 Consortium 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.

X Window System is a trademark of X Consortium, Inc.

1. IntroductionThe 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 protocolindependent of transport implementation. Each function ofthese layers are:The protocol layerimplements overall function of XIM and calls theinterface layer functions when it needs tocommunicate to IM Server.The interface layerseparates the implementation of the transportlayer from the protocol layer, in other words, itprovides implementation independent hook for thetransport layer functions.The transport layerhandles actual data communication with IM Server.It is done by a set of several functions namedtransporters.This specification describes the interface layer and thetransport layer, which makes various communication channelsusable such as X protocol or, TCP/IP, DECnet, STREAM, etc.,and provides the information needed for adding another newtransport layer. In addition, sample implementations forthe transporter using the X connection is described insection 4.2. Initialization2.1. Registering structure to initializeThe structure typed as TransportSW contains the list of thetransport layer the specific implementations supports.typedef struct {char transport_name;Bool (config);} TransportSW;transport_name name of transport(1)config initial configuration functionA sample entry for the Xlib supporting transporters is shownbelow:TransportSW _XimTransportRec[] = {/ char : transport_name, Bool (config)() / ‘‘X’’, _XimXConf,‘‘tcp’’, _XimTransConf,‘‘local’’, _XimTransConf,‘‘decnet’’, _XimTransConf,‘‘streams’’, _XimTransConf,(char )NULL, (Bool ()())NULL,};2.2. Initialization functionThe following function will be called once when Xlibconfigures the transporter functions.Bool (config)(im, transport_data)XIM im;char transport_data;im Specifies XIM structure address.transport_dataSpecifies the data specific to the transporter, inIM Server address. (1)This function must setup the transporter function pointers.The actual config function will be chosen by IM Server atthe pre-connection time, matching by the transport_namespecified in the _XimTransportRec array; The specificmembers of XimProto structure listed below must beinitialized so that point they appropriate transporterfunctions.If the specified transporter has been configuredsuccessfully, this function returns True. There is noAlternative Entry for config function itself.The structure XimProto contains the following functionpointers: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 communicatethe IM Server. These functions must process the appropriateprocedure described below.3. The interface/transport layer functionsFollowing functions are used for the transport interface.Table 3-1; The Transport Layer Functions.The Protocol layer calls the above functions using theAlternative Entry in the left column. The transportimplementation defines XimProto member function in the rightcolumn. The Alternative Entry is provided so as to makeeasier to implement the Protocol Layer.3.1. Opening connectionWhen XOpenIM is called, the following function is called toconnect with the IM Server.Bool (connect)(im)XIM im;im Specifies XIM structure address.This function must establishes the connection to the IMServer. If the connection is established successfully, thisfunction returns True. The Alternative Entry for thisfunction is:Bool _XimConnect(im)XIM im;im Specifies XIM structure address.3.2. Closing connectionWhen XCloseIM is called, the following function is called todisconnect the connection with the IM Server. TheAlternative Entry for this function is:Bool (shutdown)(im)XIM im;im Specifies XIM structure address.This function must close connection with the IM Server. Ifthe connection is closed successfully, this function returnsTrue. The Alternative Entry for this function is:Bool _XimShutdown(im)XIM im;im Specifies XIM structure address.3.3. Writing dataThe following function is called, when Xlib needs to writedata to the IM Server.Bool (write)(im, len, data)XIM im;INT16 len;XPointer data;im Specifies XIM structure address.len Specifies the length of writing data.data Specifies the writing data.This function writes the data to the IM Server, regardlessof the contents. The number of bytes is passed to len. Thewriting data is passed to data. If data is sentsuccessfully, the function returns True. Refer to "The InputMethod Protocol" for the contents of the writing data. TheAlternative Entry for this function is:Bool _XimWrite(im, len, data)XIM im;INT16 len;XPointer data;im Specifies XIM structure address.len Specifies the length of writing data.data Specifies the writing data.3.4. Reading dataThe following function is called when Xlib waits forresponse from IM server synchronously.Bool (read)(im, read_buf, buf_len, ret_len)XIM im;XPointer read_buf;int buf_len;int ret_len;im Specifies XIM structure address.read_buf Specifies the buffer to store data.buf_len Specifies the size of the bufferret_len Specifies the length of stored data.This function stores the read data in read_buf, which sizeis specified as buf_len. The size of data is set to ret_len.This function return True, if the data is read normally orreading data is completed.The Alternative Entry for this function is:Bool _XimRead(im, ret_len, buf, buf_len, predicate, predicate_arg)XIM im;INT16 ret_len;XPointer buf;int buf_len;Bool (predicate)();XPointer predicate_arg;im Specifies XIM structure address.ret_len Specifies the size of the data buffer.buf Specifies the buffer to store data.buf_len Specifies the length of buffer.predicate Specifies the predicate for the XIM data.predicate_argSpecifies the predicate specific data.The predicate procedure indicates whether the data is forthe XIM or not. len This function stores the read data inbuf, which size is specified as buf_len. The size of data isset to ret_len. If preedicate() returns True, this functionreturns True. If not, it calls the registered callbackfunction.The procedure and its arguments are:Bool (predicate)(im, len, data, predicate_arg)XIM im;INT16 len;XPointer data;XPointer predicate_arg;im Specifies XIM structure address.len Specifies the size of the data buffer.data Specifies the buffer to store data.predicate_argSpecifies the predicate specific data.3.5. Flushing bufferThe following function is called when Xlib needs to flushthe data.void (flush)(im)XIM im;im Specifies XIM structure address.This function must flush the data stored in internal bufferon the transport layer. If data transfer is completed, thefunction returns True. The Alternative Entry for thisfunction is:void _XimFlush(im)XIM im;im Specifies XIM structure address.3.6. Registering asynchronous data handlerXlib needs to handle asynchronous response from IM Server.This is because some of the XIM data occur asynchronously toX events.Those data will be handled in the Filter, and the Filterwill call asynchronous data handler in the protocol layer.Then it calls dispatchers in the transport layer. Thedispatchers are implemented by the protocol layer. Thisfunction must store the information and prepare for latercall of the dispatchers using _XimCallDispatcher.When multiple dispatchers are registered, they will becalled sequentially in order of registration, on arrival ofasynchronous data. The register_dispatcher is declared asfollowing:Bool (register_dispatcher)(im, dispatcher, call_data)XIM im;Bool (dispatcher)();XPointer call_data;im Specifies XIM structure address.dispatcherSpecifies the dispatcher function to register.call_data Specifies a parameter for the dispatcher.The dispatcher is a function of the following type:Bool (dispatcher)(im, len, data, call_data)XIM im;INT16 len;XPointer data;XPointer call_data;im Specifies XIM structure address.len Specifies the size of the data buffer.data Specifies the buffer to store data.call_data Specifies a parameter passed to theregister_dispatcher.The dispatcher is provided by the protocol layer. They arecalled once for every asynchronous data, in order ofregistration. If the data is used, it must return True.otherwise, it must return False.If the dispatcher function returns True, the Transport Layerassume that the data has been processed by the upper layer.The Alternative Entry for this function is:Bool _XimRegisterDispatcher(im, dispatcher, call_data)XIM im;Bool (dispatcher)();XPointer call_data;im Specifies XIM structure address.dispatcherSpecifies the dispatcher function to register.call_data Specifies a parameter for the dispatcher.3.7. Calling dispatcherThe following function is used to call the registereddispatcher function, when the asynchronous response from IMServer has arrived.Bool (*call_dispatcher)(im, len, data)XIM im;INT16 len;XPointer data;im Specifies XIM structure address.len Specifies the size of data buffer.data Specifies the buffer to store data.The call_dispatcher must call the dispatcher function, inorder of their registration. len and data are the datapassed to register_dispatcher.The return values are checked at each invocation, and if itfinds True, it immediately return with true for its returnvalue.It is depend on the upper layer whether the read data is XIMProtocol packet unit or not. The Alternative Entry for thisfunction is:Bool _XimCallDispatcher(im, len, data)XIM im;INT16 len;XPointer call_data; 1

XIM Transport Specification X11, Release 6.4

4. Sample implementations for the Transport LayerSample implementations for the transporter using the Xconnection is described here.4.1. X TransportAt the beginning of the X Transport connection for the XIMtransport mechanism, two different windows must be createdeither in an Xlib XIM or in an IM Server, with which theXlib and the IM Server exchange the XIM transports by usingthe ClientMessage events and Window Properties. In thefollowing, the window created by the Xlib is referred as the"client communication window", and on the other hand, thewindow created by the IM Server is referred as the "IMScommunication window".4.1.1. ConnectionIn order to establish a connection, a communication windowis created. A ClientMessage in the following event’s formatis sent to the owner window of XIM_SERVER selection, whichthe IM Server has created.Refer to "The Input Method Protocol" for the XIM_SERVERatom.Table 4-1; The ClientMessage sent to the IMS window.In order to establish the connection (to notify the IMServer communication window), the IM Server sends aClientMessage in the following event’s format to the clientcommunication window.Table 4-2; The ClientMessage sent by IM Server.(1) major/minor-transport-versionThe read/write method is decided by thecombination of major/minor-transport-version, asfollows:Table 4-3; The read/write method and the major/minor-transport-versionThe method to decide major/minor-transport-version isas follows:(1) The client sends 0 asmajor/minor-transport-version to the IM Server.The client must support all methods in Table 4-3.The client may send another number asmajor/minor-transport-version to use other methodthan the above in the future.(2) The IM Server sends itsmajor/minor-transport-version number to theclient. The client sends data using the methodspecified by the IM Server.(3) If major/minor-transport-version number is notavailable, it is regarded as 0.(2) dividing size between ClientMessage and PropertyIf data is sent via both of multi-CM and Property,specify the dividing size between ClientMessageand Property. The data, which is smaller than thissize, is sent via multi-CM (or only-CM), and thedata, which is lager than this size, is sent viaProperty.4.1.2. read/writeThe data is transferred via either ClientMessage or WindowProperty in the X Window System.4.1.2.1. Format for the data from the Client to the IMServerClientMessageIf data is sent via ClientMessage event, the format isas follows:Table 4-4; The ClientMessage event’s format (first or middle)Table 4-5; The ClientMessage event’s format (only or last)(1) If the data is smaller than 20 byte, all dataother than available data must be 0.PropertyIn the case of large data, data will be sent via theWindow Property for the efficiency. There are thefollowing two methods to notify Property, andtransport-version is decided which method is used.(1) The XChangeProperty function is used to store datain the client communication window, and Atom ofthe stored data is notified to the IM Server viaClientMessage event.(2) The XChangeProperty function is used to store datain the client communication window, and Atom ofthe stored data is notified to the IM Server viaPropertyNotify event.The arguments of the XChangeProperty are as follows:Table 4-6; The XChangeProperty event’s format(1) The read/write property ATOM allocates thefollowing strings by XInternAtom.‘‘_clientXXX’’The client changes the property with the mode ofPropModeAppend and the IM Server will read it with thedelete mode i.e. (delete = True).If Atom is notified via ClientMessage event, the formatof the ClientMessage is as follows:Table 4-7; The ClientMessage event’s format to sendAtom of property4.1.2.2. Format for the data from the IM Server to theClientClientMessageThe format of the ClientMessage is as follows:Table 4-8; The ClientMessage event’s format (first or middle)Table 4-9; The ClientMessage event’s format (only or last)(1) If the data size is smaller than 20 bytes, alldata other than available data must be 0.PropertyIn the case of large data, data will be sent via theWindow Property for the efficiency. There are thefollowing two methods to notify Property, andtransport-version is decided which method is used.(1) The XChangeProperty function is used to store datain the IMS communication window, and Atom of theproperty is sent via the ClientMessage event.(2) The XChangeProperty function is used to store datain the IMS communication window, and Atom of theproperty is sent via PropertyNotify event.The arguments of the XChangeProperty are as follows:Table 4-10; The XChangeProperty event’s format(1) The read/write property ATOM allocates somestrings, which are not allocated by the client, byXInternAtom.The IM Server changes the property with the mode ofPropModeAppend and the client reads it with the deletemode, i.e. (delete = True).If Atom is notified via ClientMessage event, the formatof the ClientMessage is as follows:Table 4-11; The ClientMessage event’s format to sendAtom of property4.1.3. Closing ConnectionIf the client disconnect with the IM Server, shutdownfunction should free the communication window properties andetc..5. References[1] Masahiko Narita and Hideki Hiura, ‘‘The Input MethodProtocol’’ 2