1147 lines
27 KiB
Plaintext
1147 lines
27 KiB
Plaintext
.\" $Xorg: Trans.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $
|
|
.\" $XdotOrg: xc/doc/specs/i18n/Trans.ms,v 1.2 2004/04/23 18:42:19 eich Exp $
|
|
.\" To print this out, type tbl macros.t This File | troff -ms
|
|
.EH ''''
|
|
.OH ''''
|
|
.EF ''''
|
|
.OF ''''
|
|
.ps 11
|
|
.nr PS 11
|
|
.\" .nr PD 1v
|
|
.\" .nr DD 1v
|
|
\&
|
|
.sp 8
|
|
.TL
|
|
\s+3\fBThe XIM Transport Specification\s-3\fP
|
|
.sp
|
|
.sp
|
|
\fBRevision 0.1\fP
|
|
.sp
|
|
\fBX Version 11, Release 6.8\fP
|
|
.sp 3
|
|
.AU
|
|
Takashi Fujiwara
|
|
.AI
|
|
FUJITSU LIMITED
|
|
.sp 3
|
|
.AB
|
|
.LP
|
|
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.
|
|
.AE
|
|
.ce 0
|
|
.br
|
|
.LP
|
|
.bp
|
|
\&
|
|
.ps 9
|
|
.nr PS 9
|
|
.sp 8
|
|
.LP
|
|
Copyright \(co 1994 by FUJITSU LIMITED
|
|
.LP
|
|
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.
|
|
.sp 5
|
|
Copyright \(co 1994 X Consortium
|
|
.LP
|
|
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:
|
|
.LP
|
|
The above copyright notice and this permission notice shall be included in
|
|
all copies or substantial portions of the Software.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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.
|
|
.sp 3
|
|
\fIX Window System\fP is a trademark of The Open Group.
|
|
.ps 11
|
|
.nr PS 11
|
|
.bp 1
|
|
.EH '\fBXIM Transport Specification\fP''\fBX11, Release 6.8\fP'
|
|
.OH '\fBXIM Transport Specification\fP''\fBX11, Release 6.8\fP'
|
|
.EF ''\fB % \fP''
|
|
.OF ''\fB % \fP''
|
|
.NH 1
|
|
Introduction
|
|
.XS
|
|
\*(SN Introduction
|
|
.XE
|
|
.LP
|
|
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 independent of transport implementation.
|
|
Each function of these layers are:
|
|
.RS 3
|
|
.IP "\fIThe protocol layer\fP"
|
|
.br
|
|
implements overall function of XIM and calls the interface layer
|
|
functions when it needs to communicate to IM Server.
|
|
.IP "\fIThe interface layer\fP"
|
|
.br
|
|
separates the implementation of the transport layer from the protocol
|
|
layer, in other words, it provides implementation independent hook for
|
|
the transport layer functions.
|
|
.IP "\fIThe transport layer\fP"
|
|
.br
|
|
handles actual data communication with IM Server. It is done by a set
|
|
of several functions named transporters.
|
|
.RE
|
|
.LP
|
|
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 section 4.
|
|
.NH 1
|
|
Initialization
|
|
.XS
|
|
\*(SN Initialization
|
|
.XE
|
|
.NH 2
|
|
Registering structure to initialize
|
|
.XS
|
|
\*(SN Registering structure to initialize
|
|
.XE
|
|
.LP
|
|
The structure typed as TransportSW contains the list of the transport
|
|
layer the specific implementations supports.
|
|
.LP
|
|
.Ds 0
|
|
.TA .5i 2.5i
|
|
.ta .5i 2.5i
|
|
typedef struct {
|
|
.br
|
|
char *transport_name;
|
|
.br
|
|
Bool (*config);
|
|
} TransportSW;
|
|
.De
|
|
.LP
|
|
.IP "\fItransport_name\fP" 15
|
|
name of transport(*1)
|
|
.FS
|
|
(*1) Refer to "The Input Method Protocol: Appendix B"
|
|
.FE
|
|
.IP "\fIconfig\fP" 15
|
|
initial configuration function
|
|
.LP
|
|
A sample entry for the Xlib supporting transporters is shown below:
|
|
.LP
|
|
.Ds 0
|
|
.TA .5i 2.5i
|
|
.ta .5i 2.5i
|
|
TransportSW _XimTransportRec[] = {
|
|
.sp 3p
|
|
/* char \fI*:
|
|
\ * transport_name\fP, Bool \fI(*config)()\fP
|
|
\ */
|
|
``X'', _XimXConf,
|
|
``tcp'', _XimTransConf,
|
|
``local'', _XimTransConf,
|
|
``decnet'', _XimTransConf,
|
|
``streams'', _XimTransConf,
|
|
(char *)NULL, (Bool (*)())NULL,
|
|
};
|
|
.De
|
|
.LP
|
|
.NH 2
|
|
Initialization function
|
|
.XS
|
|
\*(SN Initialization function
|
|
.XE
|
|
.LP
|
|
The following function will be called once when Xlib configures the
|
|
transporter functions.
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*config)(\fIim\fP, \fItransport_data\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
char \fI*transport_data\fP;
|
|
.br
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fItransport_data\fP 1i
|
|
Specifies the data specific to the transporter, in IM Server address. (*1)
|
|
.FS
|
|
(*1) Refer to "The Input Method Protocol: Appendix B"
|
|
.FE
|
|
.sp 6p
|
|
.LP
|
|
This function must setup the transporter function pointers.
|
|
.LP
|
|
The actual \fIconfig\fP function will be chosen by IM Server at the
|
|
pre-connection time, matching by the \fItransport_name\fP specified
|
|
in the \fB_XimTransportRec\fP array; The specific members of XimProto
|
|
structure listed below must be initialized so that point they
|
|
appropriate transporter functions.
|
|
.LP
|
|
If the specified transporter has been configured successfully, this
|
|
function returns True. There is no Alternative Entry for config
|
|
function itself.
|
|
.LP
|
|
The structure XimProto contains the following function pointers:
|
|
.DS
|
|
.TA .5i 2.5i
|
|
.ta .5i 2.5i
|
|
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 */
|
|
.DE
|
|
These functions are called when Xlib needs to communicate the
|
|
IM Server. These functions must process the appropriate procedure
|
|
described below.
|
|
.LP
|
|
.NH 1
|
|
The interface/transport layer functions
|
|
.XS
|
|
\*(SN The interface/transport layer functions
|
|
.XE
|
|
.LP
|
|
Following functions are used for the transport interface.
|
|
.LP
|
|
.ce
|
|
Table 3-1; The Transport Layer Functions.
|
|
.SM
|
|
.TS
|
|
tab(:) center box;
|
|
cw(4c) | cw(4c) | c
|
|
c | c | c
|
|
l | l | c.
|
|
.B
|
|
Alternative Entry:XimProto member:Section
|
|
(Interface Layer):(Transport Layer):\^
|
|
=
|
|
.R
|
|
\fB_XimConnect\fP:connect:3.1
|
|
_
|
|
\fB_XimShutdown\fP:shutdown:3.2
|
|
_
|
|
\fB_XimWrite\fP:write:3.3
|
|
_
|
|
\fB_XimRead\fP:read:3.4
|
|
_
|
|
\fB_XimFlush\fP:flush:3.5
|
|
_
|
|
\fB_XimRegisterDispatcher\fP:register_dispatcher:3.6
|
|
_
|
|
\fB_XimCallDispatcher\fP:call_dispatcher:3.7
|
|
.TE
|
|
.NL
|
|
.LP
|
|
The Protocol layer calls the above functions using the Alternative
|
|
Entry in the left column. The transport implementation defines
|
|
XimProto member function in the right column. The Alternative Entry is
|
|
provided so as to make easier to implement the Protocol Layer.
|
|
.LP
|
|
.NH 2
|
|
Opening connection
|
|
.XS
|
|
\*(SN Opening connection
|
|
.XE
|
|
.LP
|
|
When \fBXOpenIM\fP is called, the following function is called to connect
|
|
with the IM Server.
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*connect)(\fIim\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.sp 6p
|
|
.LP
|
|
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 function is:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool _XimConnect(\fIim\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.LP
|
|
.NH 2
|
|
Closing connection
|
|
.XS
|
|
\*(SN Closing connection
|
|
.XE
|
|
.LP
|
|
When \fBXCloseIM\fP is called, the following function is called to
|
|
disconnect the connection with the IM Server. The Alternative Entry
|
|
for this function is:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*shutdown)(\fIim\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.sp 6p
|
|
.LP
|
|
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:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool _XimShutdown(\fIim\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.FN
|
|
.IP \fIim\fP
|
|
Specifies XIM structure address.
|
|
.LP
|
|
.NH 2
|
|
Writing data
|
|
.XS
|
|
\*(SN Writing data
|
|
.XE
|
|
.LP
|
|
The following function is called, when Xlib needs to write data to the
|
|
IM Server.
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*write)(\fIim\fP, \fIlen\fP, \fIdata\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fIlen\fP;
|
|
.br
|
|
XPointer \fIdata\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIlen\fP 1i
|
|
Specifies the length of writing data.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the writing data.
|
|
.sp 6p
|
|
.LP
|
|
This function writes the \fIdata\fP to the IM Server, regardless
|
|
of the contents. The number of bytes is passed to \fIlen\fP. The
|
|
writing data is passed to \fIdata\fP. If data is sent successfully,
|
|
the function returns True. Refer to "The Input Method Protocol" for
|
|
the contents of the writing data. The Alternative Entry for this
|
|
function is:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool _XimWrite(\fIim\fP, \fIlen\fP, \fIdata\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fIlen\fP;
|
|
.br
|
|
XPointer \fIdata\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIlen\fP 1i
|
|
Specifies the length of writing data.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the writing data.
|
|
.LP
|
|
.NH 2
|
|
Reading data
|
|
.XS
|
|
\*(SN Reading data
|
|
.XE
|
|
.LP
|
|
The following function is called when Xlib waits for response from IM
|
|
server synchronously.
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*read)(\fIim\fP, \fIread_buf\fP, \fIbuf_len\fP, \fIret_len\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
XPointer \fIread_buf\fP;
|
|
.br
|
|
int \fIbuf_len\fP;
|
|
.br
|
|
int \fI*ret_len\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIread_buf\fP 1i
|
|
Specifies the buffer to store data.
|
|
.IP \fIbuf_len\fP 1i
|
|
Specifies the size of the \fIbuffer\fP
|
|
.IP \fIret_len\fP
|
|
Specifies the length of stored data.
|
|
.sp 6p
|
|
.LP
|
|
This function stores the read data in \fIread_buf\fP, which size is
|
|
specified as \fIbuf_len\fP. The size of data is set to \fIret_len\fP.
|
|
This function return True, if the data is read normally or reading
|
|
data is completed.
|
|
.LP
|
|
The Alternative Entry for this function is:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool _XimRead(\fIim\fP, \fIret_len\fP, \fIbuf\fP, \fIbuf_len\fP, \fIpredicate\fP, \fIpredicate_arg\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fI*ret_len\fP;
|
|
.br
|
|
XPointer \fIbuf\fP;
|
|
.br
|
|
int \fIbuf_len\fP;
|
|
.br
|
|
Bool \fI(*predicate)()\fP;
|
|
.br
|
|
XPointer \fIpredicate_arg\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIret_len\fP 1i
|
|
Specifies the size of the \fIdata\fP buffer.
|
|
.IP \fIbuf\fP 1i
|
|
Specifies the buffer to store data.
|
|
.IP \fIbuf_len\fP 1i
|
|
Specifies the length of \fIbuffer\fP.
|
|
.IP \fIpredicate\fP 1i
|
|
Specifies the predicate for the XIM data.
|
|
.IP \fIpredicate_arg\fP 1i
|
|
Specifies the predicate specific data.
|
|
.sp 6p
|
|
.LP
|
|
The predicate procedure indicates whether the \fIdata\fP is for the
|
|
XIM or not. \fIlen\fP
|
|
This function stores the read data in \fIbuf\fP, which size is specified
|
|
as \fIbuf_len\fP. The size of data is set to \fIret_len\fP.
|
|
If \fIpreedicate()\fP returns True, this function returns True.
|
|
If not, it calls the registered callback function.
|
|
.LP
|
|
The procedure and its arguments are:
|
|
.LP
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*predicate)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIpredicate_arg\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fIlen\fP;
|
|
.br
|
|
XPointer \fIdata\fP;
|
|
.br
|
|
XPointer \fIpredicate_arg\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIlen\fP 1i
|
|
Specifies the size of the \fIdata\fP buffer.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the buffer to store data.
|
|
.IP \fIpredicate_arg\fP 1i
|
|
Specifies the predicate specific data.
|
|
.LP
|
|
.NH 2
|
|
Flushing buffer
|
|
.XS
|
|
\*(SN Flushing buffer
|
|
.XE
|
|
.LP
|
|
The following function is called when Xlib needs to flush the data.
|
|
.sp 6p
|
|
.FD 0
|
|
void (*flush)(\fIim\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.sp 6p
|
|
.LP
|
|
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 function is:
|
|
.sp 6p
|
|
.FD 0
|
|
void _XimFlush(\fIim\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.LP
|
|
.NH 2
|
|
Registering asynchronous data handler
|
|
.XS
|
|
\*(SN Registering asynchronous data handler
|
|
.XE
|
|
.LP
|
|
Xlib needs to handle asynchronous response from IM Server. This is
|
|
because some of the XIM data occur asynchronously to X events.
|
|
.LP
|
|
Those data will be handled in the \fIFilter\fP, and the \fIFilter\fP
|
|
will call asynchronous data handler in the protocol layer. Then it
|
|
calls dispatchers in the transport layer. The dispatchers are
|
|
implemented by the protocol layer. This function must store the
|
|
information and prepare for later call of the dispatchers using
|
|
\fB_XimCallDispatcher\fP.
|
|
.LP
|
|
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:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*register_dispatcher)(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
Bool \fI(*dispatcher)()\fP;
|
|
.br
|
|
XPointer \fIcall_data\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIdispatcher\fP 1i
|
|
Specifies the dispatcher function to register.
|
|
.IP \fIcall_data\fP 1i
|
|
Specifies a parameter for the \fIdispatcher\fP.
|
|
.LP
|
|
The dispatcher is a function of the following type:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIcall_data\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fIlen\fP;
|
|
.br
|
|
XPointer \fIdata\fP;
|
|
.br
|
|
XPointer \fIcall_data\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIlen\fP 1i
|
|
Specifies the size of the \fIdata\fP buffer.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the buffer to store data.
|
|
.IP \fIcall_data\fP 1i
|
|
Specifies a parameter passed to the register_dispatcher.
|
|
.sp 6p
|
|
.LP
|
|
The dispatcher is provided by the protocol layer. They are called once
|
|
for every asynchronous data, in order of registration. If the data is
|
|
used, it must return True. otherwise, it must return False.
|
|
.LP
|
|
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:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool _XimRegisterDispatcher(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
Bool \fI(*dispatcher)()\fP;
|
|
.br
|
|
XPointer \fIcall_data\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIdispatcher\fP 1i
|
|
Specifies the dispatcher function to register.
|
|
.IP \fIcall_data\fP 1i
|
|
Specifies a parameter for the \fIdispatcher\fP.
|
|
.LP
|
|
.NH 2
|
|
Calling dispatcher
|
|
.XS
|
|
\*(SN Calling dispatcher
|
|
.XE
|
|
.LP
|
|
The following function is used to call the registered dispatcher
|
|
function, when the asynchronous response from IM Server has arrived.
|
|
.sp 6p
|
|
.FD 0
|
|
Bool (*call_dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fIlen\fP;
|
|
.br
|
|
XPointer \fIdata\fP;
|
|
.FN
|
|
.IP \fIim\fP 1i
|
|
Specifies XIM structure address.
|
|
.IP \fIlen\fP 1i
|
|
Specifies the size of \fIdata\fP buffer.
|
|
.IP \fIdata\fP 1i
|
|
Specifies the buffer to store data.
|
|
.LP
|
|
The call_dispatcher must call the dispatcher function, in order of
|
|
their registration. \fIlen\fP and \fIdata\fP are the data passed to
|
|
register_dispatcher.
|
|
.LP
|
|
The return values are checked at each invocation, and if it finds
|
|
True, it immediately return with true for its return value.
|
|
.LP
|
|
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:
|
|
.sp 6p
|
|
.FD 0
|
|
Bool _XimCallDispatcher(\fIim\fP, \fIlen\fP, \fIdata\fP)
|
|
.br
|
|
XIM \fIim\fP;
|
|
.br
|
|
INT16 \fIlen\fP;
|
|
.br
|
|
XPointer \fIcall_data\fP;
|
|
.FN
|
|
.LP
|
|
.bp
|
|
.NH 1
|
|
Sample implementations for the Transport Layer
|
|
.XS
|
|
\*(SN Sample implementations for the Transport Layer
|
|
.XE
|
|
.LP
|
|
Sample implementations for the transporter using the X connection is
|
|
described here.
|
|
.LP
|
|
.NH 2
|
|
X Transport
|
|
.XS
|
|
\*(SN X Transport
|
|
.XE
|
|
.LP
|
|
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 following, 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 communication window".
|
|
.LP
|
|
.NH 3
|
|
Connection
|
|
.XS
|
|
\*(SN X Connection
|
|
.XE
|
|
.LP
|
|
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.
|
|
.LP
|
|
Refer to "The Input Method Protocol" for the XIM_SERVER atom.
|
|
.LP
|
|
.ce
|
|
Table 4-1; The ClientMessage sent to the IMS window.
|
|
.TS H
|
|
tab(:);
|
|
l s|l
|
|
l l|l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member:Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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)
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
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.
|
|
.LP
|
|
.ce
|
|
Table 4-2; The ClientMessage sent by IM Server.
|
|
.TS H
|
|
tab(:);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member:Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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)
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.IP (*1)
|
|
major/minor-transport-version
|
|
.RS
|
|
The read/write method is decided by the combination of
|
|
major/minor-transport-version, as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-3; The read/write method and the major/minor-transport-version
|
|
.TS
|
|
center, tab(:);
|
|
| c s | l |
|
|
| c | c | l |.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Transport-version:read/write
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
major:minor:
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.R
|
|
0:0:only-CM & Property-with-CM
|
|
:1:only-CM & multi-CM
|
|
:2:only-CM & multi-CM & Property-with-CM
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
1:0:PropertyNotify
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
2:0:only-CM & PropertyNotify
|
|
:1:only-CM & multi-CM & PropertyNotify
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.RS
|
|
.TS
|
|
center, tab(;);
|
|
l n l.
|
|
only-CM;:;data is sent via a ClientMessage
|
|
multi-CM;:;data is sent via multiple ClientMessages
|
|
Property-with-CM;:;T{
|
|
data is written in Property, and its Atom is send via ClientMessage
|
|
T}
|
|
PropertyNotify;:;T{
|
|
data is written in Property, and its Atom is send via PropertyNotify
|
|
T}
|
|
.TE
|
|
.RE
|
|
.LP
|
|
The method to decide major/minor-transport-version is as follows:
|
|
.LP
|
|
.IP (1)
|
|
The client sends 0 as major/minor-transport-version 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.
|
|
.IP (2)
|
|
The IM Server sends its major/minor-transport-version number to
|
|
the client. The client sends data using the method specified by the
|
|
IM Server.
|
|
.IP (3)
|
|
If major/minor-transport-version number is not available, it is regarded
|
|
as 0.
|
|
.RE
|
|
.LP
|
|
.IP (*2)
|
|
dividing size between ClientMessage and Property
|
|
.RS
|
|
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.
|
|
.RE
|
|
.LP
|
|
.NH 3
|
|
read/write
|
|
.XS
|
|
\*(SN read/write
|
|
.XE
|
|
.LP
|
|
The data is transferred via either ClientMessage or Window Property in
|
|
the X Window System.
|
|
.LP
|
|
.NH 4
|
|
Format for the data from the Client to the IM Server
|
|
.XS
|
|
\*(SN Format for the data from the Client to the IM Server
|
|
.XE
|
|
.LP
|
|
.B
|
|
ClientMessage
|
|
.LP
|
|
.RS
|
|
If data is sent via ClientMessage event, the format is as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-4; The ClientMessage event's format (first or middle)
|
|
.TS H
|
|
tab(;);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member;Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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)
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.ce
|
|
Table 4-5; The ClientMessage event's format (only or last)
|
|
.TS H
|
|
tab(;);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member;Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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)
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.IP (*1)
|
|
If the data is smaller than 20 byte, all data other than available data
|
|
must be 0.
|
|
.RE
|
|
.LP
|
|
.B
|
|
Property
|
|
.LP
|
|
.RS
|
|
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.
|
|
.LP
|
|
.IP (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.
|
|
.IP (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.
|
|
.LP
|
|
The arguments of the XChangeProperty are as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-6; The XChangeProperty event's format
|
|
.TS H
|
|
tab(:);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Argument:Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.IP (*1)
|
|
The read/write property ATOM allocates the following strings by
|
|
\fBXInternAtom\fP.
|
|
.RS
|
|
``_clientXXX''
|
|
.RE
|
|
.LP
|
|
The client changes the property with the mode of PropModeAppend and
|
|
the IM Server will read it with the delete mode i.e. (delete = True).
|
|
.LP
|
|
If Atom is notified via ClientMessage event, the format of the ClientMessage
|
|
is as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-7; The ClientMessage event's format to send Atom of property
|
|
.TS H
|
|
tab(:);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member:Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.RE
|
|
.LP
|
|
.NH 4
|
|
Format for the data from the IM Server to the Client
|
|
.XS
|
|
\*(SN Format for the data from the Client to the Client
|
|
.XE
|
|
.LP
|
|
.B
|
|
ClientMessage
|
|
.LP
|
|
.RS
|
|
The format of the ClientMessage is as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-8; The ClientMessage event's format (first or middle)
|
|
.TS H
|
|
tab(;);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member;Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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)
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.ce
|
|
Table 4-9; The ClientMessage event's format (only or last)
|
|
.TS H
|
|
tab(;);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member;Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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)
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.IP (*1)
|
|
If the data size is smaller than 20 bytes, all data other than available
|
|
data must be 0.
|
|
.RE
|
|
.LP
|
|
.B
|
|
Property
|
|
.LP
|
|
.RS
|
|
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.
|
|
.LP
|
|
.IP (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.
|
|
.IP (2)
|
|
The XChangeProperty function is used to store data in the IMS
|
|
communication window, and Atom of the property is sent via
|
|
PropertyNotify event.
|
|
.LP
|
|
The arguments of the XChangeProperty are as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-10; The XChangeProperty event's format
|
|
.TS H
|
|
tab(:);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Argument:Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.LP
|
|
.IP (*1)
|
|
The read/write property ATOM allocates some strings, which are not
|
|
allocated by the client, by \fBXInternAtom\fP.
|
|
.LP
|
|
The IM Server changes the property with the mode of PropModeAppend and
|
|
the client reads it with the delete mode, i.e. (delete = True).
|
|
.LP
|
|
If Atom is notified via ClientMessage event, the format of the ClientMessage
|
|
is as follows:
|
|
.LP
|
|
.ce
|
|
Table 4-11; The ClientMessage event's format to send Atom of property
|
|
.TS H
|
|
tab(:);
|
|
l s | l
|
|
l l | l.
|
|
_
|
|
.sp 6p
|
|
.B
|
|
Structure Member:Contents
|
|
.sp 6p
|
|
_
|
|
.sp 6p
|
|
.TH
|
|
.R
|
|
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
|
|
.sp 6p
|
|
_
|
|
.TE
|
|
.RE
|
|
.LP
|
|
.NH 3
|
|
Closing Connection
|
|
.XS
|
|
\*(SN Closing Connection
|
|
.XE
|
|
.LP
|
|
If the client disconnect with the IM Server, shutdown function should
|
|
free the communication window properties and etc..
|
|
.LP
|
|
.NH 1
|
|
References
|
|
.XS
|
|
\*(SN References
|
|
.XE
|
|
.LP
|
|
[1] Masahiko Narita and Hideki Hiura, \fI``The Input Method Protocol''\fP
|
|
.LP
|
|
|