diff options
Diffstat (limited to 'libX11')
| -rw-r--r-- | libX11/specs/i18n/localedb/localedb.xml | 1554 | ||||
| -rw-r--r-- | libX11/specs/i18n/trans/trans.xml | 3958 |
2 files changed, 2756 insertions, 2756 deletions
diff --git a/libX11/specs/i18n/localedb/localedb.xml b/libX11/specs/i18n/localedb/localedb.xml index e5b96ab84..c4f6d1377 100644 --- a/libX11/specs/i18n/localedb/localedb.xml +++ b/libX11/specs/i18n/localedb/localedb.xml @@ -1,777 +1,777 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-
-<book id="localedbspec">
-
-<bookinfo>
- <title>X Locale Database Specification</title>
- <authorgroup>
- <author>
- <firstname>Yoshio</firstname><surname>Horiuchi</surname>
- <affiliation><orgname>IBM Japan</orgname></affiliation>
- </author>
- </authorgroup>
- <copyright><year>1994</year><holder>IBM Corporation</holder></copyright>
- <copyright><year>1994</year><holder>X Consortium</holder></copyright>
-
-
-<legalnotice>
-
-<para>
-License to use, copy, modify, and distribute this software and its documentation for
-any purpose and without fee is hereby granted, provided that the above copyright notice
-appear in all copies and that both that copyright notice and this permission notice
-appear in supporting documentation, and that the name of IBM not be used in advertising
-or publicity pertaining to distribution of the software without specific, written
-prior permission.
-</para>
-<para>
-IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED
-WARRANTIES OF MERCHANTABILITY, FITNESS, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS,
-IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES
-OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
-AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
-WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-</para>
-
-<para>
-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:
-</para>
-
-<para>
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-</para>
-
-<para>
-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.
-</para>
-
-<para>
-Except as contained in this notice, the name of The Open Group shall not
-be used in advertising or otherwise to promote the sale, use or other dealings
-in this Software without prior written authorization from X Consortium.
-</para>
-
-<para>X Window System is a trademark of The Open Group.</para>
-
-</legalnotice>
-</bookinfo>
-
-<chapter id="localedb">
-<title>LocaleDB</title>
-
-<sect1 id="General">
-<title>General</title>
-<para>
-An X Locale Database contains the subset of a user's environment that
-depends on language, in X Window System. It is made up from one or more
-categories. Each category consists of some classes and sub-classes.
-</para>
-
-<para>
-It is provided as a plain ASCII text file, so a user can change its
-contents easily. It allows a user to customize the behavior of
-internationalized portion of Xlib without changing Xlib itself.
-</para>
-
-<para>
-This document describes;
-</para>
-
-<itemizedlist>
- <listitem>
- <para>
-Database Format Definition
- </para>
- </listitem>
- <listitem>
- <para>
-Contents of Database in sample implementation
-<!-- .RE -->
- </para>
- </listitem>
-</itemizedlist>
-
-<para>
-Since it is hard to define the set of required information for all
-platforms, only the flexible database format is defined.
-The available entries in database are implementation dependent.
-</para>
-
-</sect1>
-<sect1 id="Database_Format_Definition">
-<title>Database Format Definition</title>
-<para>
-The X Locale Database contains one or more category definitions.
-This section describes the format of each category definition.
-</para>
-
-<para>
-The category definition consists of one or more class definitions.
-Each class definition has a pair of class name and class value, or
-has several subclasses which are enclosed by the left brace ({) and
-the right brace (}).
-</para>
-
-<para>
-Comments can be placed by using the number sign character (#).
-Putting the number sign character on the top of the line indicates
-that the entire line is comment. Also, putting any whitespace character
-followed by the number sign character indicates that a part of the line
-(from the number sign to the end of the line) is comment.
-A line can be continued by placing backslash (\) character as the
-last character on the line; this continuation character will be
-discarded from the input. Comment lines cannot be continued on
-a subsequent line using an escaped new line character.
-</para>
-
-<para>
-X Locale Database only accepts XPCS, the X Portable Character Set.
-The reserved symbols are; the quotation mark("), the number sign (#),
-the semicolon(;), the backslash(\), the left brace({) and
-the right brace(}).
-</para>
-
-<para>
-The format of category definition is;
-</para>
-
-<informaltable frame="none">
- <tgroup cols='3' align='left'>
- <colspec colname='c1' colwidth="3*" colsep="0"/>
- <colspec colname='c2' colwidth="1*" colsep="0"/>
- <colspec colname='c3' colwidth="6*" colsep="0"/>
- <tbody>
- <row rowsep="0">
- <entry>CategoryDefinition</entry>
- <entry>::=</entry>
- <entry>CategoryHeader CategorySpec CategoryTrailer</entry>
- </row>
- <row rowsep="0">
- <entry>CategoryHeader</entry>
- <entry>::=</entry>
- <entry>CategoryName NL</entry>
- </row>
- <row rowsep="0">
- <entry>CategorySpec</entry>
- <entry>::=</entry>
- <entry>{ ClassSpec }</entry>
- </row>
- <row rowsep="0">
- <entry>CategoryTrailer</entry>
- <entry>::=</entry>
- <entry>"END" Delimiter CategoryName NL</entry>
- </row>
- <row rowsep="0">
- <entry>CategoryName</entry>
- <entry>::=</entry>
- <entry>String</entry>
- </row>
- <row rowsep="0">
- <entry>ClassSpec</entry>
- <entry>::=</entry>
- <entry>ClassName Delimiter ClassValue NL</entry>
- </row>
- <row rowsep="0">
- <entry>ClassName</entry>
- <entry>::=</entry>
- <entry>String</entry>
- </row>
- <row rowsep="0">
- <entry>ClassValue</entry>
- <entry>::=</entry>
- <entry>ValueList | "{" NL { ClassSpec } "}"</entry>
- </row>
- <row rowsep="0">
- <entry>ValueList</entry>
- <entry>::=</entry>
- <entry>Value | Value ";" ValueList</entry>
- </row>
- <row rowsep="0">
- <entry>Value</entry>
- <entry>::=</entry>
- <entry>ValuePiece | ValuePiece Value</entry>
- </row>
- <row rowsep="0">
- <entry>ValuePiece</entry>
- <entry>::=</entry>
- <entry>String | QuotedString | NumericString</entry>
- </row>
- <row rowsep="0">
- <entry>String</entry>
- <entry>::=</entry>
- <entry>Char { Char }</entry>
- </row>
- <row rowsep="0">
- <entry>QuotedString</entry>
- <entry>::=</entry>
- <entry>""" QuotedChar { QuotedChar } """</entry>
- </row>
- <row rowsep="0">
- <entry>NumericString</entry>
- <entry>::=</entry>
- <entry>"\\o" OctDigit { OctDigit }</entry>
- </row>
- <row rowsep="0">
- <entry></entry>
- <entry>|</entry>
- <entry>"\\d" DecDigit { DecDigit }</entry>
- </row>
- <row rowsep="0">
- <entry></entry>
- <entry>|</entry>
- <entry>"\\x" HexDigit { HexDigit }</entry>
- </row>
- <row rowsep="0">
- <entry>Char</entry>
- <entry>::=</entry>
- <entry><XPCS except NL, Space or unescaped reserved symbols></entry>
- </row>
- <row rowsep="0">
- <entry>QuotedChar</entry>
- <entry>::=</entry>
- <entry><XPCS except unescaped """></entry>
- </row>
- <row rowsep="0">
- <entry>OctDigit</entry>
- <entry>::=</entry>
- <entry><character in the range of "0" - "7"></entry>
- </row>
- <row rowsep="0">
- <entry>DecDigit</entry>
- <entry>::=</entry>
- <entry><character in the range of "0" - "9"></entry>
- </row>
- <row rowsep="0">
- <entry>HexDigit</entry>
- <entry>::=</entry>
- <entry><character in the range of "0" - "9", "a" - "f", "A" - "F"></entry>
- </row>
- <row rowsep="0">
- <entry>Delimiter</entry>
- <entry>::=</entry>
- <entry>Space { Space }</entry>
- </row>
- <row rowsep="0">
- <entry>Space</entry>
- <entry>::=</entry>
- <entry><space> | <horizontal tab></entry>
- </row>
- <row rowsep="0">
- <entry>NL</entry>
- <entry>::=</entry>
- <entry><newline></entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-Elements separated by vertical bar (|) are alternatives. Curly
-braces ({...}) indicate zero or more repetitions of the enclosed
-elements. Square brackets ([...]) indicate that the enclosed element
-is optional. Quotes ("...") are used around literal characters.
-</para>
-
-<para>
-The backslash, which is not the top character of the NumericString, is
-recognized as an escape character, so that the next one character is
-treated as a literal character. For example, the two-character
-sequence, ""\"""(the backslash followed by the quotation mark) is
-recognized and replaced with a quotation mark character.
-Any whitespace character, that is not the Delimiter, unquoted and
-unescaped, is ignored.
-</para>
-
-</sect1>
-<sect1 id="Contents_of_Database_">
-<title>Contents of Database </title>
-<para>
-The available categories and classes depend on implementation, because
-different platform will require different information set.
-For example, some platform have system locale but some platform don't.
-Furthermore, there might be a difference in functionality even if the
-platform has system locale.
-</para>
-
-<para>
-In current sample implementation, categories listed below are available.
-</para>
-
-<informaltable frame="none">
- <tgroup cols='3' align='left'>
- <colspec colname='c1' colwidth="2*" colsep="0"/>
- <colspec colname='c2' colwidth="1*" colsep="0"/>
- <tbody>
- <row rowsep="0">
- <entry>XLC_FONTSET:XFontSet relative information</entry>
- </row>
- <row rowsep="0">
- <entry>XLC_XLOCALE:Character classification and conversion information</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-</sect1>
-<sect1 id="XLC_FONTSET_Category">
-<title>XLC_FONTSET Category</title>
-<para>
-The XLC_FONTSET category defines the XFontSet relative information.
-It contains the CHARSET_REGISTRY-CHARSET_ENCODING name and character
-mapping side (GL, GR, etc), and is used in Output Method (OM).
-</para>
-
-<informaltable frame="none">
- <tgroup cols='3' align='left'>
- <thead>
- <colspec colname='c1' colwidth="3*" colsep="0"/>
- <colspec colname='c2' colwidth="1*" colsep="0"/>
- <colspec colname='c3' colwidth="3*" colsep="0"/>
- <row>
- <entry>class</entry>
- <entry>super class</entry>
- <entry>description</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>fsN</entry>
- <entry></entry>
- <entry>Nth fontset (N=0,1,2, ...)</entry>
- </row>
- <row rowsep="0">
- <entry>charset</entry>
- <entry>fsN</entry>
- <entry>list of encoding name</entry>
- </row>
- <row rowsep="0">
- <entry>font</entry>
- <entry>fsN</entry>
- <entry>list of font encoding name</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<variablelist>
- <varlistentry>
- <term>fsN</term>
- <listitem>
- <para>
-Includes an encoding information for Nth charset, where N is
-the index number (0,1,2,...). If there are 4 charsets available
-in current locale, 4 fontsets, fs0, fs1, fs2 and fs3, should be
-defined.
-This class has two subclasses, 'charset' and 'font'.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>charset</term>
- <listitem>
- <para>
-Specifies an encoding information to be used internally in Xlib
-for this fontset. The format of value is;
- </para>
-<informaltable frame="none">
- <tgroup cols='3' align='left'>
- <colspec colname='c1' colwidth="3*" colsep="0"/>
- <colspec colname='c2' colwidth="1*" colsep="0"/>
- <colspec colname='c3' colwidth="4*" colsep="0"/>
- <tbody>
- <row rowsep="0">
- <entry>EncodingInfo</entry>
- <entry>::=</entry>
- <entry>EncodingName [ ":" EncodingSide ]</entry>
- </row>
- <row rowsep="0">
- <entry>EncodingName</entry>
- <entry>::=</entry>
- <entry>CHARSET_REGISTRY-CHARSET_ENCODING</entry>
- </row>
- <row rowsep="0">
- <entry>EncodingSide</entry>
- <entry>::=</entry>
- <entry>"GL" | "GR"</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer
-"X Logical Font Descriptions" document.
-</para>
-<literallayout>
-example:
- ISO8859-1:GL
-</literallayout>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>font</term>
- <listitem>
- <para>
-Specifies a list of encoding information which is used for searching
-appropriate font for this fontset. The left most entry has highest
-priority.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</sect1>
-<sect1 id="XLC_XLOCALE_Category">
-<title>XLC_XLOCALE Category</title>
-<para>
-The XLC_XLOCALE category defines character classification, conversion
-and other character attributes.
-</para>
-
-<informaltable frame="none">
- <tgroup cols='3' align='left'>
- <colspec colname='c1' colwidth="3*" colsep="0"/>
- <colspec colname='c2' colwidth="1*" colsep="0"/>
- <colspec colname='c3' colwidth="3*" colsep="0"/>
- <thead>
- <row>
- <entry>class</entry>
- <entry>super class</entry>
- <entry>description</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>encoding_name</entry>
- <entry></entry>
- <entry>codeset name</entry>
- </row>
- <row rowsep="0">
- <entry>mb_cur_max</entry>
- <entry></entry>
- <entry>MB_CUR_MAX</entry>
- </row>
- <row rowsep="0">
- <entry>state_depend_encoding</entry>
- <entry></entry>
- <entry>state dependent or not</entry>
- </row>
- <row rowsep="0">
- <entry>wc_encoding_mask</entry>
- <entry></entry>
- <entry>for parsing wc string</entry>
- </row>
- <row rowsep="0">
- <entry>wc_shift_bits</entry>
- <entry></entry>
- <entry>for conversion between wc and mb</entry>
- </row>
- <row rowsep="0">
- <entry>csN</entry>
- <entry></entry>
- <entry>Nth charset (N=0,1,2,...)</entry>
- </row>
- <row rowsep="0">
- <entry>side</entry>
- <entry>csN</entry>
- <entry>mapping side (GL, etc)</entry>
- </row>
- <row rowsep="0">
- <entry>length</entry>
- <entry>csN</entry>
- <entry>length of a character</entry>
- </row>
- <row rowsep="0">
- <entry>mb_encoding</entry>
- <entry>csN</entry>
- <entry>for parsing mb string</entry>
- </row>
- <row rowsep="0">
- <entry>wc_encoding</entry>
- <entry>csN</entry>
- <entry>for parsing wc string</entry>
- </row>
- <row rowsep="0">
- <entry>ct_encoding</entry>
- <entry>csN</entry>
- <entry>list of encoding name for ct</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<variablelist>
- <varlistentry>
- <term>encoding_name</term>
- <listitem>
- <para>
-Specifies a codeset name of current locale.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>mb_cur_max</term>
- <listitem>
- <para>
-Specifies a maximum allowable number of bytes in a multi-byte character.
-It is corresponding to MB_CUR_MAX of "ISO/IEC 9899:1990 C Language Standard".
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>state_depend_encoding</term>
- <listitem>
- <para>
-Indicates a current locale is state dependent. The value should be
-specified "True" or "False".
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>wc_encoding_mask</term>
- <listitem>
- <para>
-Specifies a bit-mask for parsing wide-char string. Each wide character is
-applied bit-and operation with this bit-mask, then is classified into
-the unique charset, by using 'wc_encoding'.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>wc_shift_bits</term>
- <listitem>
- <para>
-Specifies a number of bit to be shifted for converting from a multi-byte
-character to a wide character, and vice-versa.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>csN</term>
- <listitem>
- <para>
-<!-- .br -->
-Includes a character set information for Nth charset, where N is the
-index number (0,1,2,...). If there are 4 charsets available in current
-locale, cs0, cs1, cs2 and cs3 should be defined. This class has five
-subclasses, 'side', 'length', 'mb_encoding' 'wc_encoding' and 'ct_encoding'.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>side</term>
- <listitem>
- <para>
-Specifies a mapping side of this charset. The format of this value is;
- </para>
- <literallayout>
- Side ::= EncodingSide[":Default"]
- </literallayout>
- <para>
-The suffix ":Default" can be specified. It indicates that a character
-belongs to the specified side is mapped to this charset in initial state.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>length</term>
- <listitem>
- <para>
-<!-- .br -->
-Specifies a number of bytes of a multi-byte character of this charset.
-It should not contain the length of any single-shift sequence.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>mb_encoding</term>
- <listitem>
- <para>
-Specifies a list of shift sequence for parsing multi-byte string.
-The format of this value is;
- </para>
-<informaltable frame="none">
- <tgroup cols='3' align='left'>
- <colspec colname='c1' colwidth="3*" colsep="0"/>
- <colspec colname='c2' colwidth="1*" colsep="0"/>
- <colspec colname='c3' colwidth="5*" colsep="0"/>
- <tbody>
- <row rowsep="0">
- <entry>MBEncoding</entry>
- <entry>::=</entry>
- <entry>ShiftType ShiftSequence</entry>
- </row>
- <row rowsep="0">
- <entry></entry>
- <entry>|</entry>
- <entry>ShiftType ShiftSequence ";" MBEncoding</entry>
- </row>
- <row rowsep="0">
- <entry>ShiftType</entry>
- <entry>::=</entry>
- <entry>"<SS>"|"<LSL>"|"<LSR>"</entry>
- </row>
- <row rowsep="0">
- <entry>ShiftSequence</entry>
- <entry>::=</entry>
- <entry>SequenceValue|SequenceValue ShiftSequence</entry>
- </row>
- <row rowsep="0">
- <entry>SequenceValue</entry>
- <entry>::=</entry>
- <entry>NumericString</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
- <literallayout>
-example:
- <LSL> \x1b \x28 \x4a; <LSL> \x1b \x28 \x42
- </literallayout>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>wc_encoding</term>
- <listitem>
- <para>
-Specifies an integer value for parsing wide-char string.
-It is used to determine the charset for each wide character, after
-applying bit-and operation using 'wc_encoding_mask'.
-This value should be unique in all csN classes.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ct_encoding</term>
- <listitem>
- <para>
-Specifies a list of encoding information that can be used for Compound
-Text.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect1>
-
-<sect1 id="Sample_of_X_Locale_Database">
-<title>Sample of X Locale Database</title>
-<para>
-The following is sample X Locale Database file.
-</para>
-
-<literallayout class="monospaced">
-# XLocale Database Sample for ja_JP.euc
-#
-
-#
-# XLC_FONTSET category
-#
-XLC_FONTSET
-# fs0 class (7 bit ASCII)
-fs0 {
- charset ISO8859-1:GL
- font ISO8859-1:GL; JISX0201.1976-0:GL
-}
-# fs1 class (Kanji)
-fs1 {
- charset JISX0208.1983-0:GL
- font JISX0208.1983-0:GL
-}
-# fs2 class (Half Kana)
-fs2 {
- charset JISX0201.1976-0:GR
- font JISX0201.1976-0:GR
-}
-# fs3 class (User Defined Character)
-# fs3 {
-# charset JISX0212.1990-0:GL
-# font JISX0212.1990-0:GL
-# }
-END XLC_FONTSET
-
-#
-# XLC_XLOCALE category
-#
-XLC_XLOCALE
-
-encoding_name ja.euc
-mb_cur_max 3
-state_depend_encoding False
-
-wc_encoding_mask \x00008080
-wc_shift_bits 8
-
-# cs0 class
-cs0 {
- side GL:Default
- length 1
- wc_encoding \x00000000
- ct_encoding ISO8859-1:GL; JISX0201.1976-0:GL
-}
-# cs1 class
-cs1 {
- side GR:Default
- length 2
-
- wc_encoding \x00008080
-
- ct_encoding JISX0208.1983-0:GL; JISX0208.1983-0:GR;\
- JISX0208.1983-1:GL; JISX0208.1983-1:GR
-}
-
-# cs2 class
-cs2 {
- side GR
- length 1
- mb_encoding <SS> \x8e
-
- wc_encoding \x00000080
-
- ct_encoding JISX0201.1976-0:GR
-}
-
-# cs3 class
-# cs3 {
-# side GL
-# length 2
-# mb_encoding <SS> \x8f
-# #if HasWChar32
-# wc_encoding \x20000000
-# #else
-# wc_encoding \x00008000
-# #endif
-# ct_encoding JISX0212.1990-0:GL; JISX0212.1990-0:GR
-# }
-
-END XLC_XLOCALE
-</literallayout>
-</sect1>
-
-<sect1 id="Reference">
-<title>Reference</title>
-<para>
-[1] <emphasis remap='I'>ISO/IEC 9899:1990 C Language Standard</emphasis>
-</para>
-<para>
-[2] <emphasis remap='I'>X Logical Font Descriptions</emphasis>
-</para>
-
-</sect1>
-</chapter>
-</book>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<book id="localedb"> + +<bookinfo> + <title>X Locale Database Specification</title> + <authorgroup> + <author> + <firstname>Yoshio</firstname><surname>Horiuchi</surname> + <affiliation><orgname>IBM Japan</orgname></affiliation> + </author> + </authorgroup> + <copyright><year>1994</year><holder>IBM Corporation</holder></copyright> + <copyright><year>1994</year><holder>X Consortium</holder></copyright> + + +<legalnotice> + +<para> +License to use, copy, modify, and distribute this software and its documentation for +any purpose and without fee is hereby granted, provided that the above copyright notice +appear in all copies and that both that copyright notice and this permission notice +appear in supporting documentation, and that the name of IBM not be used in advertising +or publicity pertaining to distribution of the software without specific, written +prior permission. +</para> +<para> +IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED +WARRANTIES OF MERCHANTABILITY, FITNESS, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS, +IN NO EVENT SHALL IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES +OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN +AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +</para> + +<para> +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: +</para> + +<para> +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. +</para> + +<para> +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. +</para> + +<para> +Except as contained in this notice, the name of The Open Group shall not +be used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from X Consortium. +</para> + +<para>X Window System is a trademark of The Open Group.</para> + +</legalnotice> +</bookinfo> + +<chapter id="localeDatabase"> +<title>LocaleDB</title> + +<sect1 id="General"> +<title>General</title> +<para> +An X Locale Database contains the subset of a user's environment that +depends on language, in X Window System. It is made up from one or more +categories. Each category consists of some classes and sub-classes. +</para> + +<para> +It is provided as a plain ASCII text file, so a user can change its +contents easily. It allows a user to customize the behavior of +internationalized portion of Xlib without changing Xlib itself. +</para> + +<para> +This document describes; +</para> + +<itemizedlist> + <listitem> + <para> +Database Format Definition + </para> + </listitem> + <listitem> + <para> +Contents of Database in sample implementation +<!-- .RE --> + </para> + </listitem> +</itemizedlist> + +<para> +Since it is hard to define the set of required information for all +platforms, only the flexible database format is defined. +The available entries in database are implementation dependent. +</para> + +</sect1> +<sect1 id="Database_Format_Definition"> +<title>Database Format Definition</title> +<para> +The X Locale Database contains one or more category definitions. +This section describes the format of each category definition. +</para> + +<para> +The category definition consists of one or more class definitions. +Each class definition has a pair of class name and class value, or +has several subclasses which are enclosed by the left brace ({) and +the right brace (}). +</para> + +<para> +Comments can be placed by using the number sign character (#). +Putting the number sign character on the top of the line indicates +that the entire line is comment. Also, putting any whitespace character +followed by the number sign character indicates that a part of the line +(from the number sign to the end of the line) is comment. +A line can be continued by placing backslash (\) character as the +last character on the line; this continuation character will be +discarded from the input. Comment lines cannot be continued on +a subsequent line using an escaped new line character. +</para> + +<para> +X Locale Database only accepts XPCS, the X Portable Character Set. +The reserved symbols are; the quotation mark("), the number sign (#), +the semicolon(;), the backslash(\), the left brace({) and +the right brace(}). +</para> + +<para> +The format of category definition is; +</para> + +<informaltable frame="none"> + <tgroup cols='3' align='left'> + <colspec colname='c1' colwidth="3*" colsep="0"/> + <colspec colname='c2' colwidth="1*" colsep="0"/> + <colspec colname='c3' colwidth="6*" colsep="0"/> + <tbody> + <row rowsep="0"> + <entry>CategoryDefinition</entry> + <entry>::=</entry> + <entry>CategoryHeader CategorySpec CategoryTrailer</entry> + </row> + <row rowsep="0"> + <entry>CategoryHeader</entry> + <entry>::=</entry> + <entry>CategoryName NL</entry> + </row> + <row rowsep="0"> + <entry>CategorySpec</entry> + <entry>::=</entry> + <entry>{ ClassSpec }</entry> + </row> + <row rowsep="0"> + <entry>CategoryTrailer</entry> + <entry>::=</entry> + <entry>"END" Delimiter CategoryName NL</entry> + </row> + <row rowsep="0"> + <entry>CategoryName</entry> + <entry>::=</entry> + <entry>String</entry> + </row> + <row rowsep="0"> + <entry>ClassSpec</entry> + <entry>::=</entry> + <entry>ClassName Delimiter ClassValue NL</entry> + </row> + <row rowsep="0"> + <entry>ClassName</entry> + <entry>::=</entry> + <entry>String</entry> + </row> + <row rowsep="0"> + <entry>ClassValue</entry> + <entry>::=</entry> + <entry>ValueList | "{" NL { ClassSpec } "}"</entry> + </row> + <row rowsep="0"> + <entry>ValueList</entry> + <entry>::=</entry> + <entry>Value | Value ";" ValueList</entry> + </row> + <row rowsep="0"> + <entry>Value</entry> + <entry>::=</entry> + <entry>ValuePiece | ValuePiece Value</entry> + </row> + <row rowsep="0"> + <entry>ValuePiece</entry> + <entry>::=</entry> + <entry>String | QuotedString | NumericString</entry> + </row> + <row rowsep="0"> + <entry>String</entry> + <entry>::=</entry> + <entry>Char { Char }</entry> + </row> + <row rowsep="0"> + <entry>QuotedString</entry> + <entry>::=</entry> + <entry>""" QuotedChar { QuotedChar } """</entry> + </row> + <row rowsep="0"> + <entry>NumericString</entry> + <entry>::=</entry> + <entry>"\\o" OctDigit { OctDigit }</entry> + </row> + <row rowsep="0"> + <entry></entry> + <entry>|</entry> + <entry>"\\d" DecDigit { DecDigit }</entry> + </row> + <row rowsep="0"> + <entry></entry> + <entry>|</entry> + <entry>"\\x" HexDigit { HexDigit }</entry> + </row> + <row rowsep="0"> + <entry>Char</entry> + <entry>::=</entry> + <entry><XPCS except NL, Space or unescaped reserved symbols></entry> + </row> + <row rowsep="0"> + <entry>QuotedChar</entry> + <entry>::=</entry> + <entry><XPCS except unescaped """></entry> + </row> + <row rowsep="0"> + <entry>OctDigit</entry> + <entry>::=</entry> + <entry><character in the range of "0" - "7"></entry> + </row> + <row rowsep="0"> + <entry>DecDigit</entry> + <entry>::=</entry> + <entry><character in the range of "0" - "9"></entry> + </row> + <row rowsep="0"> + <entry>HexDigit</entry> + <entry>::=</entry> + <entry><character in the range of "0" - "9", "a" - "f", "A" - "F"></entry> + </row> + <row rowsep="0"> + <entry>Delimiter</entry> + <entry>::=</entry> + <entry>Space { Space }</entry> + </row> + <row rowsep="0"> + <entry>Space</entry> + <entry>::=</entry> + <entry><space> | <horizontal tab></entry> + </row> + <row rowsep="0"> + <entry>NL</entry> + <entry>::=</entry> + <entry><newline></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +Elements separated by vertical bar (|) are alternatives. Curly +braces ({...}) indicate zero or more repetitions of the enclosed +elements. Square brackets ([...]) indicate that the enclosed element +is optional. Quotes ("...") are used around literal characters. +</para> + +<para> +The backslash, which is not the top character of the NumericString, is +recognized as an escape character, so that the next one character is +treated as a literal character. For example, the two-character +sequence, ""\"""(the backslash followed by the quotation mark) is +recognized and replaced with a quotation mark character. +Any whitespace character, that is not the Delimiter, unquoted and +unescaped, is ignored. +</para> + +</sect1> +<sect1 id="Contents_of_Database_"> +<title>Contents of Database </title> +<para> +The available categories and classes depend on implementation, because +different platform will require different information set. +For example, some platform have system locale but some platform don't. +Furthermore, there might be a difference in functionality even if the +platform has system locale. +</para> + +<para> +In current sample implementation, categories listed below are available. +</para> + +<informaltable frame="none"> + <tgroup cols='3' align='left'> + <colspec colname='c1' colwidth="2*" colsep="0"/> + <colspec colname='c2' colwidth="1*" colsep="0"/> + <tbody> + <row rowsep="0"> + <entry>XLC_FONTSET:XFontSet relative information</entry> + </row> + <row rowsep="0"> + <entry>XLC_XLOCALE:Character classification and conversion information</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +</sect1> +<sect1 id="XLC_FONTSET_Category"> +<title>XLC_FONTSET Category</title> +<para> +The XLC_FONTSET category defines the XFontSet relative information. +It contains the CHARSET_REGISTRY-CHARSET_ENCODING name and character +mapping side (GL, GR, etc), and is used in Output Method (OM). +</para> + +<informaltable frame="none"> + <tgroup cols='3' align='left'> + <thead> + <colspec colname='c1' colwidth="3*" colsep="0"/> + <colspec colname='c2' colwidth="1*" colsep="0"/> + <colspec colname='c3' colwidth="3*" colsep="0"/> + <row> + <entry>class</entry> + <entry>super class</entry> + <entry>description</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>fsN</entry> + <entry></entry> + <entry>Nth fontset (N=0,1,2, ...)</entry> + </row> + <row rowsep="0"> + <entry>charset</entry> + <entry>fsN</entry> + <entry>list of encoding name</entry> + </row> + <row rowsep="0"> + <entry>font</entry> + <entry>fsN</entry> + <entry>list of font encoding name</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<variablelist> + <varlistentry> + <term>fsN</term> + <listitem> + <para> +Includes an encoding information for Nth charset, where N is +the index number (0,1,2,...). If there are 4 charsets available +in current locale, 4 fontsets, fs0, fs1, fs2 and fs3, should be +defined. +This class has two subclasses, 'charset' and 'font'. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>charset</term> + <listitem> + <para> +Specifies an encoding information to be used internally in Xlib +for this fontset. The format of value is; + </para> +<informaltable frame="none"> + <tgroup cols='3' align='left'> + <colspec colname='c1' colwidth="3*" colsep="0"/> + <colspec colname='c2' colwidth="1*" colsep="0"/> + <colspec colname='c3' colwidth="4*" colsep="0"/> + <tbody> + <row rowsep="0"> + <entry>EncodingInfo</entry> + <entry>::=</entry> + <entry>EncodingName [ ":" EncodingSide ]</entry> + </row> + <row rowsep="0"> + <entry>EncodingName</entry> + <entry>::=</entry> + <entry>CHARSET_REGISTRY-CHARSET_ENCODING</entry> + </row> + <row rowsep="0"> + <entry>EncodingSide</entry> + <entry>::=</entry> + <entry>"GL" | "GR"</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer +"X Logical Font Descriptions" document. +</para> +<literallayout> +example: + ISO8859-1:GL +</literallayout> + </listitem> + </varlistentry> + <varlistentry> + <term>font</term> + <listitem> + <para> +Specifies a list of encoding information which is used for searching +appropriate font for this fontset. The left most entry has highest +priority. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect1> +<sect1 id="XLC_XLOCALE_Category"> +<title>XLC_XLOCALE Category</title> +<para> +The XLC_XLOCALE category defines character classification, conversion +and other character attributes. +</para> + +<informaltable frame="none"> + <tgroup cols='3' align='left'> + <colspec colname='c1' colwidth="3*" colsep="0"/> + <colspec colname='c2' colwidth="1*" colsep="0"/> + <colspec colname='c3' colwidth="3*" colsep="0"/> + <thead> + <row> + <entry>class</entry> + <entry>super class</entry> + <entry>description</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>encoding_name</entry> + <entry></entry> + <entry>codeset name</entry> + </row> + <row rowsep="0"> + <entry>mb_cur_max</entry> + <entry></entry> + <entry>MB_CUR_MAX</entry> + </row> + <row rowsep="0"> + <entry>state_depend_encoding</entry> + <entry></entry> + <entry>state dependent or not</entry> + </row> + <row rowsep="0"> + <entry>wc_encoding_mask</entry> + <entry></entry> + <entry>for parsing wc string</entry> + </row> + <row rowsep="0"> + <entry>wc_shift_bits</entry> + <entry></entry> + <entry>for conversion between wc and mb</entry> + </row> + <row rowsep="0"> + <entry>csN</entry> + <entry></entry> + <entry>Nth charset (N=0,1,2,...)</entry> + </row> + <row rowsep="0"> + <entry>side</entry> + <entry>csN</entry> + <entry>mapping side (GL, etc)</entry> + </row> + <row rowsep="0"> + <entry>length</entry> + <entry>csN</entry> + <entry>length of a character</entry> + </row> + <row rowsep="0"> + <entry>mb_encoding</entry> + <entry>csN</entry> + <entry>for parsing mb string</entry> + </row> + <row rowsep="0"> + <entry>wc_encoding</entry> + <entry>csN</entry> + <entry>for parsing wc string</entry> + </row> + <row rowsep="0"> + <entry>ct_encoding</entry> + <entry>csN</entry> + <entry>list of encoding name for ct</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<variablelist> + <varlistentry> + <term>encoding_name</term> + <listitem> + <para> +Specifies a codeset name of current locale. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>mb_cur_max</term> + <listitem> + <para> +Specifies a maximum allowable number of bytes in a multi-byte character. +It is corresponding to MB_CUR_MAX of "ISO/IEC 9899:1990 C Language Standard". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>state_depend_encoding</term> + <listitem> + <para> +Indicates a current locale is state dependent. The value should be +specified "True" or "False". + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>wc_encoding_mask</term> + <listitem> + <para> +Specifies a bit-mask for parsing wide-char string. Each wide character is +applied bit-and operation with this bit-mask, then is classified into +the unique charset, by using 'wc_encoding'. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>wc_shift_bits</term> + <listitem> + <para> +Specifies a number of bit to be shifted for converting from a multi-byte +character to a wide character, and vice-versa. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>csN</term> + <listitem> + <para> +<!-- .br --> +Includes a character set information for Nth charset, where N is the +index number (0,1,2,...). If there are 4 charsets available in current +locale, cs0, cs1, cs2 and cs3 should be defined. This class has five +subclasses, 'side', 'length', 'mb_encoding' 'wc_encoding' and 'ct_encoding'. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>side</term> + <listitem> + <para> +Specifies a mapping side of this charset. The format of this value is; + </para> + <literallayout> + Side ::= EncodingSide[":Default"] + </literallayout> + <para> +The suffix ":Default" can be specified. It indicates that a character +belongs to the specified side is mapped to this charset in initial state. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>length</term> + <listitem> + <para> +<!-- .br --> +Specifies a number of bytes of a multi-byte character of this charset. +It should not contain the length of any single-shift sequence. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>mb_encoding</term> + <listitem> + <para> +Specifies a list of shift sequence for parsing multi-byte string. +The format of this value is; + </para> +<informaltable frame="none"> + <tgroup cols='3' align='left'> + <colspec colname='c1' colwidth="3*" colsep="0"/> + <colspec colname='c2' colwidth="1*" colsep="0"/> + <colspec colname='c3' colwidth="5*" colsep="0"/> + <tbody> + <row rowsep="0"> + <entry>MBEncoding</entry> + <entry>::=</entry> + <entry>ShiftType ShiftSequence</entry> + </row> + <row rowsep="0"> + <entry></entry> + <entry>|</entry> + <entry>ShiftType ShiftSequence ";" MBEncoding</entry> + </row> + <row rowsep="0"> + <entry>ShiftType</entry> + <entry>::=</entry> + <entry>"<SS>"|"<LSL>"|"<LSR>"</entry> + </row> + <row rowsep="0"> + <entry>ShiftSequence</entry> + <entry>::=</entry> + <entry>SequenceValue|SequenceValue ShiftSequence</entry> + </row> + <row rowsep="0"> + <entry>SequenceValue</entry> + <entry>::=</entry> + <entry>NumericString</entry> + </row> + </tbody> + </tgroup> +</informaltable> + + <literallayout> +example: + <LSL> \x1b \x28 \x4a; <LSL> \x1b \x28 \x42 + </literallayout> + </listitem> + </varlistentry> + <varlistentry> + <term>wc_encoding</term> + <listitem> + <para> +Specifies an integer value for parsing wide-char string. +It is used to determine the charset for each wide character, after +applying bit-and operation using 'wc_encoding_mask'. +This value should be unique in all csN classes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ct_encoding</term> + <listitem> + <para> +Specifies a list of encoding information that can be used for Compound +Text. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect1> + +<sect1 id="Sample_of_X_Locale_Database"> +<title>Sample of X Locale Database</title> +<para> +The following is sample X Locale Database file. +</para> + +<literallayout class="monospaced"> +# XLocale Database Sample for ja_JP.euc +# + +# +# XLC_FONTSET category +# +XLC_FONTSET +# fs0 class (7 bit ASCII) +fs0 { + charset ISO8859-1:GL + font ISO8859-1:GL; JISX0201.1976-0:GL +} +# fs1 class (Kanji) +fs1 { + charset JISX0208.1983-0:GL + font JISX0208.1983-0:GL +} +# fs2 class (Half Kana) +fs2 { + charset JISX0201.1976-0:GR + font JISX0201.1976-0:GR +} +# fs3 class (User Defined Character) +# fs3 { +# charset JISX0212.1990-0:GL +# font JISX0212.1990-0:GL +# } +END XLC_FONTSET + +# +# XLC_XLOCALE category +# +XLC_XLOCALE + +encoding_name ja.euc +mb_cur_max 3 +state_depend_encoding False + +wc_encoding_mask \x00008080 +wc_shift_bits 8 + +# cs0 class +cs0 { + side GL:Default + length 1 + wc_encoding \x00000000 + ct_encoding ISO8859-1:GL; JISX0201.1976-0:GL +} +# cs1 class +cs1 { + side GR:Default + length 2 + + wc_encoding \x00008080 + + ct_encoding JISX0208.1983-0:GL; JISX0208.1983-0:GR;\ + JISX0208.1983-1:GL; JISX0208.1983-1:GR +} + +# cs2 class +cs2 { + side GR + length 1 + mb_encoding <SS> \x8e + + wc_encoding \x00000080 + + ct_encoding JISX0201.1976-0:GR +} + +# cs3 class +# cs3 { +# side GL +# length 2 +# mb_encoding <SS> \x8f +# #if HasWChar32 +# wc_encoding \x20000000 +# #else +# wc_encoding \x00008000 +# #endif +# ct_encoding JISX0212.1990-0:GL; JISX0212.1990-0:GR +# } + +END XLC_XLOCALE +</literallayout> +</sect1> + +<sect1 id="Reference"> +<title>Reference</title> +<para> +[1] <emphasis remap='I'>ISO/IEC 9899:1990 C Language Standard</emphasis> +</para> +<para> +[2] <emphasis remap='I'>X Logical Font Descriptions</emphasis> +</para> + +</sect1> +</chapter> +</book> diff --git a/libX11/specs/i18n/trans/trans.xml b/libX11/specs/i18n/trans/trans.xml index 9a01d97f6..c8447f934 100644 --- a/libX11/specs/i18n/trans/trans.xml +++ b/libX11/specs/i18n/trans/trans.xml @@ -1,1979 +1,1979 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-
-<book id="xtransportspec">
-
-<bookinfo>
- <title>The XIM Transport Specification</title>
- <subtitle>Revision 0.1</subtitle>
- <releaseinfo>X Version 11, Release 7</releaseinfo>
- <authorgroup>
- <author>
- <firstname>Takashi</firstname><surname>Fujiwara</surname>
- <affiliation><orgname>FUJITSU LIMITED</orgname></affiliation>
- </author>
- </authorgroup>
- <copyright><year>1994</year><holder>FUJITSU LIMITED</holder></copyright>
- <copyright><year>1994</year><holder>X Consortium</holder></copyright>
-
- <productnumber>Revision 0.1</productnumber>
-
-
-<abstract>
-<para>
-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.
-</para>
-</abstract>
-
-<legalnotice>
-
-<para>
-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:
-</para>
-
-<para>
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-</para>
-
-<para>
-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.
-</para>
-
-<para>
-Except as contained in this notice, the name of The Open Group shall not
-be used in advertising or otherwise to promote the sale, use or other dealings
-in this Software without prior written authorization from X Consortium.
-</para>
-
-<para>X Window System is a trademark of The Open Group.</para>
-
-</legalnotice>
-</bookinfo>
-
-<chapter id="xim_transport_specification">
-<title>X Transport Specification</title>
-
-<sect1 id="Introduction">
-<title>Introduction</title>
-<!-- .XS -->
-<!-- (SN Introduction -->
-<!-- .XE -->
-<para>
-<!-- .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 -->
-</para>
-<variablelist>
- <varlistentry>
- <term><emphasis>The protocol layer</emphasis></term>
- <listitem>
- <para>
-implements overall function of XIM and calls the interface layer
-functions when it needs to communicate to IM Server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis>The interface layer</emphasis></term>
- <listitem>
- <para>
-separates the implementation of the transport layer from the protocol
-layer, in other words, it provides implementation independent hook for
-the transport layer functions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>The transport layer</emphasis></term>
- <listitem>
- <para>
-handles actual data communication with IM Server. It is done by a set
-of several functions named transporters.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-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. <!-- xref -->
-</para>
-</sect1>
-
-<sect1 id="Initialization">
-<title>Initialization</title>
-
-<sect2 id="Registering_structure_to_initialize">
-<title>Registering structure to initialize</title>
-
-<para>
-The structure typed as TransportSW contains the list of the transport
-layer the specific implementations supports.
-</para>
-
-<literallayout class="monospaced">
-typedef struct {
- char *transport_name;
- Bool (*config);
-} TransportSW;
-</literallayout>
-
-<informaltable frame="none">
- <tgroup cols="2">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="0"/>
- <tbody>
- <row rowsep="0">
- <entry><emphasis>transport_name</emphasis></entry>
- <entry>name of transport<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote></entry>
- </row>
- <row rowsep="0">
- <entry><emphasis>config</emphasis></entry>
- <entry>initial configuration function</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-
-<para>
-A sample entry for the Xlib supporting transporters is shown below:
-</para>
-
-<literallayout class="monospaced">
-TransportSW _XimTransportRec[] = {
-/* char <emphasis remap='I'>*</emphasis>:
- * transport_name, Bool <emphasis remap='I'>(*config)()</emphasis>
- */
- "X", _XimXConf,
- "tcp", _XimTransConf,
- "local", _XimTransConf,
- "decnet", _XimTransConf,
- "streams", _XimTransConf,
- (char *)NULL, (Bool (*)())NULL,
-};
-</literallayout>
-
-</sect2>
-<sect2 id="Initialization_function">
-<title>Initialization function</title>
-<!-- .XS -->
-<!-- (SN Initialization function -->
-<!-- .XE -->
-<para>
-The following function will be called once when Xlib configures the
-transporter functions.
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>(*config)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>char<parameter> *transport_data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>transport_data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the data specific to the transporter, in IM Server address.<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-This function must setup the transporter function pointers.
-</para>
-
-<para>
-<!-- .LP -->
-The actual <emphasis remap='I'>config</emphasis> function will be chosen by IM Server at the
-pre-connection time, matching by the <emphasis remap='I'>transport_name</emphasis> specified
-in the <function>_XimTransportRec</function> array; The specific members of XimProto
-structure listed below must be initialized so that point they
-appropriate transporter functions.
-</para>
-
-<para>
-If the specified transporter has been configured successfully, this
-function returns True. There is no Alternative Entry for config
-function itself.
-</para>
-
-<para>
-The structure XimProto contains the following function pointers:
-</para>
-
-<literallayout class="monospaced">
-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 */
-</literallayout>
-
-<para>
-These functions are called when Xlib needs to communicate the
-IM Server. These functions must process the appropriate procedure
-described below.
-</para>
-
-</sect2>
-</sect1>
-<sect1 id="The_interface_transport_layer_functions">
-<title>The interface/transport layer functions</title>
-<para>
-Following functions are used for the transport interface.
-</para>
-
-<table frame="all" id="transport_layer_functions_2">
- <title>The Transport Layer Functions</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="3*" colsep="1"/>
- <colspec colname="col2" colwidth="3*" colsep="1"/>
- <colspec colname="col3" colwidth="1*" colsep="1"/>
- <thead>
- <row>
- <entry align="center">Alternate Entry (Interface Layer)</entry>
- <entry align="center">XimProto member (Transport Layer)</entry>
- <entry align="center">Section</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>_XimConnect</entry>
- <entry>connect</entry>
- <entry>3.1</entry>
- </row>
- <row>
- <entry>_XimShutdown</entry>
- <entry>shutdown</entry>
- <entry>3.2</entry>
- </row>
- <row>
- <entry>_XimWrite</entry>
- <entry>write</entry>
- <entry>3.3</entry>
- </row>
- <row>
- <entry>_XimRead</entry>
- <entry>read</entry>
- <entry>3.4</entry>
- </row>
- <row>
- <entry>_XimFlush</entry>
- <entry>flush</entry>
- <entry>3.5</entry>
- </row>
- <row>
- <entry>_XimRegisterDispatcher</entry>
- <entry>register_dispatcher</entry>
- <entry>3.6</entry>
- </row>
- <row>
- <entry>_XimCallDispatcher</entry>
- <entry>call_dispatcher</entry>
- <entry>3.7</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-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.
-</para>
-
-<sect2 id="Opening_connection">
-<title>Opening connection</title>
-<para>
-<!-- .LP -->
-When <function>XOpenIM</function> is called, the following function is called to connect
-with the IM Server.
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>(*connect)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> _XimConnect</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</sect2>
-
-<sect2 id="Closing_connection">
-<title>Closing connection</title>
-<!-- .XS -->
-<!-- (SN Closing connection -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-When <function>XCloseIM</function> is called, the following function is called to
-disconnect the connection with the IM Server. The Alternative Entry
-for this function is:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> (*shutdown)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<!-- .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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>_XimShutdown</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</sect2>
-
-<sect2 id="Writing_data">
-<title>Writing data</title>
-<para>
-The following function is called, when Xlib needs to write data to the
-IM Server.
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> _XimWrite</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> len</parameter></paramdef>
- <paramdef>XPointer<parameter> data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the length of writing data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the writing data.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-This function writes the <emphasis remap='I'>data</emphasis> to the IM Server, regardless
-of the contents. The number of bytes is passed to <emphasis remap='I'>len</emphasis>. The
-writing data is passed to <emphasis remap='I'>data</emphasis>. 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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>_XimWrite</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> len</parameter></paramdef>
- <paramdef>XPointer<parameter> data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the length of writing data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the writing data.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</sect2>
-<sect2 id="Reading_data">
-<title>Reading data</title>
-<para>
-The following function is called when Xlib waits for response from IM
-server synchronously.
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> _XimRead</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>XPointer<parameter> read_buf</parameter></paramdef>
- <paramdef>int<parameter> buf_len</parameter></paramdef>
- <paramdef>int<parameter> *ret_len</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>read_buf</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the buffer to store data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>buf_len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the size of the <emphasis remap='I'>buffer</emphasis>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>ret_len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the length of stored data.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-This function stores the read data in <emphasis remap='I'>read_buf</emphasis>, which size is
-specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to <emphasis remap='I'>ret_len</emphasis>.
-This function return True, if the data is read normally or reading
-data is completed.
-</para>
-<para>
-The Alternative Entry for this function is:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> _XimRead</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> *ret_len</parameter></paramdef>
- <paramdef>XPointer<parameter> buf</parameter></paramdef>
- <paramdef>int<parameter> buf_len</parameter></paramdef>
- <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
- <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>ret_len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>buf</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the buffer to store data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>buf_len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the length of <emphasis remap='I'>buffer</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>predicate</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the predicate for the XIM data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>predicate_arg</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the predicate specific data.
-<!-- .sp 6p -->
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-The predicate procedure indicates whether the <emphasis remap='I'>data</emphasis> is for the
-XIM or not. <emphasis remap='I'>len</emphasis>
-This function stores the read data in <emphasis remap='I'>buf</emphasis>, which size
-is specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to
-<emphasis remap='I'>ret_len</emphasis>. If <emphasis remap='I'>preedicate()</emphasis>
-returns True, this function returns True. If not, it calls the registered callback function.
-</para>
-
-<para>
-The procedure and its arguments are:
-</para>
-
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>(*predicate)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> len</parameter></paramdef>
- <paramdef>XPointer<parameter> data</parameter></paramdef>
- <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the buffer to store data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>predicate_arg</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the predicate specific data.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</sect2>
-<sect2 id="Flushing_buffer">
-<title>Flushing buffer</title>
-<para>
-The following function is called when Xlib needs to flush the data.
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>(*flush)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function> _XimFlush</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</sect2>
-<sect2 id="Registering_asynchronous_data_handler">
-<title>Registering asynchronous data handler</title>
-<para>
-Xlib needs to handle asynchronous response from IM Server. This is
-because some of the XIM data occur asynchronously to X events.
-</para>
-
-<para>
-Those data will be handled in the <emphasis remap='I'>Filter</emphasis>,
-and the <emphasis remap='I'>Filter</emphasis>
-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
-<function>_XimCallDispatcher</function>.
-</para>
-
-<para>
-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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>(*register_dispatcher)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef>
- <paramdef>XPointer<parameter> call_data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dispatcher</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the dispatcher function to register.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>call_data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-The dispatcher is a function of the following type:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>(*dispatcher)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> len</parameter></paramdef>
- <paramdef>XPointer<parameter> data</parameter></paramdef>
- <paramdef>XPointer<parameter> call_data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the buffer to store data.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>call_data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a parameter passed to the register_dispatcher.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-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.
-</para>
-
-<para>
-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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> _XimRegisterDispatcher</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef>
- <paramdef>XPointer<parameter> call_data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>dispatcher</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the dispatcher function to register.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>call_data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</sect2>
-<sect2 id="Calling_dispatcher">
-<title>Calling dispatcher</title>
-<para>
-The following function is used to call the registered dispatcher
-function, when the asynchronous response from IM Server has arrived.
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>(*call_dispatcher)</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> len</parameter></paramdef>
- <paramdef>XPointer<parameter> data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>im</emphasis>
- </term>
- <listitem>
- <para>
-Specifies XIM structure address.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>len</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the size of <emphasis remap='I'>data</emphasis> buffer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the buffer to store data.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-The call_dispatcher must call the dispatcher function, in order of
-their registration. <emphasis remap='I'>len</emphasis> and <emphasis remap='I'>data</emphasis> are the data passed to
-register_dispatcher.
-</para>
-
-<para>
-The return values are checked at each invocation, and if it finds
-True, it immediately return with true for its return value.
-</para>
-
-<para>
-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:
-</para>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function> _XimCallDispatcher</function></funcdef>
- <paramdef>XIM<parameter> im</parameter></paramdef>
- <paramdef>INT16<parameter> len</parameter></paramdef>
- <paramdef>XPointer<parameter> call_data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-
-</sect2>
-</sect1>
-<sect1 id="Sample_implementations_for_the_Transport_Layer">
-<title>Sample implementations for the Transport Layer</title>
-<para>
-Sample implementations for the transporter using the X connection is
-described here.
-</para>
-
-<sect2 id="X_Transport">
-<title>X Transport</title>
-<para>
-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".
-</para>
-
-<sect3 id="Connection">
-<title>Connection</title>
-<para>
-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.
-</para>
-
-<para>
-<!-- .LP -->
-Refer to "The Input Method Protocol" for the XIM_SERVER atom.
-</para>
-
-<table frame="none" id="transport_layer_functions">
- <title>The ClientMessage sent to the IMS window.</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>32</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[0]</entry>
- <entry>client communication window ID</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[1]</entry>
- <entry>client-major-transport-version(*1)</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[2]</entry>
- <entry>client-major-transport-version(*1)</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-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.
-</para>
-
-<table frame="none" id="clientmessage_sent_by_im_server">
- <title>The ClientMessage sent by IM Server.</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>32</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[0]</entry>
- <entry>client communication window ID</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[1]</entry>
- <entry>client-major-transport-version(*1)</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[2]</entry>
- <entry>client-major-transport-version(*1)</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[3]</entry>
- <entry>dividing size between ClientMessage and Property(*2)</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-(*1) major/minor-transport-version
-</para>
-
-<para>
-The read/write method is decided by the combination of
-major/minor-transport-version, as follows:
-</para>
-
-<table frame="all" id="readwrite_method_and_the_majorminor_transport_version">
-<title>The read/write method and the major/minor-transport-version</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="1"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3*" colsep="1"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
- <thead>
- <row>
- <entry spanname="span-horiz">Transport-version</entry>
- <entry>read/write</entry>
- </row>
- <row>
- <entry>major</entry>
- <entry>minor</entry>
- <entry></entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry morerows="2">0</entry>
- <entry>0</entry>
- <entry>only-CM & Property-with-CM</entry>
- </row>
- <row rowsep="0">
- <entry>1</entry>
- <entry>only-CM & multi-CM</entry>
- </row>
- <row rowsep="1">
- <entry>2</entry>
- <entry>only-CM & multi-CM & Property-with-CM</entry>
- </row>
- <row rowsep="1">
- <entry>1</entry>
- <entry>0</entry>
- <entry>PropertyNotify</entry>
- </row>
- <row rowsep="0">
- <entry morerows="1">2</entry>
- <entry>0</entry>
- <entry>only-CM & PropertyNotify</entry>
- </row>
- <row>
- <entry>1</entry>
- <entry>only-CM & multi-CM & PropertyNotify</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<literallayout class="monospaced">
-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
-
-</literallayout>
-
-
-<para>
-The method to decide major/minor-transport-version is as follows:
-</para>
-
-<itemizedlist>
- <listitem>
- <para>
-The client sends 0 as major/minor-transport-version to the IM Server.
-The client must support all methods in Table 4-3. <!-- xref -->
-The client may send another number as major/minor-transport-version to
-use other method than the above in the future.
- </para>
- </listitem>
- <listitem>
- <para>
-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.
- </para>
- </listitem>
- <listitem>
- <para>
-If major/minor-transport-version number is not available, it is regarded
-as 0.
- </para>
- </listitem>
-</itemizedlist>
-
-<para>
-(*2) dividing size between ClientMessage and Property
-</para>
-
-<para>
-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.
-</para>
-
-</sect3>
-
-<sect3 id="read_write_">
-<title>read/write </title>
-<para>
-The data is transferred via either ClientMessage or Window Property in
-the X Window System.
-</para>
-
-<sect4 id="Format_for_the_data_from_the_Client_to_the_IM_Server">
-<title>Format for the data from the Client to the IM Server</title>
-<para>
-<emphasis role="bold">ClientMessage</emphasis>
-</para>
-
-<para>
-If data is sent via ClientMessage event, the format is as follows:
-</para>
-
-<table frame="none" id="clientmessage_events_format_first_or_middle">
- <title>The ClientMessage event's format (first or middle)</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>char</entry>
- <entry>data.b[20]</entry>
- <entry>(read/write DATA : 20 byte)</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-
-
-<table frame="none" id="clientmessage_events_format_only_or_last">
- <title>The ClientMessage event's format (only or last)</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>char</entry>
- <entry>data.b[20]</entry>
- <entry>(read/write DATA : MAX 20 byte)
-<footnote><para>If the data is smaller
-than 20 bytes, all data other than available data must be 0.
-</para></footnote>
- </entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-<emphasis role="bold">Property</emphasis>
-</para>
-
-<para>
-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.
-</para>
-
-<itemizedlist>
- <listitem>
- <para>
-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.
- </para>
- </listitem>
- <listitem>
- <para>
-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.
- </para>
- </listitem>
-</itemizedlist>
-
-<para>
-The arguments of the XChangeProperty are as follows:
-</para>
-
-
-<table frame="none" id="xchangeproperty_events_format">
- <title>The XChangeProperty event's format</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Argument</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS communication window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>property</entry>
- <entry>read/write property Atom (*1)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>mode</entry>
- <entry>PropModeAppend</entry>
- </row>
- <row rowsep="0">
- <entry>u_char</entry>
- <entry>*data</entry>
- <entry>read/write DATA</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>nelements</entry>
- <entry>length of DATA</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-(*1) The read/write property ATOM allocates the following strings by
-<function>XInternAtom</function>.
-"_clientXXX"
-</para>
-
-<para>
-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).
-</para>
-
-<para>
-If Atom is notified via ClientMessage event, the format of the ClientMessage
-is as follows:
-</para>
-
-<table frame="none" id="clientmessage_events_format_to_send_atom_of_property">
- <title>The ClientMessage event's format to send Atom of property</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[0]</entry>
- <entry>length of read/write property Atom</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[1]</entry>
- <entry>read/write property Atom</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-</sect4>
-
-<sect4 id="Format_for_the_data_from_the_IM_Server_to_the_Client">
-<title>Format for the data from the IM Server to the Client</title>
-<para>
-<emphasis role="bold">ClientMessage</emphasis>
-</para>
-
-<para>
-The format of the ClientMessage is as follows:
-</para>
-
-<table frame="none" id="clientmessage_events_format_first_or_middle_2">
- <title>The ClientMessage event's format (first or middle)</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>char</entry>
- <entry>data.b[20]</entry>
- <entry>(read/write DATA : 20 byte)</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-
-
-
-
-<table frame="none" id="clientmessage_events_format_only_or_last_2">
- <title>The ClientMessage event's format (only or last)</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>char</entry>
- <entry>data.b[20]</entry>
- <entry>(read/write DATA : MAX 20 byte) (*1)</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-(*1) If the data size is smaller than 20 bytes, all data other than available
-data must be 0.
-</para>
-
-<para>
-<emphasis role="bold">Property</emphasis>
-</para>
-
-<para>
-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.
-</para>
-
-<itemizedlist>
- <listitem>
- <para>
-The XChangeProperty function is used to store data in the IMS
-communication window, and Atom of the property is sent via the
-ClientMessage event.
- </para>
- </listitem>
- <listitem>
- <para>
-The XChangeProperty function is used to store data in the IMS
-communication window, and Atom of the property is sent via
-PropertyNotify event.
- </para>
- </listitem>
-</itemizedlist>
-
-<para>
-The arguments of the XChangeProperty are as follows:
-</para>
-
-<table frame="none" id="xchangeproperty_events_format_b">
- <title>The XChangeProperty event's format</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Argument</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS communication window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>property</entry>
- <entry>read/write property Atom (*1)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>mode</entry>
- <entry>PropModeAppend</entry>
- </row>
- <row rowsep="0">
- <entry>u_char</entry>
- <entry>*data</entry>
- <entry>read/write DATA</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>nelements</entry>
- <entry>length of DATA</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>
-(*1) The read/write property ATOM allocates some strings, which are not
-allocated by the client, by <function>XInternAtom</function>.
-</para>
-
-<para>
-The IM Server changes the property with the mode of PropModeAppend and
-the client reads it with the delete mode, i.e. (delete = True).
-</para>
-
-<para>
-If Atom is notified via ClientMessage event, the format of the ClientMessage
-is as follows:
-</para>
-
-<table frame="none" id="clientmessage_events_format_to_send_atom_of_property_2">
- <title>The ClientMessage event's format to send Atom of property</title>
- <tgroup cols="3">
- <colspec colname="col1" colwidth="1*" colsep="0"/>
- <colspec colname="col2" colwidth="1*" colsep="1"/>
- <colspec colname="col3" colwidth="3.5*" colsep="0"/>
- <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
- <thead>
- <row>
- <entry align="left" spanname="span-horiz">Structure Member</entry>
- <entry align="left">Contents</entry>
- </row>
- </thead>
- <tbody>
- <row rowsep="0">
- <entry>int</entry>
- <entry>type</entry>
- <entry>ClientMessage</entry>
- </row>
- <row rowsep="0">
- <entry>u_long</entry>
- <entry>serial</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Bool</entry>
- <entry>send_event</entry>
- <entry>Set by the X Window System</entry>
- </row>
- <row rowsep="0">
- <entry>Display</entry>
- <entry>*display</entry>
- <entry>The display to which connects</entry>
- </row>
- <row rowsep="0">
- <entry>Window</entry>
- <entry>window</entry>
- <entry>IMS Window ID</entry>
- </row>
- <row rowsep="0">
- <entry>Atom</entry>
- <entry>message_type</entry>
- <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
- </row>
- <row rowsep="0">
- <entry>int</entry>
- <entry>format</entry>
- <entry>8</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[0]</entry>
- <entry>length of read/write property Atom</entry>
- </row>
- <row rowsep="0">
- <entry>long</entry>
- <entry>data.1[1]</entry>
- <entry>read/write property Atom</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-</sect4>
-</sect3>
-<sect3 id="Closing_Connection">
-<title>Closing Connection</title>
-
-<para>
-If the client disconnect with the IM Server, shutdown function should
-free the communication window properties and etc..
-</para>
-
-</sect3>
-</sect2>
-</sect1>
-
-<sect1 id="References">
-<title>References</title>
-<para>
-[1] Masahiko Narita and Hideki Hiura, <emphasis remap='I'>"The Input Method Protocol"</emphasis>
-</para>
-</sect1>
-
-</chapter>
-</book>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<book id="trans"> + +<bookinfo> + <title>The XIM Transport Specification</title> + <subtitle>Revision 0.1</subtitle> + <releaseinfo>X Version 11, Release 7</releaseinfo> + <authorgroup> + <author> + <firstname>Takashi</firstname><surname>Fujiwara</surname> + <affiliation><orgname>FUJITSU LIMITED</orgname></affiliation> + </author> + </authorgroup> + <copyright><year>1994</year><holder>FUJITSU LIMITED</holder></copyright> + <copyright><year>1994</year><holder>X Consortium</holder></copyright> + + <productnumber>Revision 0.1</productnumber> + + +<abstract> +<para> +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. +</para> +</abstract> + +<legalnotice> + +<para> +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: +</para> + +<para> +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. +</para> + +<para> +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. +</para> + +<para> +Except as contained in this notice, the name of The Open Group shall not +be used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from X Consortium. +</para> + +<para>X Window System is a trademark of The Open Group.</para> + +</legalnotice> +</bookinfo> + +<chapter id="xim_transport_specification"> +<title>X Transport Specification</title> + +<sect1 id="Introduction"> +<title>Introduction</title> +<!-- .XS --> +<!-- (SN Introduction --> +<!-- .XE --> +<para> +<!-- .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 --> +</para> +<variablelist> + <varlistentry> + <term><emphasis>The protocol layer</emphasis></term> + <listitem> + <para> +implements overall function of XIM and calls the interface layer +functions when it needs to communicate to IM Server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>The interface layer</emphasis></term> + <listitem> + <para> +separates the implementation of the transport layer from the protocol +layer, in other words, it provides implementation independent hook for +the transport layer functions. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis>The transport layer</emphasis></term> + <listitem> + <para> +handles actual data communication with IM Server. It is done by a set +of several functions named transporters. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +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. <!-- xref --> +</para> +</sect1> + +<sect1 id="Initialization"> +<title>Initialization</title> + +<sect2 id="Registering_structure_to_initialize"> +<title>Registering structure to initialize</title> + +<para> +The structure typed as TransportSW contains the list of the transport +layer the specific implementations supports. +</para> + +<literallayout class="monospaced"> +typedef struct { + char *transport_name; + Bool (*config); +} TransportSW; +</literallayout> + +<informaltable frame="none"> + <tgroup cols="2"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="0"/> + <tbody> + <row rowsep="0"> + <entry><emphasis>transport_name</emphasis></entry> + <entry>name of transport<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote></entry> + </row> + <row rowsep="0"> + <entry><emphasis>config</emphasis></entry> + <entry>initial configuration function</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +A sample entry for the Xlib supporting transporters is shown below: +</para> + +<literallayout class="monospaced"> +TransportSW _XimTransportRec[] = { +/* char <emphasis remap='I'>*</emphasis>: + * transport_name, Bool <emphasis remap='I'>(*config)()</emphasis> + */ + "X", _XimXConf, + "tcp", _XimTransConf, + "local", _XimTransConf, + "decnet", _XimTransConf, + "streams", _XimTransConf, + (char *)NULL, (Bool (*)())NULL, +}; +</literallayout> + +</sect2> +<sect2 id="Initialization_function"> +<title>Initialization function</title> +<!-- .XS --> +<!-- (SN Initialization function --> +<!-- .XE --> +<para> +The following function will be called once when Xlib configures the +transporter functions. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>(*config)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>char<parameter> *transport_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>transport_data</emphasis> + </term> + <listitem> + <para> +Specifies the data specific to the transporter, in IM Server address.<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This function must setup the transporter function pointers. +</para> + +<para> +<!-- .LP --> +The actual <emphasis remap='I'>config</emphasis> function will be chosen by IM Server at the +pre-connection time, matching by the <emphasis remap='I'>transport_name</emphasis> specified +in the <function>_XimTransportRec</function> array; The specific members of XimProto +structure listed below must be initialized so that point they +appropriate transporter functions. +</para> + +<para> +If the specified transporter has been configured successfully, this +function returns True. There is no Alternative Entry for config +function itself. +</para> + +<para> +The structure XimProto contains the following function pointers: +</para> + +<literallayout class="monospaced"> +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 */ +</literallayout> + +<para> +These functions are called when Xlib needs to communicate the +IM Server. These functions must process the appropriate procedure +described below. +</para> + +</sect2> +</sect1> +<sect1 id="The_interface_transport_layer_functions"> +<title>The interface/transport layer functions</title> +<para> +Following functions are used for the transport interface. +</para> + +<table frame="all" id="transport_layer_functions_2"> + <title>The Transport Layer Functions</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="3*" colsep="1"/> + <colspec colname="col2" colwidth="3*" colsep="1"/> + <colspec colname="col3" colwidth="1*" colsep="1"/> + <thead> + <row> + <entry align="center">Alternate Entry (Interface Layer)</entry> + <entry align="center">XimProto member (Transport Layer)</entry> + <entry align="center">Section</entry> + </row> + </thead> + <tbody> + <row> + <entry>_XimConnect</entry> + <entry>connect</entry> + <entry>3.1</entry> + </row> + <row> + <entry>_XimShutdown</entry> + <entry>shutdown</entry> + <entry>3.2</entry> + </row> + <row> + <entry>_XimWrite</entry> + <entry>write</entry> + <entry>3.3</entry> + </row> + <row> + <entry>_XimRead</entry> + <entry>read</entry> + <entry>3.4</entry> + </row> + <row> + <entry>_XimFlush</entry> + <entry>flush</entry> + <entry>3.5</entry> + </row> + <row> + <entry>_XimRegisterDispatcher</entry> + <entry>register_dispatcher</entry> + <entry>3.6</entry> + </row> + <row> + <entry>_XimCallDispatcher</entry> + <entry>call_dispatcher</entry> + <entry>3.7</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +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. +</para> + +<sect2 id="Opening_connection"> +<title>Opening connection</title> +<para> +<!-- .LP --> +When <function>XOpenIM</function> is called, the following function is called to connect +with the IM Server. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>(*connect)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> _XimConnect</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> +</variablelist> +</sect2> + +<sect2 id="Closing_connection"> +<title>Closing connection</title> +<!-- .XS --> +<!-- (SN Closing connection --> +<!-- .XE --> +<para> +<!-- .LP --> +When <function>XCloseIM</function> is called, the following function is called to +disconnect the connection with the IM Server. The Alternative Entry +for this function is: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> (*shutdown)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<!-- .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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>_XimShutdown</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> + +<sect2 id="Writing_data"> +<title>Writing data</title> +<para> +The following function is called, when Xlib needs to write data to the +IM Server. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> _XimWrite</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> len</parameter></paramdef> + <paramdef>XPointer<parameter> data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>len</emphasis> + </term> + <listitem> + <para> +Specifies the length of writing data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>data</emphasis> + </term> + <listitem> + <para> +Specifies the writing data. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This function writes the <emphasis remap='I'>data</emphasis> to the IM Server, regardless +of the contents. The number of bytes is passed to <emphasis remap='I'>len</emphasis>. The +writing data is passed to <emphasis remap='I'>data</emphasis>. 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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>_XimWrite</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> len</parameter></paramdef> + <paramdef>XPointer<parameter> data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>len</emphasis> + </term> + <listitem> + <para> +Specifies the length of writing data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>data</emphasis> + </term> + <listitem> + <para> +Specifies the writing data. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> +<sect2 id="Reading_data"> +<title>Reading data</title> +<para> +The following function is called when Xlib waits for response from IM +server synchronously. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> _XimRead</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>XPointer<parameter> read_buf</parameter></paramdef> + <paramdef>int<parameter> buf_len</parameter></paramdef> + <paramdef>int<parameter> *ret_len</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>read_buf</emphasis> + </term> + <listitem> + <para> +Specifies the buffer to store data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>buf_len</emphasis> + </term> + <listitem> + <para> +Specifies the size of the <emphasis remap='I'>buffer</emphasis> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ret_len</emphasis> + </term> + <listitem> + <para> +Specifies the length of stored data. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This function stores the read data in <emphasis remap='I'>read_buf</emphasis>, which size is +specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to <emphasis remap='I'>ret_len</emphasis>. +This function return True, if the data is read normally or reading +data is completed. +</para> +<para> +The Alternative Entry for this function is: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> _XimRead</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> *ret_len</parameter></paramdef> + <paramdef>XPointer<parameter> buf</parameter></paramdef> + <paramdef>int<parameter> buf_len</parameter></paramdef> + <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef> + <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ret_len</emphasis> + </term> + <listitem> + <para> +Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>buf</emphasis> + </term> + <listitem> + <para> +Specifies the buffer to store data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>buf_len</emphasis> + </term> + <listitem> + <para> +Specifies the length of <emphasis remap='I'>buffer</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>predicate</emphasis> + </term> + <listitem> + <para> +Specifies the predicate for the XIM data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>predicate_arg</emphasis> + </term> + <listitem> + <para> +Specifies the predicate specific data. +<!-- .sp 6p --> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The predicate procedure indicates whether the <emphasis remap='I'>data</emphasis> is for the +XIM or not. <emphasis remap='I'>len</emphasis> +This function stores the read data in <emphasis remap='I'>buf</emphasis>, which size +is specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to +<emphasis remap='I'>ret_len</emphasis>. If <emphasis remap='I'>preedicate()</emphasis> +returns True, this function returns True. If not, it calls the registered callback function. +</para> + +<para> +The procedure and its arguments are: +</para> + + +<funcsynopsis> +<funcprototype> + <funcdef>void <function>(*predicate)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> len</parameter></paramdef> + <paramdef>XPointer<parameter> data</parameter></paramdef> + <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>len</emphasis> + </term> + <listitem> + <para> +Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>data</emphasis> + </term> + <listitem> + <para> +Specifies the buffer to store data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>predicate_arg</emphasis> + </term> + <listitem> + <para> +Specifies the predicate specific data. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> +<sect2 id="Flushing_buffer"> +<title>Flushing buffer</title> +<para> +The following function is called when Xlib needs to flush the data. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void <function>(*flush)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>void <function> _XimFlush</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> +<sect2 id="Registering_asynchronous_data_handler"> +<title>Registering asynchronous data handler</title> +<para> +Xlib needs to handle asynchronous response from IM Server. This is +because some of the XIM data occur asynchronously to X events. +</para> + +<para> +Those data will be handled in the <emphasis remap='I'>Filter</emphasis>, +and the <emphasis remap='I'>Filter</emphasis> +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 +<function>_XimCallDispatcher</function>. +</para> + +<para> +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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>(*register_dispatcher)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dispatcher</emphasis> + </term> + <listitem> + <para> +Specifies the dispatcher function to register. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The dispatcher is a function of the following type: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>(*dispatcher)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> len</parameter></paramdef> + <paramdef>XPointer<parameter> data</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>len</emphasis> + </term> + <listitem> + <para> +Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>data</emphasis> + </term> + <listitem> + <para> +Specifies the buffer to store data. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies a parameter passed to the register_dispatcher. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +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. +</para> + +<para> +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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> _XimRegisterDispatcher</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dispatcher</emphasis> + </term> + <listitem> + <para> +Specifies the dispatcher function to register. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>call_data</emphasis> + </term> + <listitem> + <para> +Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> +<sect2 id="Calling_dispatcher"> +<title>Calling dispatcher</title> +<para> +The following function is used to call the registered dispatcher +function, when the asynchronous response from IM Server has arrived. +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function>(*call_dispatcher)</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> len</parameter></paramdef> + <paramdef>XPointer<parameter> data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>im</emphasis> + </term> + <listitem> + <para> +Specifies XIM structure address. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>len</emphasis> + </term> + <listitem> + <para> +Specifies the size of <emphasis remap='I'>data</emphasis> buffer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>data</emphasis> + </term> + <listitem> + <para> +Specifies the buffer to store data. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The call_dispatcher must call the dispatcher function, in order of +their registration. <emphasis remap='I'>len</emphasis> and <emphasis remap='I'>data</emphasis> are the data passed to +register_dispatcher. +</para> + +<para> +The return values are checked at each invocation, and if it finds +True, it immediately return with true for its return value. +</para> + +<para> +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: +</para> + +<funcsynopsis> +<funcprototype> + <funcdef>Bool <function> _XimCallDispatcher</function></funcdef> + <paramdef>XIM<parameter> im</parameter></paramdef> + <paramdef>INT16<parameter> len</parameter></paramdef> + <paramdef>XPointer<parameter> call_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +</sect2> +</sect1> +<sect1 id="Sample_implementations_for_the_Transport_Layer"> +<title>Sample implementations for the Transport Layer</title> +<para> +Sample implementations for the transporter using the X connection is +described here. +</para> + +<sect2 id="X_Transport"> +<title>X Transport</title> +<para> +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". +</para> + +<sect3 id="Connection"> +<title>Connection</title> +<para> +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. +</para> + +<para> +<!-- .LP --> +Refer to "The Input Method Protocol" for the XIM_SERVER atom. +</para> + +<table frame="none" id="transport_layer_functions"> + <title>The ClientMessage sent to the IMS window.</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>32</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[0]</entry> + <entry>client communication window ID</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[1]</entry> + <entry>client-major-transport-version(*1)</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[2]</entry> + <entry>client-major-transport-version(*1)</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +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. +</para> + +<table frame="none" id="clientmessage_sent_by_im_server"> + <title>The ClientMessage sent by IM Server.</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>32</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[0]</entry> + <entry>client communication window ID</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[1]</entry> + <entry>client-major-transport-version(*1)</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[2]</entry> + <entry>client-major-transport-version(*1)</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[3]</entry> + <entry>dividing size between ClientMessage and Property(*2)</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +(*1) major/minor-transport-version +</para> + +<para> +The read/write method is decided by the combination of +major/minor-transport-version, as follows: +</para> + +<table frame="all" id="readwrite_method_and_the_majorminor_transport_version"> +<title>The read/write method and the major/minor-transport-version</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="1"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3*" colsep="1"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/> + <thead> + <row> + <entry spanname="span-horiz">Transport-version</entry> + <entry>read/write</entry> + </row> + <row> + <entry>major</entry> + <entry>minor</entry> + <entry></entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry morerows="2">0</entry> + <entry>0</entry> + <entry>only-CM & Property-with-CM</entry> + </row> + <row rowsep="0"> + <entry>1</entry> + <entry>only-CM & multi-CM</entry> + </row> + <row rowsep="1"> + <entry>2</entry> + <entry>only-CM & multi-CM & Property-with-CM</entry> + </row> + <row rowsep="1"> + <entry>1</entry> + <entry>0</entry> + <entry>PropertyNotify</entry> + </row> + <row rowsep="0"> + <entry morerows="1">2</entry> + <entry>0</entry> + <entry>only-CM & PropertyNotify</entry> + </row> + <row> + <entry>1</entry> + <entry>only-CM & multi-CM & PropertyNotify</entry> + </row> + </tbody> + </tgroup> +</table> + +<literallayout class="monospaced"> +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 + +</literallayout> + + +<para> +The method to decide major/minor-transport-version is as follows: +</para> + +<itemizedlist> + <listitem> + <para> +The client sends 0 as major/minor-transport-version to the IM Server. +The client must support all methods in Table 4-3. <!-- xref --> +The client may send another number as major/minor-transport-version to +use other method than the above in the future. + </para> + </listitem> + <listitem> + <para> +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. + </para> + </listitem> + <listitem> + <para> +If major/minor-transport-version number is not available, it is regarded +as 0. + </para> + </listitem> +</itemizedlist> + +<para> +(*2) dividing size between ClientMessage and Property +</para> + +<para> +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. +</para> + +</sect3> + +<sect3 id="read_write_"> +<title>read/write </title> +<para> +The data is transferred via either ClientMessage or Window Property in +the X Window System. +</para> + +<sect4 id="Format_for_the_data_from_the_Client_to_the_IM_Server"> +<title>Format for the data from the Client to the IM Server</title> +<para> +<emphasis role="bold">ClientMessage</emphasis> +</para> + +<para> +If data is sent via ClientMessage event, the format is as follows: +</para> + +<table frame="none" id="clientmessage_events_format_first_or_middle"> + <title>The ClientMessage event's format (first or middle)</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>char</entry> + <entry>data.b[20]</entry> + <entry>(read/write DATA : 20 byte)</entry> + </row> + </tbody> + </tgroup> +</table> + + + +<table frame="none" id="clientmessage_events_format_only_or_last"> + <title>The ClientMessage event's format (only or last)</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>char</entry> + <entry>data.b[20]</entry> + <entry>(read/write DATA : MAX 20 byte) +<footnote><para>If the data is smaller +than 20 bytes, all data other than available data must be 0. +</para></footnote> + </entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +<emphasis role="bold">Property</emphasis> +</para> + +<para> +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. +</para> + +<itemizedlist> + <listitem> + <para> +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. + </para> + </listitem> + <listitem> + <para> +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. + </para> + </listitem> +</itemizedlist> + +<para> +The arguments of the XChangeProperty are as follows: +</para> + + +<table frame="none" id="xchangeproperty_events_format"> + <title>The XChangeProperty event's format</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Argument</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS communication window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>property</entry> + <entry>read/write property Atom (*1)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>mode</entry> + <entry>PropModeAppend</entry> + </row> + <row rowsep="0"> + <entry>u_char</entry> + <entry>*data</entry> + <entry>read/write DATA</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>nelements</entry> + <entry>length of DATA</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +(*1) The read/write property ATOM allocates the following strings by +<function>XInternAtom</function>. +"_clientXXX" +</para> + +<para> +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). +</para> + +<para> +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: +</para> + +<table frame="none" id="clientmessage_events_format_to_send_atom_of_property"> + <title>The ClientMessage event's format to send Atom of property</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[0]</entry> + <entry>length of read/write property Atom</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[1]</entry> + <entry>read/write property Atom</entry> + </row> + </tbody> + </tgroup> +</table> +</sect4> + +<sect4 id="Format_for_the_data_from_the_IM_Server_to_the_Client"> +<title>Format for the data from the IM Server to the Client</title> +<para> +<emphasis role="bold">ClientMessage</emphasis> +</para> + +<para> +The format of the ClientMessage is as follows: +</para> + +<table frame="none" id="clientmessage_events_format_first_or_middle_2"> + <title>The ClientMessage event's format (first or middle)</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>char</entry> + <entry>data.b[20]</entry> + <entry>(read/write DATA : 20 byte)</entry> + </row> + </tbody> + </tgroup> +</table> + + + + + +<table frame="none" id="clientmessage_events_format_only_or_last_2"> + <title>The ClientMessage event's format (only or last)</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>char</entry> + <entry>data.b[20]</entry> + <entry>(read/write DATA : MAX 20 byte) (*1)</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +(*1) If the data size is smaller than 20 bytes, all data other than available +data must be 0. +</para> + +<para> +<emphasis role="bold">Property</emphasis> +</para> + +<para> +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. +</para> + +<itemizedlist> + <listitem> + <para> +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via the +ClientMessage event. + </para> + </listitem> + <listitem> + <para> +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via +PropertyNotify event. + </para> + </listitem> +</itemizedlist> + +<para> +The arguments of the XChangeProperty are as follows: +</para> + +<table frame="none" id="xchangeproperty_events_format_b"> + <title>The XChangeProperty event's format</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Argument</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS communication window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>property</entry> + <entry>read/write property Atom (*1)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>mode</entry> + <entry>PropModeAppend</entry> + </row> + <row rowsep="0"> + <entry>u_char</entry> + <entry>*data</entry> + <entry>read/write DATA</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>nelements</entry> + <entry>length of DATA</entry> + </row> + </tbody> + </tgroup> +</table> + +<para> +(*1) The read/write property ATOM allocates some strings, which are not +allocated by the client, by <function>XInternAtom</function>. +</para> + +<para> +The IM Server changes the property with the mode of PropModeAppend and +the client reads it with the delete mode, i.e. (delete = True). +</para> + +<para> +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: +</para> + +<table frame="none" id="clientmessage_events_format_to_send_atom_of_property_2"> + <title>The ClientMessage event's format to send Atom of property</title> + <tgroup cols="3"> + <colspec colname="col1" colwidth="1*" colsep="0"/> + <colspec colname="col2" colwidth="1*" colsep="1"/> + <colspec colname="col3" colwidth="3.5*" colsep="0"/> + <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> + <thead> + <row> + <entry align="left" spanname="span-horiz">Structure Member</entry> + <entry align="left">Contents</entry> + </row> + </thead> + <tbody> + <row rowsep="0"> + <entry>int</entry> + <entry>type</entry> + <entry>ClientMessage</entry> + </row> + <row rowsep="0"> + <entry>u_long</entry> + <entry>serial</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Bool</entry> + <entry>send_event</entry> + <entry>Set by the X Window System</entry> + </row> + <row rowsep="0"> + <entry>Display</entry> + <entry>*display</entry> + <entry>The display to which connects</entry> + </row> + <row rowsep="0"> + <entry>Window</entry> + <entry>window</entry> + <entry>IMS Window ID</entry> + </row> + <row rowsep="0"> + <entry>Atom</entry> + <entry>message_type</entry> + <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> + </row> + <row rowsep="0"> + <entry>int</entry> + <entry>format</entry> + <entry>8</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[0]</entry> + <entry>length of read/write property Atom</entry> + </row> + <row rowsep="0"> + <entry>long</entry> + <entry>data.1[1]</entry> + <entry>read/write property Atom</entry> + </row> + </tbody> + </tgroup> +</table> + +</sect4> +</sect3> +<sect3 id="Closing_Connection"> +<title>Closing Connection</title> + +<para> +If the client disconnect with the IM Server, shutdown function should +free the communication window properties and etc.. +</para> + +</sect3> +</sect2> +</sect1> + +<sect1 id="References"> +<title>References</title> +<para> +[1] Masahiko Narita and Hideki Hiura, <emphasis remap='I'>"The Input Method Protocol"</emphasis> +</para> +</sect1> + +</chapter> +</book> |