From d2758df0a0091496717fe7a65c3e7563e7c82785 Mon Sep 17 00:00:00 2001 From: marha Date: Mon, 2 Aug 2010 08:29:58 +0000 Subject: xserver libX11 libXdmcp git update 2-8-2010 --- libX11/specs/i18n/Framework.ms | 1564 ----------------------- libX11/specs/i18n/LocaleDB.ms | 499 -------- libX11/specs/i18n/Makefile.am | 8 +- libX11/specs/i18n/Trans.ms | 1146 ----------------- libX11/specs/i18n/framework/Makefile.am | 32 + libX11/specs/i18n/framework/framework.svg | 703 ++++++++++ libX11/specs/i18n/framework/framework.xml | 1620 +++++++++++++++++++++++ libX11/specs/i18n/localedb/Makefile.am | 32 + libX11/specs/i18n/localedb/localedb.xml | 777 +++++++++++ libX11/specs/i18n/trans/Makefile.am | 32 + libX11/specs/i18n/trans/trans.xml | 1979 +++++++++++++++++++++++++++++ 11 files changed, 5177 insertions(+), 3215 deletions(-) delete mode 100644 libX11/specs/i18n/Framework.ms delete mode 100644 libX11/specs/i18n/LocaleDB.ms delete mode 100644 libX11/specs/i18n/Trans.ms create mode 100644 libX11/specs/i18n/framework/Makefile.am create mode 100644 libX11/specs/i18n/framework/framework.svg create mode 100644 libX11/specs/i18n/framework/framework.xml create mode 100644 libX11/specs/i18n/localedb/Makefile.am create mode 100644 libX11/specs/i18n/localedb/localedb.xml create mode 100644 libX11/specs/i18n/trans/Makefile.am create mode 100644 libX11/specs/i18n/trans/trans.xml (limited to 'libX11/specs/i18n') diff --git a/libX11/specs/i18n/Framework.ms b/libX11/specs/i18n/Framework.ms deleted file mode 100644 index 98a61f930..000000000 --- a/libX11/specs/i18n/Framework.ms +++ /dev/null @@ -1,1564 +0,0 @@ -.\" To print this out, type tbl macros.t ThisFile | troff -ms -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.ps 11 -.nr PS 11 -\& -.TL -\s+3\fBX11R6 Sample Implementation Frame Work\fP\s-3 -.sp 2 -.AU -Katsuhisa Yano -.AI -TOSHIBA Corporation -.AU -Yoshio Horiuchi -.AI -IBM Japan -.LP -.bp -.br -\& -.sp 15 -.ps 9 -.nr PS 9 -.LP -Copyright \(co 1994 by TOSHIBA Corporation -.br -Copyright \(co 1994 by IBM Corporation -.LP -Permission to use, copy, modify, and distribute this documentation -for any purpose and without fee is hereby granted, provided -that the above copyright notice and this permission notice appear -in all copies. -TOSHIBA Corporation and IBM Corporation make no representations about -the suitability for any purpose of the information in this document. -This documentation is provided as is without express or implied warranty. -.sp 5 -Copyright \(co 1994 X Consortium -.LP -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the ``Software''), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: -.LP -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. -.LP -THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN -AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -.LP -Except as contained in this notice, the name of the X Consortium shall not be -used in advertising or otherwise to promote the sale, use or other dealings -in this Software without prior written authorization from the X Consortium. -.sp 3 -\fIX Window System\fP is a trademark of The Open Group. -.ps 11 -.nr PS 11 -.bp 1 -.EH '\fBSample Implementation Frame Work\fP''\fB\*(xV\fP' -.OH '\fBSample Implementation Frame Work\fP''\fB\*(xV\fP' -.EF ''\fB % \fP'' -.OF ''\fB % \fP'' -.NH 1 -Preface -.XS \*(SN Preface -.XE -.LP -This document proposes to define the structures, methods and their -signatures that are expected to be common to all locale dependent -functions within the Xlib sample implementation. The following -illustration (Fig.1) is proposed to outline the separating of -the components within the sample implementation. -.LP -.\" figure start -.in +1c -\^... 0.237 5.796 5.24 10.14 -\^... 0.000i 4.344i 5.003i 0.000i -.nr 00 \n(.u -.nf -.PS 4.344i 5.003i -.br -.ps 11 -\h'1.753i'\v'2.130i'\v'-.13m'\L'-1.000i\(br'\v'.13m' -.sp -1 -\h'1.753i'\v'1.130i'\l'1.500i' -.sp -1 -\h'3.253i'\v'1.130i'\v'-.13m'\L'1.000i\(br'\v'.13m' -.sp -1 -\h'3.253i'\v'2.130i'\l'-1.500i' -.sp -1 -\h'1.751i'\v'1.628i'\l'1.499i' -.sp -1 -\h'2.500i'\v'1.128i'\v'-.13m'\L'0.500i\(br'\v'.13m' -.sp -1 -\h'1.875i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRInput\fP -.sp -1 -\h'1.875i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRMethod\fP -.sp -1 -\h'2.625i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fROutput\fP -.sp -1 -\h'2.625i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRMethod\fP -.sp -1 -\h'1.938i'\v'1.844i'\h'-0.0m'\v'0.2m'\s12\fR\fP -.sp -1 -\h'2.000i'\v'2.032i'\h'-0.0m'\v'0.2m'\s12\fRX Locale Object\fP -.sp -1 -\h'3.503i'\v'1.630i'\v'-.13m'\L'-0.500i\(br'\v'.13m' -.sp -1 -\h'3.503i'\v'1.130i'\l'1.500i' -.sp -1 -\h'5.003i'\v'1.130i'\v'-.13m'\L'0.500i\(br'\v'.13m' -.sp -1 -\h'5.003i'\v'1.630i'\l'-1.500i' -.sp -1 -\h'3.625i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRC Library\fP -.sp -1 -\h'4.250i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRANSI impl.\fP -.sp -1 -\h'0.003i'\v'1.630i'\v'-.13m'\L'-0.500i\(br'\v'.13m' -.sp -1 -\h'0.003i'\v'1.130i'\l'1.500i' -.sp -1 -\h'1.503i'\v'1.130i'\v'-.13m'\L'0.500i\(br'\v'.13m' -.sp -1 -\h'1.503i'\v'1.630i'\l'-1.500i' -.sp -1 -\h'0.125i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRLocale Library\fP -.sp -1 -\h'0.438i'\v'1.507i'\h'-0.0m'\v'0.2m'\s12\fRnon-AnSI impl.\fP -.sp -1 -\h'3.500i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<< ANSI/MSE API >>\fP -.sp -1 -\h'4.250i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Contrib)\fP'u/2u'\s12\fR(X Contrib)\fP\h'-\w'\s12\fR(X Contrib)\fP'u/2u' -.sp -1 -\h'0.125i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRXLC_XLOCALE\fP -.sp -1 -\h'0.125i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- MB_CUR_MAX\fP -.sp -1 -\h'0.125i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- codeset info\fP -.sp -1 -\h'0.125i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fRo char/charset\fP -.sp -1 -\h'0.125i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fRo conv/charset\fP -.sp -1 -\h'0.003i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m' -.sp -1 -\h'0.003i'\v'2.880i'\l'1.500i' -.sp -1 -\h'1.503i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m' -.sp -1 -\h'1.503i'\v'3.880i'\l'-1.500i' -.sp -1 -\h'1.875i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRXLC_FONTSET\fP -.sp -1 -\h'1.875i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- fonset info\fP -.sp -1 -\h'1.875i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- charset info\fP -.sp -1 -\h'1.875i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fR- font/charset\fP -.sp -1 -\h'1.875i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fR- XLFD, GL/GR\fP -.sp -1 -\h'1.753i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m' -.sp -1 -\h'1.753i'\v'2.880i'\l'1.500i' -.sp -1 -\h'3.253i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m' -.sp -1 -\h'3.253i'\v'3.880i'\l'-1.500i' -.sp -1 -\h'3.625i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- codeset info\fP -.sp -1 -\h'3.625i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fRo char/charset\fP -.sp -1 -\h'3.625i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fRo conv/charset\fP -.sp -1 -\h'3.625i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- MB_CUR_MAX\fP -.sp -1 -\h'3.625i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRlocaledef DB\fP -.sp -1 -\h'3.503i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m' -.sp -1 -\h'3.503i'\v'2.880i'\l'1.500i' -.sp -1 -\h'5.003i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m' -.sp -1 -\h'5.003i'\v'3.880i'\l'-1.500i' -.sp -1 -\h'0.753i'\v'0.250i'\D'l0.000i -0.250i' -.sp -1 -\h'0.753i'\l'3.500i' -.sp -1 -\h'4.253i'\D'l0.000i 0.250i' -.sp -1 -\h'4.253i'\v'0.250i'\l'-3.500i' -.sp -1 -\h'2.500i'\v'0.157i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRApplication\fP'u/2u'\s12\fRApplication\fP\h'-\w'\s12\fRApplication\fP'u/2u' -.sp -1 -\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<< ANSI/MSE API >>\fP -.sp -1 -\h'0.751i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Contrib)\fP'u/2u'\s12\fR(X Contrib)\fP\h'-\w'\s12\fR(X Contrib)\fP'u/2u' -.sp -1 -\h'2.500i'\v'2.128i'\v'-.13m'\L'0.749i\(br'\v'.13m' -.sp -1 -\h'2.475i'\v'2.777i'\D'l0.025i 0.100i' -.sp -1 -\h'2.525i'\v'2.777i'\D'l-0.025i 0.100i' -.sp -1 -\h'2.500i'\v'2.315i'\D'l-0.250i 0.187i' -.sp -1 -\h'2.250i'\v'2.502i'\l'-1.124i' -.sp -1 -\h'1.126i'\v'2.502i'\v'-.13m'\L'0.375i\(br'\v'.13m' -.sp -1 -\h'1.101i'\v'2.777i'\D'l0.025i 0.100i' -.sp -1 -\h'1.151i'\v'2.777i'\D'l-0.025i 0.100i' -.sp -1 -\h'2.500i'\v'2.315i'\D'l0.250i 0.187i' -.sp -1 -\h'2.750i'\v'2.502i'\l'1.125i' -.sp -1 -\h'3.875i'\v'2.502i'\v'-.13m'\L'0.375i\(br'\v'.13m' -.sp -1 -\h'3.850i'\v'2.777i'\D'l0.025i 0.100i' -.sp -1 -\h'3.900i'\v'2.777i'\D'l-0.025i 0.100i' -.sp -1 -\h'0.376i'\v'1.628i'\v'-.13m'\L'1.249i\(br'\v'.13m' -.sp -1 -\h'0.351i'\v'2.777i'\D'l0.025i 0.100i' -.sp -1 -\h'0.401i'\v'2.777i'\D'l-0.025i 0.100i' -.sp -1 -\h'4.625i'\v'1.628i'\v'-.13m'\L'1.249i\(br'\v'.13m' -.sp -1 -\h'4.600i'\v'2.777i'\D'l0.025i 0.100i' -.sp -1 -\h'4.650i'\v'2.777i'\D'l-0.025i 0.100i' -.sp -1 -\h'2.125i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' -.sp -1 -\h'2.100i'\v'0.528i'\D'l0.025i 0.100i' -.sp -1 -\h'2.150i'\v'0.528i'\D'l-0.025i 0.100i' -.sp -1 -\h'2.875i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' -.sp -1 -\h'2.850i'\v'0.528i'\D'l0.025i 0.100i' -.sp -1 -\h'2.900i'\v'0.528i'\D'l-0.025i 0.100i' -.sp -1 -\h'1.126i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' -.sp -1 -\h'1.101i'\v'0.528i'\D'l0.025i 0.100i' -.sp -1 -\h'1.151i'\v'0.528i'\D'l-0.025i 0.100i' -.sp -1 -\h'3.875i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m' -.sp -1 -\h'3.850i'\v'0.528i'\D'l0.025i 0.100i' -.sp -1 -\h'3.900i'\v'0.528i'\D'l-0.025i 0.100i' -.sp -1 -\v'4.002i'\D'l0.125i 0.125i' -.sp -1 -\h'0.125i'\v'4.127i'\l'3.000i' -.sp -1 -\h'3.125i'\v'4.127i'\D'l0.125i -0.125i' -.sp -1 -\h'3.500i'\v'4.002i'\D'l0.125i 0.125i' -.sp -1 -\h'3.625i'\v'4.127i'\l'1.250i' -.sp -1 -\h'4.875i'\v'4.127i'\D'l0.125i -0.125i' -.sp -1 -\h'1.626i'\v'4.344i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRXLocale Source (X Core)\fP'u/2u'\s12\fRXLocale Source (X Core)\fP\h'-\w'\s12\fRXLocale Source (X Core)\fP'u/2u' -.sp -1 -\h'4.250i'\v'4.344i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRSystem LOcale Source\fP'u/2u'\s12\fRSystem LOcale Source\fP\h'-\w'\s12\fRSystem LOcale Source\fP'u/2u' -.sp -1 -\h'2.500i'\v'0.782i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRXLib API\fP'u/2u'\s12\fRXLib API\fP\h'-\w'\s12\fRXLib API\fP'u/2u' -.sp -1 -\h'2.500i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Core)\fP'u/2u'\s12\fR(X Core)\fP\h'-\w'\s12\fR(X Core)\fP'u/2u' -.sp -1 -\h'1.751i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<<\fP -.sp -1 -\h'3.063i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR>>\fP -.sp -1 -.sp 1+4.344i -.in -1c -.PE -.if \n(00 .fi -.\" figure end -.LP -.ce -.sp 6p -Fig.1 : Frame Work of Locale Service API Proposal -.LP -Generally speaking, the internationalized portion of Xlib (Locale -Dependent X, LDX) consists of three objects; -locale (LC) , input method (IM) and output method (OM). -The LC provides a set of information that depends on user's language -environment. The IM manages text inputing, and the OM manages text -drawing. Both IM and OM highly depend on LC data. -.LP -In X11R5, there are two sample implementations, Ximp and Xsi, for -Xlib internationalization. But in both implementations, IM and OM -actually refer the private extension of LC. It breaks coexistence -of these two sample implementations. For example, if a user creates -a new OM for special purpose as a part of Ximp, it will not work with -Xsi. -.LP -As a solution of this problem, we propose to define the standard -APIs between these three objects, and define the structure that are -common to these objects. -.LP -.NH 1 -Objective -.XS \*(SN Objective -.XE -.LP -.IP \(bu -Explain the current X11R6 sample implementation -.IP \(bu -Document the common set of locale dependent interfaces -.IP \(bu -Provide more flexible pluggable layer -.LP -.NH 1 -Locale Object Binding Functions -.XS \*(SN Locale Object Binding Functions -.XE -.LP -This chapter describes functions related locale object binding for -implementing the pluggable layer. -.LP -A locale loader is an entry point for locale object, which -instantiates XLCd object and binds locale methods with specified -locale name. The behavior of loader is implementation dependent. -And, what kind of loaders are available is also implementation -dependent. -.LP -The loader is called in -.PN _XOpenLC, -but caller of -.PN _XOpenLC -does not need to care about its inside. For example, if the loader is -implemented with dynamic load functions, and the dynamic module is -expected to be unloaded when the corresponding XLCd is freed, -close methods of XLCdMethods should handle unloading. -.LP -.sp -\fBInitializing a locale loader list\fP -.LP -.FD 0 -void _XlcInitLoader() -.FN -The -.PN _XlcInitLoader -function initializes the locale loader list with vendor specific -manner. Each loader is registered with calling -.PN _XlcAddLoader. -The number of loaders and their order in the loader list is -implementation dependent. -.sp -.LP -\fBAdd a loader\fP -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef XLCd (*XLCdLoadProc)(\fIname\fP); - char \fI*name\fP; - -typedef int XlcPosition; -.De -.TS -lw(.5i) lw(2i) lw(2i). -T{ -#define -T} T{ -XlcHead -T} T{ - 0 -T} -T{ -#define -T} T{ -XlcTail -T} T{ --1 -T} -.TE -.LP -.FD 0 -Bool _XlcAddLoader(\fIproc, position\fP) -.br - XLCdLoadProc \fIproc\fP; -.br - XlcPosition \fIposition\fP; -.FN -.LP -The -.PN _XlcAddLoader -function registers the specified locale loader ``\fIproc\fP'' to the -internal loader list. The position specifies that the loader -``\fIproc\fP'' should be placed in the top of the loader list(XlcHead) -or last(XlcTail). -.LP -The object loader is called from the top of the loader list in order, -when calling time. -.sp -.LP -\fBRemove a loader\fP -.LP -.FD 0 -void _XlcRemoveLoader(\fIproc\fP) -.br - XLCdLoadProc \fIproc\fP; -.FN -.LP -The -.PN _XlcRemoveLoader -function removes the locale loader specified by ``\fIproc\fP'' from the -loader list. -.LP -Current implementation provides following locale loaders; -.DS -.PN _XlcDefaultLoader -.PN _XlcGenericLoader -.PN _XlcEucLoader -.PN _XlcSjisLoader -.PN _XlcUtfLoader -.PN _XaixOsDynamicLoad -.DE -.LP -.NH 1 -Locale Method Interface -.XS \*(SN Locale Method Interface -.XE -.LP -This chapter describes the locale method API, which is a set of -accessible functions from both IM and OM parts. -The locale method API provides the functionalities; obtaining locale -dependent information, handling charset, converting text, etc. -.LP -As a result of using these APIs instead of accessing vender private -extension of the locale object, we can keep locale, IM and OM -independently each other. -.LP -.NH 1 -Locale Method Functions -.XS \*(SN Locale Method Functions -.XE -.LP -\fBOpen a Locale Method\fP -.LP -.FD 0 -XLCd _XOpenLC(\fIname\fP) -.br - char \fI*name\fP; -.FN -.LP -The -.PN _XOpenLC -function opens a locale method which corresponds to the -specified locale name. -.PN _XOpenLC -calls a locale object loader, which is registered via -.PN _XlcAddLoader into the internal loader list. If the called loader -is valid and successfully opens a locale, -.PN _XOpenLC -returns the XLCd. If the loader is invalid or failed to open a locale, -.PN _XOpenLC -calls the next loader. If all registered loaders cannot open a locale, -.PN _XOpenLC -returns NULL. -.LP -.FD 0 -XLCd _XlcCurrentLC() -.FN -.LP -The -.PN _XlcCurrentLC -function returns an XLCd that are bound to current locale. -.sp -.LP -\fBClose a Locale Method\fP -.LP -.FD 0 -void _XCloseLC(\fIlcd\fP) -.br - XLCd \fIlcd\fP; -.FN -.LP -The -.PN _XCloseLC -function close a locale method the specified lcd. -.sp -.LP -\fBObtain Locale Method values\fP -.LP -.FD 0 -char * _XGetLCValues(\fIlcd\fP, ...) -.br - XLCd \fIlcd\fP; -.FN -.LP -The -.PN _XGetLCValues -function returns NULL if no error occurred; otherwise, it returns the -name of the first argument that could not be obtained. -The following values are defined as standard arguments. Other values -are implementation dependent. -.LP -.TS H -tab(:); -l l l. -_ -.sp 6p -.B -Name:Type:Description -.sp 6p -_ -.sp 6p -.TH -.R -XlcNCodeset:char*:codeset part of locale name -XlcNDefaultString:char*:XDefaultString() -XlcNEncodingName:char*:encoding name -XlcNLanguage:char*:language part of locale name -XlcNMbCurMax:int:ANSI C MB_CUR_MAX -XlcNStateDependentEncoding:Bool:is state-dependent encoding or not -XlcNTerritory:char*:territory part of locale name -.sp 6p -_ -.TE -.LP -.NH 1 -Charset functions -.XS \*(SN -Charset functions -.XE -.LP -The XlcCharSet is an identifier which represents a subset of characters -(character set) in the locale object. -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef enum { - XlcUnknown, XlcC0, XlcGL, XlcC1, XlcGR, XlcGLGR, XlcOther -} XlcSide; - -typedef struct _XlcCharSetRec *XlcCharSet; - -typedef struct { - char *name; - XPointer value; -} XlcArg, *XlcArgList; - -typedef char* (*XlcGetCSValuesProc)(\fIcharset\fP, \fIargs\fP, \fInum_args\fP); - XlcCharSet \fIcharset\fP; - XlcArgList \fIargs\fP; - int \fInum_args\fP; - -typedef struct _XlcCharSetRec { - char *name; - XrmQuark xrm_name; - char *encoding_name; - XrmQuark xrm_encoding_name; - XlcSide side; - int char_size; - int set_size; - char *ct_sequence; - XlcGetCSValuesProc get_values; -} XlcCharSetRec; -.De -.sp -.LP -\fBGet an XlcCharSet\fP -.LP -.FD 0 -XlcCharSet _XlcGetCharSet(\fIname\fP) -.br - char \fI*name\fP; -.FN -.LP -The -.PN _XlcGetCharSet -function gets an XlcCharSet which corresponds to the charset name -specified by ``\fIname\fP''. -.PN _XlcGetCharSet -returns NULL, if no XlcCharSet bound to specified ``\fIname\fP''. -.LP -The following character sets are pre-registered. -.LP -.TS H -tab(@); -l l. -_ -.sp 6p -.B -Name@Description -.sp 6p -_ -.sp 6p -.TH -.R -ISO8859-1:GL@7-bit ASCII graphics (ANSI X3.4-1968), -@Left half of ISO 8859 sets -JISX0201.1976-0:GL@Left half of JIS X0201-1976 (reaffirmed 1984), -@8-Bit Alphanumeric-Katakana Code -.sp -ISO8859-1:GR@Right half of ISO 8859-1, Latin alphabet No. 1 -ISO8859-2:GR@Right half of ISO 8859-2, Latin alphabet No. 2 -ISO8859-3:GR@Right half of ISO 8859-3, Latin alphabet No. 3 -ISO8859-4:GR@Right half of ISO 8859-4, Latin alphabet No. 4 -ISO8859-7:GR@Right half of ISO 8859-7, Latin/Greek alphabet -ISO8859-6:GR@Right half of ISO 8859-6, Latin/Arabic alphabet -ISO8859-8:GR@Right half of ISO 8859-8, Latin/Hebrew alphabet -ISO8859-5:GR@Right half of ISO 8859-5, Latin/Cyrillic alphabet -ISO8859-9:GR@Right half of ISO 8859-9, Latin alphabet No. 5 -JISX0201.1976-0:GR@Right half of JIS X0201-1976 (reaffirmed 1984), -@8-Bit Alphanumeric-Katakana Code -.sp -GB2312.1980-0:GL@GB2312-1980, China (PRC) Hanzi defined as GL -GB2312.1980-0:GR@GB2312-1980, China (PRC) Hanzi defined as GR -JISX0208.1983-0:GL@JIS X0208-1983, Japanese Graphic Character Set -@defined as GL -JISX0208.1983-0:GR@JIS X0208-1983, Japanese Graphic Character Set -@defined as GR -KSC5601.1987-0:GL@KS C5601-1987, Korean Graphic Character Set -@defined as GL -KSC5601.1987-0:GR@KS C5601-1987, Korean Graphic Character Set -@defined as GR -JISX0212.1990-0:GL@JIS X0212-1990, Japanese Graphic Character Set -@defined as GL -JISX0212.1990-0:GR@JIS X0212-1990, Japanese Graphic Character Set -@defined as GR -.\" CNS11643.1986-0:GL -.\" CNS11643.1986-1:GL -.\" TIS620-0:GR -.sp 6p -_ -.TE -.LP -.sp -\fBAdd an XlcCharSet\fP -.LP -.FD 0 -Bool _XlcAddCharSet(\fIcharset\fP) - XlcCharSet \fIcharset\fP; -.FN -.LP -The -.PN _XlcAddCharSet -function registers XlcCharSet specified by ``\fIcharset\fP''. -.LP -.sp -\fBObtain Character Set values\fP -.LP -.FD 0 -char * _XlcGetCSValues(\fIcharset\fP, ...) -.br - XlcCharSet \fIcharset\fP; -.FN -.LP -The -.PN _XlcGetCSValues -function returns NULL if no error occurred; -otherwise, it returns the name of the first argument that could not -be obtained. The following values are defined as standard arguments. -Other values are implementation dependent. -.LP -.TS H -tab(:); -l l l. -_ -.sp 6p -.B -Name:Type:Description -.sp 6p -_ -.sp 6p -.TH -.R -XlcNName:char*:charset name -XlcNEncodingName:char*:XLFD CharSet Registry and Encoding -XlcNSide:XlcSide:charset side (GL, GR, ...) -XlcNCharSize:int:number of octets per character -XlcNSetSize:int:number of character sets -XlcNControlSequence:char*:control sequence of Compound Text -.sp 6p -_ -.TE -.LP -.NH 1 -Converter Functions -.XS \*(SN Converter Functions -.XE -.LP -We provide a set of the common converter APIs, that are independent -from both of source and destination text type. -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XlcConvRec *XlcConv; - -typedef void (*XlcCloseConverterProc)(\fIconv\fP); - XlcConv \fIconv\fP; - -typedef int (*XlcConvertProc)(\fIconv\fP, \fIfrom\fP, \fIfrom_left\fP, \fIto\fP, \fIto_left\fP, \fIargs\fP, \fInum_args\fP); - XlcConv \fIconv\fP; - XPointer \fI*from\fP; - int \fI*from_left\fP; - XPointer \fI*to\fP; - int \fI*to_left\fP; - XPointer \fI*args\fP; - int \fInum_args\fP; - -typedef void (*XlcResetConverterProc)(\fIconv\fP); - XlcConv \fIconv\fP; - -typedef struct _XlcConvMethodsRec { - XlcCloseConverterProc close; - XlcConvertProc convert; - XlcResetConverterProc reset; -} XlcConvMethodsRec, *XlcConvMethods; - -typedef struct _XlcConvRec { - XlcConvMethods methods; - XPointer state; -} XlcConvRec; -.De -.LP -.sp -\fBOpen a converter\fP -.LP -.FD 0 -XlcConv _XlcOpenConverter(\fIfrom_lcd\fP, \fIfrom_type\fP, \fIto_lcd\fP, \fIto_type\fP) -.br - XLCd \fIfrom_lcd\fP; -.br - char \fI*from_type\fP; -.br - XLCd \fIto_lcd\fP; -.br - char \fI*to_type\fP; -.FN -.LP -.PN _XlcOpenConverter -function opens the converter which converts a text from specified -``\fIfrom_type\fP'' to specified ``\fIto_type\fP'' encoding. If the -function cannot find proper converter or cannot open a corresponding -converter, it returns NULL. Otherwise, it returns the conversion -descriptor. -.LP -The following types are pre-defined. Other types are implementation -dependent. -.LP -.TS H -tab(:); -l l l l. -_ -.sp 6p -.B -Name:Type:Description:Arguments -.sp 6p -_ -.sp 6p -.TH -.R -XlcNMultiByte:char *:multibyte:- -XlcNWideChar:wchar_t *:wide character:- -XlcNCompoundText:char *:COMPOUND_TEXT:- -XlcNString:char *:STRING:- -XlcNCharSet:char *:per charset:XlcCharSet -XlcNChar:char *:per character:XlcCharSet -.sp 6p -_ -.TE -.LP -.sp -\fBClose a converter\fP -.LP -.FD 0 -void _XlcCloseConverter(\fIconv\fP) -.br - XlcConv \fIconv\fP; -.FN -.LP -The -.PN _XlcCloseConverter -function closes the specified converter ``\fIconv\fP''. -.LP -.sp -\fBCode conversion\fP -.LP -.FD 0 -int _XlcConvert(\fIconv\fP, \fIfrom\fP, \fIfrom_left\fP, \fIto\fP, \fIto_left\fP, \fIargs\fP, \fInum_args\fP) -.br - XlcConv \fIconv\fP; -.br - XPointer \fI*from\fP; -.br - int \fI*from_left\fP; -.br - XPointer \fI*to\fP; -.br - int \fI*to_left\fP; -.br - XPointer \fI*args\fP; -.br - int \fInum_args\fP; -.FN -.LP -The -.PN _XlcConvert -function converts a sequence of characters from one type, in the array -specified by ``\fIfrom\fP'', into a sequence of corresponding characters -in another type, in the array specified by ``\fIto\fP''. The types are -those specified in the -.PN _XlcOpenConverter() -call that returned the conversion descriptor, ``\fIconv\fP''. -The arguments ``\fIfrom\fP'', ``\fIfrom_left\fP'', ``\fIto\fP'' and -``\fIto_left\fP'' have the same specification of XPG4 iconv function. -.LP -For state-dependent encodings, the conversion descriptor ``\fIconv\fP'' -is placed into its initial shift state by a call for which ``\fIfrom\fP'' -is a NULL pointer, or for which ``\fIfrom\fP'' points to a null pointer. -.LP -The following 2 converters prepared by locale returns appropriate -charset (XlcCharSet) in an area pointed by args[0]. -.LP -.TS -tab(:); -l l l. -_ -.sp 6p -.B -From:To:Description -.sp 6p -_ -.sp 6p -.R -XlcNMultiByte:XlcNCharSet:Segmentation (Decomposing) -XlcNWideChar:XlcNCharSet:Segmentation (Decomposing) -.sp 6p -_ -.TE -.LP -The conversion, from XlcNMultiByte/XlcNWideChar to XlcNCharSet, -extracts a segment which has same charset encoding characters. -More than one segment cannot be converted in a call. -.LP -.sp -\fBReset a converter\fP -.LP -.FD 0 -void _XlcResetConverter(\fIconv\fP) -.br - XlcConv \fIconv\fP; -.FN -.LP -The -.PN _XlcResetConverter -function reset the specified converter ``\fIconv\fP''. -.LP -.sp -\fBRegister a converter\fP -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef XlcConv (*XlcOpenConverterProc)(\fIfrom_lcd\fP, \fIfrom_type\fP, \fIto_lcd\fP, \fIto_type\fP); - XLCd \fIfrom_lcd\fP; - char \fI*from_type\fP; - XLCd \fIto_lcd\fP; - char \fI*to_type\fP; -.De -.LP -.FD 0 -Bool _XlcSetConverter(\fIfrom_lcd\fP, \fIfrom\fP, \fIto_lcd\fP, \fIto\fP, \fIconverter\fP) -.br - XLCd \fIfrom_lcd\fP; -.br - char \fI*from\fP; -.br - XLCd \fIto_lcd\fP; -.br - char \fI*to\fP; -.br - XlcOpenConverterProc \fIconverter\fP; -.FN -.LP -The \fBXlcSetConverter\fP function registers a converter which convert -from ``\fIfrom_type\fP'' to ``\fIto_type\fP'' into the converter list -(in the specified XLCd). -.LP -.NH 1 -X Locale Database functions -.XS \*(SN X Locale Database functions -.XE -.LP -X Locale Database contains the subset of user's environment that -depends on language. The following APIs are provided for accessing -X Locale Database and other locale relative files. -.LP -For more detail about X Locale Database, please refer -X Locale Database Definition document. -.LP -.sp -\fBGet a resource from database\fP -.LP -.FD 0 -void _XlcGetResource(\fIlcd\fP, \fIcategory\fP, \fIclass\fP, \fIvalue\fP, \fIcount\fP) -.br - XLCd \fIlcd\fP; -.br - char \fI*category\fP; -.br - char \fI*class\fP; -.br - char \fI***value\fP; -.br - int \fI*count\fP; -.FN -.LP -The -.PN _XlcGetResource -function obtains a locale dependent data which is associated with the -locale of specified ``\fIlcd\fP''. -The locale data is provided by system locale or by X Locale Database -file, and what kind of data is available is implementation dependent. -.LP -The specified ``\fIcategory\fP'' and ``\fIclass\fP'' are used for -finding out the objective locale data. -.LP -The returned value is returned in value argument in string list form, -and the returned count shows the number of strings in the value. -.LP -The returned value is owned by locale method, and should not be modified -or freed by caller. -.LP -.sp -\fBGet a locale relative file name\fP -.LP -.FD 0 -char * _XlcFileName(\fIlcd\fP, \fIcategory\fP) -.br - XLCd \fIlcd\fP; -.br - char \fI*category\fP; -.FN -.LP -The -.PN _XlcFileName -functions returns a file name which is bound to the specified ``\fIlcd\fP'' -and ``\fIcategory\fP'', as a null-terminated string. If no file name can -be found, or there is no readable file for the found file name, -.PN _XlcFileName -returns NULL. The returned file name should be freed by caller. -.LP -The rule for searching a file name is implementation dependent. -In current implementation, -.PN _XlcFileName -uses ``{category}.dir'' file as mapping table, which has pairs of -strings, a full locale name and a corresponding file name. -.LP -.NH 1 -Utility Functions -.XS \*(SN Utility Functions -.XE -.LP -\fBCompare Latin-1 strings\fP -.LP -.FD 0 -int _XlcCompareISOLatin1(\fIstr1\fP, \fIstr2\fP) -.br - char \fI*str1\fP, \fI*str2\fP; -.FN -.FD 0 -int _XlcNCompareISOLatin1(\fIstr1\fP, \fIstr2\fP, \fIlen\fP) -.br - char \fI*str1\fP, \fI*str2\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _XlcCompareIsoLatin1 -function to compares two ISO-8859-1 strings. Bytes representing ASCII lower -case letters are converted to upper case before making the comparison. -The value returned is an integer less than, equal to, or greater than -zero, depending on whether ``\fIstr1\fP'' is lexicographicly less than, -equal to, or greater than ``\fIstr2\fP''. -.LP -The -.PN _XlcNCompareIsoLatin1 -function is identical to -.PN _XlcCompareISOLatin1, -except that at most ``\fIlen\fP'' bytes are compared. -.LP -.sp -\fBResource Utility\fP -.LP -.FD 0 -int XlcNumber(\fIarray\fP) - ArrayType \fIarray\fP; -.FN -.LP -Similar to XtNumber. -.LP -.FD 0 -void _XlcCopyFromArg(\fIsrc\fP, \fIdst\fP, \fIsize\fP) -.br - char \fI*src\fP; -.br - char \fI*dst\fP; -.br - int \fIsize\fP; -.FN -.FD 0 -void _XlcCopyToArg(\fIsrc\fP, \fIdst\fP, \fIsize\fP) -.br - char \fI*src\fP; -.br - char \fI**dst\fP; -.br - int \fIsize\fP; -.FN -.LP -Similar to -.PN _XtCopyFromArg -and -.PN _XtCopyToArg. -.LP -.FD 0 -void _XlcCountVaList(\fIvar\fP, \fIcount_ret\fP) -.br - va_list \fIvar\fP; -.br - int \fI*count_ret\fP; -.FN -.LP -Similar to -.PN _XtCountVaList. -.LP -.FD 0 -void _XlcVaToArgList(\fIvar\fP, \fIcount\fP, \fIargs_ret\fP) -.br - va_list \fIvar\fP; -.br - int \fIcount\fP; -.br - XlcArgList \fI*args_ret\fP; -.FN -.LP -Similar to -.PN _XtVaToArgList. -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct _XlcResource { - char *name; - XrmQuark xrm_name; - int size; - int offset; - unsigned long mask; -} XlcResource, *XlcResourceList; -.De -.LP -.TS -lw(.5i) lw(2i) lw(2i). -T{ -#define -T} T{ -XlcCreateMask -T} T{ -(1L<<0) -T} -T{ -#define -T} T{ -XlcDefaultMask -T} T{ -(1L<<1) -T} -T{ -#define -T} T{ -XlcGetMask -T} T{ -(1L<<2) -T} -T{ -#define -T} T{ -XlcSetMask -T} T{ -(1L<<3) -T} -T{ -#define -T} T{ -XlcIgnoreMask -T} T{ -(1L<<4) -T} -.TE -.LP -.FD 0 -void _XlcCompileResourceList(\fIresources\fP, \fInum_resources\fP) -.br - XlcResourceList \fIresources\fP; -.br - int \fInum_resources\fP; -.FN -.LP -Similar to -.PN _XtCompileResourceList. -.LP -.FD 0 -char * _XlcGetValues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP, \fImask\fP) -.br - XPointer \fIbase\fP; -.br - XlcResourceList \fIresources\fP; -.br - int \fInum_resources\fP; -.br - XlcArgList \fIargs\fP; -.br - int \fInum_args\fP; -.br - unsigned long \fImask\fP; -.FN -.LP -Similar to XtGetSubvalues. -.LP -.FD 0 -char * _XlcSetValues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP, \fImask\fP) -.br - XPointer \fIbase\fP; -.br - XlcResourceList \fIresources\fP; -.br - int \fInum_resources\fP; -.br - XlcArgList \fIargs\fP; -.br - int \fInum_args\fP; -.br - unsigned long \fImask\fP; -.FN -.LP -Similar to XtSetSubvalues. -.LP -.sp -\fBANSI C Compatible Functions\fP -.LP -The following are ANSI C/MSE Compatible Functions for non-ANSI C environment. -.LP -.FD 0 -int _Xmblen(\fIstr\fP, \fIlen\fP) -.br - char \fI*str\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xmblen -function returns the number of characters pointed to by ``\fIstr\fP''. -Only ``\fIlen\fP'' bytes in ``\fIstr\fP'' are used in determining the -character count returned. ``\fIStr\fP'' may point at characters from -any valid codeset in the current locale. -.LP -The call -.PN _Xmblen -is equivalent to -.RS -_Xmbtowc(_Xmbtowc((\fIwchar_t*\fP)NULL, \fIstr\fP, \fIlen\fP)) -.RE -.LP -.FD 0 -int _Xmbtowc(\fIwstr\fP, \fIstr\fP, \fIlen\fP) -.br - wchar_t \fI*wstr\fP; -.br - char \fI*str\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xmbtowc -function converts the character(s) pointed to by ``\fIstr\fP'' -to their wide character representation(s) pointed to by ``\fIwstr\fP''. -``\fILen\fP'' is the number of bytes in ``\fIstr\fP'' to be converted. -The return value is the number of characters converted. -.LP -The call -.PN _Xmbtowc -is equivalent to -.RS -_Xlcmbtowc((XLCd)NULL, \fIwstr\fP, \fIstr\fP, \fIlen\fP) -.RE -.LP -.FD 0 -int _Xlcmbtowc(\fIlcd\fP, \fIwstr\fP, \fIstr\fP, \fIlen\fP) -.br - XLCd \fIlcd\fP; -.br - wchar_t \fI*wstr\fP; -.br - char \fI*str\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xlcmbtowc -function is identical to -.PN _Xmbtowc, -except that it requires the ``\fIlcd\fP'' argument. If ``\fIlcd\fP'' -is (XLCd) NULL, -.PN _Xlcmbtowc, -calls -.PN _XlcCurrentLC -to determine the current locale. -.LP -.FD 0 -int _Xwctomb(\fIstr\fP, \fIwc\fP) -.br - char \fI*str\fP; -.br - wchar_t \fIwc\fP; -.FN -.LP -The -.PN _Xwctomb -function converts a single wide character pointed to by ``\fIwc\fP'' to -its multibyte representation pointed to by ``\fIstr\fP''. -On success, the return value is 1. -.LP -The call -.PN _Xwctomb -is equivalent to -.RS -_Xlcwctomb((XLCd)NULL, \fIstr\fP, \fIwstr\fP) -.RE -.LP -.FD 0 -int _Xlcwctomb(\fIlcd\fP, \fIstr\fP, \fIwc\fP) -.br - XLCd \fIlcd\fP; -.br - char \fI*str\fP; -.br - wchar_t \fIwc\fP; -.FN -.LP -The -.PN _Xlcwctomb -function is identical to _Xwctomb, except that it requires the -``\fIlcd\fP'' argument. If ``\fIlcd\fP'' is (XLCd) NULL, -.PN _Xlcwctomb, -calls -.PN _XlcCurrentLC -to determine the current locale. -.LP -.FD 0 -int _Xmbstowcs(\fIwstr\fP, \fIstr\fP, \fIlen\fP) -.br - wchar_t \fI*wstr\fP; -.br - char \fI*str\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xmbstowcs -function converts the NULL-terminated string pointed to by ``\fIstr\fP'' -to its wide character string representation pointed to by ``\fIwstr\fP''. -``\fILen\fP'' is the number of characters in ``\fIstr\fP'' to be converted. -.LP -The call -.PN _Xmbstowcs -is equivalent to -.RS -_Xlcmbstowcs((XLCd)NULL, \fIwstr\fP, \fIstr\fP, \fIlen\fP) -.RE -.LP -.FD 0 -int _Xlcmbstowcs(\fIlcd\fP, \fIwstr\fP, \fIstr\fP, \fIlen\fP) -.br - XLCd \fIlcd\fP; -.br - wchar_t \fI*wstr\fP; -.br - char \fI*str\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xlcmbstowcs -function is identical to _Xmbstowcs, except that it requires the -``\fIlcd\fP'' argument. If ``\fIlcd\fP'' is (XLCd) NULL, -.PN _Xlcmbstowcs, -calls -.PN _XlcCurrentLC -to determine the current locale. -.LP -.FD 0 -int _Xwcstombs(\fIstr\fP, \fIwstr\fP, \fIlen\fP) -.br - char \fI*str\fP; -.br - wchar_t \fI*wstr\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xwcstombs -function converts the (wchar_t) NULL terminated wide character string -pointed to by ``\fIwstr\fP'' to the NULL terminated multibyte string -pointed to by ``\fIstr\fP''. -.LP -The call -.PN _Xwcstombs -is equivalent to -.RS -_Xlcwcstombs((XLCd)NULL, \fIstr\fP, \fIwstr\fP, \fIlen\fP) -.RE -.LP -.FD 0 -int _Xlcwcstombs(\fIlcd\fP, \fIstr\fP, \fIwstr\fP, \fIlen\fP) -.br - XLCd \fIlcd\fP; -.br - char \fI*str\fP; -.br - wchar_t \fI*wstr\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xlcwcstombs -function is identical to _Xwcstombs, except that it requires the -``\fIlcd\fP'' argument. If ``\fIlcd\fP'' is (XLCd) NULL, -.PN _Xlcwcstombs, -calls -.PN _XlcCurrentLC -to determine the current locale. -.LP -.FD 0 -int _Xwcslen(\fIwstr\fP) -.br - wchar_t \fI*wstr\fP; -.FN -.LP -The -.PN _Xwcslen -function returns the count of wide characters in the (wchar_t) NULL -terminated wide character string pointed to by ``\fIwstr\fP''. -.LP -.FD 0 -wchar_t * _Xwcscpy(\fIwstr1\fP, \fIwstr2\fP) -.br - wchar_t \fI*wstr1\fP, \fI*wstr2\fP; -.FN -.FD 0 -wchar_t * _Xwcsncpy(\fIwstr1\fP, \fIwstr2\fP, \fIlen\fP) -.br - wchar_t \fI*wstr1\fP, \fI*wstr2\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xwcscpy -function copies the (wchar_t) NULL terminated wide character string -pointed to by ``\fIwstr2\fP'' to the object pointed at by ``\fIwstr1\fP''. -``\fIWstr1\fP'' is (wchar_t) NULL terminated. The return value is a -pointer to ``\fIwstr1\fP''. -.LP -The -.PN _Xwcsncpy -function is identical to -.PN _Xwcscpy, -except that it copies ``\fIlen\fP'' wide characters from the object -pointed to by ``\fIwstr2\fP'' to the object pointed to ``\fIwstr1\fP''. -.LP -.FD 0 -int _Xwcscmp(\fIwstr1\fP, \fIwstr2\fP) -.br - wchar_t \fI*wstr1\fP, \fI*wstr2\fP; -.FN -.FD 0 -int _Xwcsncmp(\fIwstr1\fP, \fIwstr2\fP, \fIlen\fP) -.br - wchar_t \fI*wstr1\fP, \fI*wstr2\fP; -.br - int \fIlen\fP; -.FN -.LP -The -.PN _Xwcscmp -function compares two (wchar_t) NULL terminated wide character strings. -The value returned is an integer less than, equal to, or greater than zero, -depending on whether ``\fIwstr1\fP'' is lexicographicly less then, equal to, -or greater than ``\fIstr2\fP''. -.LP -The -.PN _Xwcsncmp -function is identical to -.PN _XlcCompareISOLatin1, -except that at most ``\fIlen\fP'' wide characters are compared. -.sp -.\" -------------------------------------------------------------------- -.\" .LP -.\" \fBLocale Method Internal Functions\fP -.\" .LP -.\" .FD 0 -.\" XlcCharSet _XlcCreateDefaultCharSet(\fIname\fP, \fIct_sequence\fP) -.\" .br -.\" char \fI*name\fP; -.\" .br -.\" char \fI*ct_sequence\fP; -.\" .FN -.\" .FD 0 -.\" Bool _XlcParseCharSet(\fIcharset\fP) -.\" .br -.\" XlcCharSet \fIcharset\fP; -.\" .FN -.\" .FD 0 -.\" void _XlcGetLocaleDataBase(\fIlcd\fP, \fIcategory\fP, \fIname\fP, \fIvalue\fP, \fIcount\fP) -.\" .br -.\" XLCd \fIlcd\fP; -.\" .br -.\" char \fI*category\fP; -.\" .br -.\" char \fI*name\fP; -.\" .br -.\" char \fI***value\fP; -.\" .br -.\" int \fI*count\fP; -.\" .FN -.\" .FD 0 -.\" void _XlcDestroyLocaleDataBase(\fIlcd\fP) -.\" .br -.\" XLCd \fIlcd\fP; -.\" .FN -.\" .FD 0 -.\" XPointer _XlcCreateLocaleDataBase(\fIlcd\fP) -.\" .br -.\" XLCd \fIlcd\fP; -.\" .FN -.\" .LP -.\" .sp -.\" \fBObtain an locale database path\fP -.\" .LP -.\" .FD 0 -.\" int _XlcResolveI18NPath(\fIdir\fP) -.\" .br -.\" char \fI*dir\fP; -.\" .FN -.\" .LP -.\" The -.\" .PN _XlcResolveI18NPath -.\" function returns path name list that is related to X Locale Database. -.\" The obtained path is stored into the array which is pointed by -.\" specified ``\fIdir\fP''. The path consists of directory paths which -.\" are separated with colon. -.\" If the environment variable XLOCALEDIR is specified, the path -.\" contains its contents. -.\" .LP -.\" The default path of X Locale Database is implementation dependent. -.\" In current implementation, it's determined in build time. -.\" .LP -.\" .PN _XlcResolveI18NPath -.\" does not check overflow of the array to which the ``\fIdir\fP'' -.\" parameter points. Caller should provide enough buffer to store this -.\" string. -.\" .LP -.\" .sp -.\" \fBObtain a full locale name\fP -.\" .LP -.\" .FD 0 -.\" int _XlcResolveLocaleName(\fIlc_name\fP, \fIfull_name\fP, \fIlanguage\fP, \fIterritory\fP, \fIcodeset\fP) -.\" .br -.\" char \fI*lc_name\fP; -.\" .br -.\" char \fI*full_name\fP; -.\" .br -.\" char \fI*language\fP; -.\" .br -.\" char \fI*territory\fP; -.\" .br -.\" char \fI*codeset\fP; -.\" .FN -.\" .LP -.\" The -.\" .PN _XlcResolveLocaleName -.\" function returns a full locale name. -.\" The obtained full locale name is stored into the array which is -.\" pointed by specified ``\fIfull_name\fP''. -.\" The language, territory and codeset part of the full locale name -.\" are copied to the return arguments, ``\fIlanguage\fP'', -.\" ``\fIterritory\fP'' and ``\fIcodeset\fP'', respectively. -.\" NULL can be specified for these arguments. -.\" .LP -.\" The rule for mapping from locale name to full locale name is -.\" implementation dependent. -.\" .LP -.\" .PN _XlcResolveLocaleName -.\" does not check overflow of the array to which -.\" ``\fIfull_name\fP'', ``\fIlanguage\fP'', ``\fIterritory\fP'' and -.\" ``\fIcodeset\fP'' parameter point. -.\" Caller should provide enough buffer to store those string. -.\" .LP -.\" In current implementation, -.\" .PN _XlcResolveLocaleName -.\" uses locale.alias file as mapping table, which has pairs of strings, -.\" a locale name and a full locale name. -.\" .LP -.\" .FD 0 -.\" int _XlcResolveDBName(\fIlc_name\fP, \fIfile_name\fP) -.\" .br -.\" char \fI*lc_name\fP; -.\" .br -.\" char \fI*file_name\fP; -.\" .FN -.\" .FD 0 -.\" XLCd _XlcCreateLC(\fIname\fP, \fImethods\fP) -.\" .br -.\" char \fI*name\fP; -.\" .br -.\" XLCdMethods \fImethods\fP; -.\" .FN -.\" .FD 0 -.\" void _XlcDestroyLC(\fIlcd\fP) -.\" .br -.\" XLCd \fIlcd\fP; -.\" .FN -.\" .LP -.\" - diff --git a/libX11/specs/i18n/LocaleDB.ms b/libX11/specs/i18n/LocaleDB.ms deleted file mode 100644 index 4592879d1..000000000 --- a/libX11/specs/i18n/LocaleDB.ms +++ /dev/null @@ -1,499 +0,0 @@ -.\" To print this out, type tbl macros.t ThisFile | troff -ms -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.ps 11 -.nr PS 11 -\& -.TL -\s+3\fBX Locale Database Definition\fP\s-3 -.sp 2 -.AU -Yoshio Horiuchi -.AI -IBM Japan -.LP -.bp -.br -\& -.ps 9 -.nr PS 9 -.sp 2 -.LP -Copyright \(co IBM Corporation 1994 -.LP -All Rights Reserved -.LP -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. -.LP -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. -.sp 5 -Copyright \(co 1994 X Consortium -.LP -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the ``Software''), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: -.LP -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. -.LP -THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN -AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -.LP -Except as contained in this notice, the name of the X Consortium shall not be -used in advertising or otherwise to promote the sale, use or other dealings -in this Software without prior written authorization from the X Consortium. -.sp 3 -\fIX Window System\fP is a trademark of The Open Group. -.LP -.bp 1 -.ps 11 -.nr PS 11 -.EH '\fBX Locale Database Definition\fP''\fB\*(xV\fP' -.OH '\fBX Locale Database Definition\fP''\fB\*(xV\fP' -.EF ''\fB % \fP'' -.OF ''\fB % \fP'' -.NH 1 -General -.XS -\*(SN General -.XE -.LP -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. -.LP -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. -.LP -This document describes; -.RS -.IP -Database Format Definition -.IP -Contents of Database in sample implementation -.RE -.LP -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. -.LP -.NH 1 -Database Format Definition -.XS -\*(SN Database Format Definition -.XE -.LP -The X Locale Database contains one or more category definitions. -This section describes the format of each category definition. -.LP -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 (}). -.LP -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. -.LP -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(}). -.LP -The format of category definition is; -.RS -.TS -tab(@); -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l l l -l r l -l r l -l l l. -CategoryDefinition@::=@CategoryHeader CategorySpec CategoryTrailer -CategoryHeader@::=@CategoryName NL -CategorySpec@::=@{ ClassSpec } -CategoryTrailer@::=@"END" Delimiter CategoryName NL -CategoryName@::=@String -ClassSpec@::=@ClassName Delimiter ClassValue NL -ClassName@::=@String -ClassValue@::=@ValueList | "{" NL { ClassSpec } "}" -ValueList@::=@Value | Value ";" ValueList -Value@::=@ValuePiece | ValuePiece Value -ValuePiece@::=@String | QuotedString | NumericString -String@::=@Char { Char } -QuotedString@::=@""" QuotedChar { QuotedChar } """ -NumericString@::=@"\\\\o" OctDigit { OctDigit } -@|@"\\\\d" DecDigit { DecDigit } -@|@"\\\\x" HexDigit { HexDigit } -Char@::=@ -QuotedChar@::=@ -OctDigit@::=@ -DecDigit@::=@ -HexDigit@::=@ -Delimiter@::=@ Space { Space } -Space@::=@ | -NL@::=@ -.TE -.RE -.LP -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. -.LP -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. -.LP -.NH 1 -Contents of Database -.XS -\*(SN Contents of Database -.XE -.LP -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. -.LP -In current sample implementation, categories listed below are available. -.RS -.TS -tab(:); -l l. -XLC_FONTSET:XFontSet relative information -XLC_XLOCALE:Character classification and conversion information -.TE -.RE -.LP -.NH 1 -XLC_FONTSET Category -.XS -\*(SN XLC_FONTSET Category -.XE -.LP -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). -.RS -.TS H -tab(:); -lw(1.5i) l l. -_ -.sp 6p -.B -class:super class:description -.sp 6p -_ -.sp 6p -.TH -.R -fsN::Nth fontset (N=0,1,2, ...) -.sp -charset:fsN:list of encoding name -font:fsN:list of font encoding name -.sp 6p -_ -.TE -.RE -.LP -.IP "fsN" -.br -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'. -.IP "charset" -Specifies an encoding information to be used internally in Xlib -for this fontset. The format of value is; -.RS -.TS -tab(;); -l l l. -EncodingInfo;::=;EncodingName [ ":" EncodingSide ] -EncodingName;::=;CHARSET_REGISTRY-CHARSET_ENCODING -EncodingSide;::=;"GL" | "GR" -.TE -.RE -For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer -"X Logical Font Descriptions" document. -.IP -example: -.br - ISO8859-1:GL -.IP "font" -.br -Specifies a list of encoding information which is used for searching -appropriate font for this fontset. The left most entry has highest -priority. -.LP -.NH 1 -XLC_XLOCALE Category -.XS -\*(SN XLC_XLOCALE Category -.XE -.LP -The XLC_XLOCALE category defines character classification, conversion -and other character attributes. -.RS -.TS H -tab(:); -lw(1.5i) l l. -_ -.sp 6p -.B -class:super class:description -.sp 6p -_ -.sp 6p -.TH -.R -encoding_name::codeset name -mb_cur_max::MB_CUR_MAX -state_depend_encoding::state dependent or not -wc_encoding_mask::for parsing wc string -wc_shift_bits::for conversion between wc and mb -csN::Nth charset (N=0,1,2,...) -.sp -side:csN:mapping side (GL, etc) -length:csN:length of a character -mb_encoding:csN:for parsing mb string -wc_encoding:csN:for parsing wc string -ct_encoding:csN:list of encoding name for ct -.sp 6p -_ -.TE -.RE -.LP -.IP "encoding_name" -Specifies a codeset name of current locale. -.IP "mb_cur_max" -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". -.IP "state_depend_encoding" -Indicates a current locale is state dependent. The value should be -specified "True" or "False". -.IP "wc_encoding_mask" -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'. -.IP "wc_shift_bits" -Specifies a number of bit to be shifted for converting from a multi-byte -character to a wide character, and vice-versa. -.IP "csN" -.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'. -.IP "side" -.br -Specifies a mapping side of this charset. The format of this value is; -.RS -.TS -tab(@); -l l l. -Side@::=@EncodingSide [``:Default''] -.TE -.RE -The suffix ":Default" can be specified. It indicates that a character -belongs to the specified side is mapped to this charset in initial state. -.IP "length" -.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. -.IP "mb_encoding" -Specifies a list of shift sequence for parsing multi-byte string. -The format of this value is; -.RS -.TS -tab(@); -l l l -l r l -l l l -l l l -l l l -l l l -c l s -c l s. -MBEncoding@::=@ShiftType ShiftSequence -@|@ShiftType ShiftSequence ";" MBEncoding -ShiftType@::=@"" | "" | "" -ShiftSequence@::=@SequenceValue | SequenceValue ShiftSequence -SequenceValue@::=@NumericString -.sp -shift types: -@Indicates single shift sequence -@Indicates locking shift left sequence -@Indicates locking shift right sequence -.TE -.RE -example: -.br - \\x1b \\x28 \\x4a; \\x1b \\x28 \\x42 -.LP -.IP "wc_encoding" -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. -.IP "ct_encoding" -Specifies a list of encoding information that can be used for Compound -Text. -.LP -.NH 1 -Sample of X Locale Database -.XS -\*(SN Sample of X Locale Database -.XE -.LP -The following is sample X Locale Database file. -.LP -.sp -.RS -.nf -# 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 \\x8e - - wc_encoding \\x00000080 - - ct_encoding JISX0201.1976-0:GR -} - -# cs3 class -# cs3 { -# side GL -# length 2 -# mb_encoding \\x8f -# #if HasWChar32 -# wc_encoding \\x20000000 -# #else -# wc_encoding \\x00008000 -# #endif -# ct_encoding JISX0212.1990-0:GL; JISX0212.1990-0:GR -# } - -END XLC_XLOCALE -.fi -.RE -.LP -.NH 1 -Reference -.XS -\*(SN Reference -.XE -.LP -.XP -[1] \fIISO/IEC 9899:1990 C Language Standard\fP -.XP -[2] \fIX Logical Font Descriptions\fP -.LP diff --git a/libX11/specs/i18n/Makefile.am b/libX11/specs/i18n/Makefile.am index 9f5d51e9a..1fd341f21 100644 --- a/libX11/specs/i18n/Makefile.am +++ b/libX11/specs/i18n/Makefile.am @@ -1,5 +1,5 @@ # -# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), @@ -21,8 +21,4 @@ # DEALINGS IN THE SOFTWARE. # -# Based on xc/doc/specs/i18n/Makefile from X11R6.9 - -doc_sources = Framework.ms LocaleDB.ms Trans.ms - -include $(top_srcdir)/specs/troffrules.in +SUBDIRS=framework localedb trans diff --git a/libX11/specs/i18n/Trans.ms b/libX11/specs/i18n/Trans.ms deleted file mode 100644 index 1216ef254..000000000 --- a/libX11/specs/i18n/Trans.ms +++ /dev/null @@ -1,1146 +0,0 @@ -.\" To print this out, type tbl macros.t This File | troff -ms -.EH '''' -.OH '''' -.EF '''' -.OF '''' -.ps 11 -.nr PS 11 -.\" .nr PD 1v -.\" .nr DD 1v -\& -.sp 8 -.TL -\s+3\fBThe XIM Transport Specification\s-3\fP -.sp -.sp -\fBRevision 0.1\fP -.sp -\fBX Version 11, Release 7\fP -.sp -\fB\*(xV\fP -.sp 3 -.AU -Takashi Fujiwara -.AI -FUJITSU LIMITED -.sp 3 -.AB -.LP -This specification describes the transport layer interfaces between -Xlib and IM Server, which makes various channels usable such as X -protocol or, TCP/IP, DECnet and etc. -.AE -.ce 0 -.br -.LP -.bp -\& -.ps 9 -.nr PS 9 -.sp 8 -.LP -Copyright \(co 1994 by FUJITSU LIMITED -.LP -Permission to use, copy, modify, and distribute this documentation -for any purpose and without fee is hereby granted, provided -that the above copyright notice and this permission -notice appear in all copies. -Fujitsu makes no representations about the suitability -for any purpose of the information in this document. -This documentation is provided as is without express or implied warranty. -.sp 5 -Copyright \(co 1994 X Consortium -.LP -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the ``Software''), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: -.LP -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. -.LP -THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN -AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -.LP -Except as contained in this notice, the name of the X Consortium shall not be -used in advertising or otherwise to promote the sale, use or other dealings -in this Software without prior written authorization from the X Consortium. -.sp 3 -\fIX Window System\fP is a trademark of The Open Group. -.ps 11 -.nr PS 11 -.bp 1 -.EH '\fBXIM Transport Specification\fP''\fB\*(xV\fP' -.OH '\fBXIM Transport Specification\fP''\fB\*(xV\fP' -.EF ''\fB % \fP'' -.OF ''\fB % \fP'' -.NH 1 -Introduction -.XS -\*(SN Introduction -.XE -.LP -The Xlib XIM implementation is layered into three functions, a protocol -layer, an interface layer and a transport layer. The purpose of this -layering is to make the protocol independent of transport implementation. -Each function of these layers are: -.RS 3 -.IP "\fIThe protocol layer\fP" -.br -implements overall function of XIM and calls the interface layer -functions when it needs to communicate to IM Server. -.IP "\fIThe interface layer\fP" -.br -separates the implementation of the transport layer from the protocol -layer, in other words, it provides implementation independent hook for -the transport layer functions. -.IP "\fIThe transport layer\fP" -.br -handles actual data communication with IM Server. It is done by a set -of several functions named transporters. -.RE -.LP -This specification describes the interface layer and the transport -layer, which makes various communication channels usable such as -X protocol or, TCP/IP, DECnet, STREAM, etc., and provides -the information needed for adding another new transport layer. -In addition, sample implementations for the transporter using the -X connection is described in section 4. -.NH 1 -Initialization -.XS -\*(SN Initialization -.XE -.NH 2 -Registering structure to initialize -.XS -\*(SN Registering structure to initialize -.XE -.LP -The structure typed as TransportSW contains the list of the transport -layer the specific implementations supports. -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -typedef struct { -.br - char *transport_name; -.br - Bool (*config); -} TransportSW; -.De -.LP -.IP "\fItransport_name\fP" 15 -name of transport(*1) -.FS -(*1) Refer to "The Input Method Protocol: Appendix B" -.FE -.IP "\fIconfig\fP" 15 -initial configuration function -.LP -A sample entry for the Xlib supporting transporters is shown below: -.LP -.Ds 0 -.TA .5i 2.5i -.ta .5i 2.5i -TransportSW _XimTransportRec[] = { -.sp 3p -/* char \fI*: -\ * transport_name\fP, Bool \fI(*config)()\fP -\ */ - ``X'', _XimXConf, - ``tcp'', _XimTransConf, - ``local'', _XimTransConf, - ``decnet'', _XimTransConf, - ``streams'', _XimTransConf, - (char *)NULL, (Bool (*)())NULL, -}; -.De -.LP -.NH 2 -Initialization function -.XS -\*(SN Initialization function -.XE -.LP -The following function will be called once when Xlib configures the -transporter functions. -.sp 6p -.FD 0 -Bool (*config)(\fIim\fP, \fItransport_data\fP) -.br - XIM \fIim\fP; -.br - char \fI*transport_data\fP; -.br -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fItransport_data\fP 1i -Specifies the data specific to the transporter, in IM Server address. (*1) -.FS -(*1) Refer to "The Input Method Protocol: Appendix B" -.FE -.sp 6p -.LP -This function must setup the transporter function pointers. -.LP -The actual \fIconfig\fP function will be chosen by IM Server at the -pre-connection time, matching by the \fItransport_name\fP specified -in the \fB_XimTransportRec\fP array; The specific members of XimProto -structure listed below must be initialized so that point they -appropriate transporter functions. -.LP -If the specified transporter has been configured successfully, this -function returns True. There is no Alternative Entry for config -function itself. -.LP -The structure XimProto contains the following function pointers: -.DS -.TA .5i 2.5i -.ta .5i 2.5i -Bool (*connect)(); /* Open connection */ -Bool (*shutdown)(); /* Close connection */ -Bool (*write)(); /* Write data */ -Bool (*read)(); /* Read data */ -Bool (*flush)(); /* Flush data buffer */ -Bool (*register_dispatcher)(); /* Register asynchronous data handler */ -Bool (*call_dispatcher)(); /* Call dispatcher */ -.DE -These functions are called when Xlib needs to communicate the -IM Server. These functions must process the appropriate procedure -described below. -.LP -.NH 1 -The interface/transport layer functions -.XS -\*(SN The interface/transport layer functions -.XE -.LP -Following functions are used for the transport interface. -.LP -.ce -Table 3-1; The Transport Layer Functions. -.SM -.TS -tab(:) center box; -cw(4c) | cw(4c) | c -c | c | c -l | l | c. -.B -Alternative Entry:XimProto member:Section -(Interface Layer):(Transport Layer):\^ -= -.R -\fB_XimConnect\fP:connect:3.1 -_ -\fB_XimShutdown\fP:shutdown:3.2 -_ -\fB_XimWrite\fP:write:3.3 -_ -\fB_XimRead\fP:read:3.4 -_ -\fB_XimFlush\fP:flush:3.5 -_ -\fB_XimRegisterDispatcher\fP:register_dispatcher:3.6 -_ -\fB_XimCallDispatcher\fP:call_dispatcher:3.7 -.TE -.NL -.LP -The Protocol layer calls the above functions using the Alternative -Entry in the left column. The transport implementation defines -XimProto member function in the right column. The Alternative Entry is -provided so as to make easier to implement the Protocol Layer. -.LP -.NH 2 -Opening connection -.XS -\*(SN Opening connection -.XE -.LP -When \fBXOpenIM\fP is called, the following function is called to connect -with the IM Server. -.sp 6p -.FD 0 -Bool (*connect)(\fIim\fP) -.br - XIM \fIim\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.sp 6p -.LP -This function must establishes the connection to the IM Server. If the -connection is established successfully, this function returns True. -The Alternative Entry for this function is: -.sp 6p -.FD 0 -Bool _XimConnect(\fIim\fP) -.br - XIM \fIim\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.LP -.NH 2 -Closing connection -.XS -\*(SN Closing connection -.XE -.LP -When \fBXCloseIM\fP is called, the following function is called to -disconnect the connection with the IM Server. The Alternative Entry -for this function is: -.sp 6p -.FD 0 -Bool (*shutdown)(\fIim\fP) -.br - XIM \fIim\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.sp 6p -.LP -This function must close connection with the IM Server. If the -connection is closed successfully, this function returns True. The -Alternative Entry for this function is: -.sp 6p -.FD 0 -Bool _XimShutdown(\fIim\fP) -.br - XIM \fIim\fP; -.FN -.IP \fIim\fP -Specifies XIM structure address. -.LP -.NH 2 -Writing data -.XS -\*(SN Writing data -.XE -.LP -The following function is called, when Xlib needs to write data to the -IM Server. -.sp 6p -.FD 0 -Bool (*write)(\fIim\fP, \fIlen\fP, \fIdata\fP) -.br - XIM \fIim\fP; -.br - INT16 \fIlen\fP; -.br - XPointer \fIdata\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIlen\fP 1i -Specifies the length of writing data. -.IP \fIdata\fP 1i -Specifies the writing data. -.sp 6p -.LP -This function writes the \fIdata\fP to the IM Server, regardless -of the contents. The number of bytes is passed to \fIlen\fP. The -writing data is passed to \fIdata\fP. If data is sent successfully, -the function returns True. Refer to "The Input Method Protocol" for -the contents of the writing data. The Alternative Entry for this -function is: -.sp 6p -.FD 0 -Bool _XimWrite(\fIim\fP, \fIlen\fP, \fIdata\fP) -.br - XIM \fIim\fP; -.br - INT16 \fIlen\fP; -.br - XPointer \fIdata\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIlen\fP 1i -Specifies the length of writing data. -.IP \fIdata\fP 1i -Specifies the writing data. -.LP -.NH 2 -Reading data -.XS -\*(SN Reading data -.XE -.LP -The following function is called when Xlib waits for response from IM -server synchronously. -.sp 6p -.FD 0 -Bool (*read)(\fIim\fP, \fIread_buf\fP, \fIbuf_len\fP, \fIret_len\fP) -.br - XIM \fIim\fP; -.br - XPointer \fIread_buf\fP; -.br - int \fIbuf_len\fP; -.br - int \fI*ret_len\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIread_buf\fP 1i -Specifies the buffer to store data. -.IP \fIbuf_len\fP 1i -Specifies the size of the \fIbuffer\fP -.IP \fIret_len\fP -Specifies the length of stored data. -.sp 6p -.LP -This function stores the read data in \fIread_buf\fP, which size is -specified as \fIbuf_len\fP. The size of data is set to \fIret_len\fP. -This function return True, if the data is read normally or reading -data is completed. -.LP -The Alternative Entry for this function is: -.sp 6p -.FD 0 -Bool _XimRead(\fIim\fP, \fIret_len\fP, \fIbuf\fP, \fIbuf_len\fP, \fIpredicate\fP, \fIpredicate_arg\fP) -.br - XIM \fIim\fP; -.br - INT16 \fI*ret_len\fP; -.br - XPointer \fIbuf\fP; -.br - int \fIbuf_len\fP; -.br - Bool \fI(*predicate)()\fP; -.br - XPointer \fIpredicate_arg\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIret_len\fP 1i -Specifies the size of the \fIdata\fP buffer. -.IP \fIbuf\fP 1i -Specifies the buffer to store data. -.IP \fIbuf_len\fP 1i -Specifies the length of \fIbuffer\fP. -.IP \fIpredicate\fP 1i -Specifies the predicate for the XIM data. -.IP \fIpredicate_arg\fP 1i -Specifies the predicate specific data. -.sp 6p -.LP -The predicate procedure indicates whether the \fIdata\fP is for the -XIM or not. \fIlen\fP -This function stores the read data in \fIbuf\fP, which size is specified -as \fIbuf_len\fP. The size of data is set to \fIret_len\fP. -If \fIpreedicate()\fP returns True, this function returns True. -If not, it calls the registered callback function. -.LP -The procedure and its arguments are: -.LP -.sp 6p -.FD 0 -Bool (*predicate)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIpredicate_arg\fP) -.br - XIM \fIim\fP; -.br - INT16 \fIlen\fP; -.br - XPointer \fIdata\fP; -.br - XPointer \fIpredicate_arg\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIlen\fP 1i -Specifies the size of the \fIdata\fP buffer. -.IP \fIdata\fP 1i -Specifies the buffer to store data. -.IP \fIpredicate_arg\fP 1i -Specifies the predicate specific data. -.LP -.NH 2 -Flushing buffer -.XS -\*(SN Flushing buffer -.XE -.LP -The following function is called when Xlib needs to flush the data. -.sp 6p -.FD 0 -void (*flush)(\fIim\fP) -.br - XIM \fIim\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.sp 6p -.LP -This function must flush the data stored in internal buffer on the -transport layer. If data transfer is completed, the function returns -True. The Alternative Entry for this function is: -.sp 6p -.FD 0 -void _XimFlush(\fIim\fP) -.br - XIM \fIim\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.LP -.NH 2 -Registering asynchronous data handler -.XS -\*(SN Registering asynchronous data handler -.XE -.LP -Xlib needs to handle asynchronous response from IM Server. This is -because some of the XIM data occur asynchronously to X events. -.LP -Those data will be handled in the \fIFilter\fP, and the \fIFilter\fP -will call asynchronous data handler in the protocol layer. Then it -calls dispatchers in the transport layer. The dispatchers are -implemented by the protocol layer. This function must store the -information and prepare for later call of the dispatchers using -\fB_XimCallDispatcher\fP. -.LP -When multiple dispatchers are registered, they will be called -sequentially in order of registration, on arrival of asynchronous -data. The register_dispatcher is declared as following: -.sp 6p -.FD 0 -Bool (*register_dispatcher)(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP) -.br - XIM \fIim\fP; -.br - Bool \fI(*dispatcher)()\fP; -.br - XPointer \fIcall_data\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIdispatcher\fP 1i -Specifies the dispatcher function to register. -.IP \fIcall_data\fP 1i -Specifies a parameter for the \fIdispatcher\fP. -.LP -The dispatcher is a function of the following type: -.sp 6p -.FD 0 -Bool (*dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIcall_data\fP) -.br - XIM \fIim\fP; -.br - INT16 \fIlen\fP; -.br - XPointer \fIdata\fP; -.br - XPointer \fIcall_data\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIlen\fP 1i -Specifies the size of the \fIdata\fP buffer. -.IP \fIdata\fP 1i -Specifies the buffer to store data. -.IP \fIcall_data\fP 1i -Specifies a parameter passed to the register_dispatcher. -.sp 6p -.LP -The dispatcher is provided by the protocol layer. They are called once -for every asynchronous data, in order of registration. If the data is -used, it must return True. otherwise, it must return False. -.LP -If the dispatcher function returns True, the Transport Layer assume -that the data has been processed by the upper layer. The Alternative -Entry for this function is: -.sp 6p -.FD 0 -Bool _XimRegisterDispatcher(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP) -.br - XIM \fIim\fP; -.br - Bool \fI(*dispatcher)()\fP; -.br - XPointer \fIcall_data\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIdispatcher\fP 1i -Specifies the dispatcher function to register. -.IP \fIcall_data\fP 1i -Specifies a parameter for the \fIdispatcher\fP. -.LP -.NH 2 -Calling dispatcher -.XS -\*(SN Calling dispatcher -.XE -.LP -The following function is used to call the registered dispatcher -function, when the asynchronous response from IM Server has arrived. -.sp 6p -.FD 0 -Bool (*call_dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP) -.br - XIM \fIim\fP; -.br - INT16 \fIlen\fP; -.br - XPointer \fIdata\fP; -.FN -.IP \fIim\fP 1i -Specifies XIM structure address. -.IP \fIlen\fP 1i -Specifies the size of \fIdata\fP buffer. -.IP \fIdata\fP 1i -Specifies the buffer to store data. -.LP -The call_dispatcher must call the dispatcher function, in order of -their registration. \fIlen\fP and \fIdata\fP are the data passed to -register_dispatcher. -.LP -The return values are checked at each invocation, and if it finds -True, it immediately return with true for its return value. -.LP -It is depend on the upper layer whether the read data is XIM -Protocol packet unit or not. -The Alternative Entry for this function is: -.sp 6p -.FD 0 -Bool _XimCallDispatcher(\fIim\fP, \fIlen\fP, \fIdata\fP) -.br - XIM \fIim\fP; -.br - INT16 \fIlen\fP; -.br - XPointer \fIcall_data\fP; -.FN -.LP -.bp -.NH 1 -Sample implementations for the Transport Layer -.XS -\*(SN Sample implementations for the Transport Layer -.XE -.LP -Sample implementations for the transporter using the X connection is -described here. -.LP -.NH 2 -X Transport -.XS -\*(SN X Transport -.XE -.LP -At the beginning of the X Transport connection for the XIM transport -mechanism, two different windows must be created either in an Xlib XIM -or in an IM Server, with which the Xlib and the IM Server exchange the -XIM transports by using the ClientMessage events and Window Properties. -In the following, the window created by the Xlib is referred as the -"client communication window", and on the other hand, the window created -by the IM Server is referred as the "IMS communication window". -.LP -.NH 3 -Connection -.XS -\*(SN X Connection -.XE -.LP -In order to establish a connection, a communication window is created. -A ClientMessage in the following event's format is sent to the owner -window of XIM_SERVER selection, which the IM Server has created. -.LP -Refer to "The Input Method Protocol" for the XIM_SERVER atom. -.LP -.ce -Table 4-1; The ClientMessage sent to the IMS window. -.TS H -tab(:); -l s|l -l l|l. -_ -.sp 6p -.B -Structure Member:Contents -.sp 6p -_ -.sp 6p -.TH -.R -int:type:ClientMessage -u_long:serial:Set by the X Window System -Bool:send_event:Set by the X Window System -Display:*display:The display to which connects -Window:window:IMS Window ID -Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False) -int:format:32 -long:data.l[0]:client communication window ID -long:data.l[1]:client-major-transport-version (*1) -long:data.l[2]:client-major-transport-version (*1) -.sp 6p -_ -.TE -.LP -In order to establish the connection (to notify the IM Server communication -window), the IM Server sends a ClientMessage in the following event's -format to the client communication window. -.LP -.ce -Table 4-2; The ClientMessage sent by IM Server. -.TS H -tab(:); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member:Contents -.sp 6p -_ -.sp 6p -.TH -.R -int:type:ClientMessage -u_long:serial:Set by the X Window System -Bool:send_event:Set by the X Window System -Display:*display:The display to which connects -Window:window:client communication window ID -Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False) -int:format:32 -long:data.l[0]:IMS communication window ID -long:data.l[1]:server-major-transport-version (*1) -long:data.l[2]:server-minor-transport-version (*1) -long:data.l[3]:dividing size between ClientMessage and Property (*2) -.sp 6p -_ -.TE -.LP -.IP (*1) -major/minor-transport-version -.RS -The read/write method is decided by the combination of -major/minor-transport-version, as follows: -.LP -.ce -Table 4-3; The read/write method and the major/minor-transport-version -.TS -center, tab(:); -| c s | l | -| c | c | l |. -_ -.sp 6p -.B -Transport-version:read/write -.sp 6p -_ -.sp 6p -major:minor: -.sp 6p -_ -.sp 6p -.R -0:0:only-CM & Property-with-CM -:1:only-CM & multi-CM -:2:only-CM & multi-CM & Property-with-CM -.sp 6p -_ -.sp 6p -1:0:PropertyNotify -.sp 6p -_ -.sp 6p -2:0:only-CM & PropertyNotify -:1:only-CM & multi-CM & PropertyNotify -.sp 6p -_ -.TE -.LP -.RS -.TS -center, tab(;); -l n l. -only-CM;:;data is sent via a ClientMessage -multi-CM;:;data is sent via multiple ClientMessages -Property-with-CM;:;T{ -data is written in Property, and its Atom is send via ClientMessage -T} -PropertyNotify;:;T{ -data is written in Property, and its Atom is send via PropertyNotify -T} -.TE -.RE -.LP -The method to decide major/minor-transport-version is as follows: -.LP -.IP (1) -The client sends 0 as major/minor-transport-version to the IM Server. -The client must support all methods in Table 4-3. -The client may send another number as major/minor-transport-version to -use other method than the above in the future. -.IP (2) -The IM Server sends its major/minor-transport-version number to -the client. The client sends data using the method specified by the -IM Server. -.IP (3) -If major/minor-transport-version number is not available, it is regarded -as 0. -.RE -.LP -.IP (*2) -dividing size between ClientMessage and Property -.RS -If data is sent via both of multi-CM and Property, specify the dividing -size between ClientMessage and Property. The data, which is smaller than -this size, is sent via multi-CM (or only-CM), and the data, which is -lager than this size, is sent via Property. -.RE -.LP -.NH 3 -read/write -.XS -\*(SN read/write -.XE -.LP -The data is transferred via either ClientMessage or Window Property in -the X Window System. -.LP -.NH 4 -Format for the data from the Client to the IM Server -.XS -\*(SN Format for the data from the Client to the IM Server -.XE -.LP -.B -ClientMessage -.LP -.RS -If data is sent via ClientMessage event, the format is as follows: -.LP -.ce -Table 4-4; The ClientMessage event's format (first or middle) -.TS H -tab(;); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member;Contents -.sp 6p -_ -.sp 6p -.TH -.R -int;type;ClientMessage -u_long;serial;Set by the X Window System -Bool;send_event;Set by the X Window System -Display;*display;The display to which connects -Window;window;IMS communication window ID -Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False) -int;format;8 -char;data.b[20];(read/write DATA : 20 byte) -.sp 6p -_ -.TE -.LP -.ce -Table 4-5; The ClientMessage event's format (only or last) -.TS H -tab(;); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member;Contents -.sp 6p -_ -.sp 6p -.TH -.R -int;type;ClientMessage -u_long;serial;Set by the X Window System -Bool;send_event;Set by the X Window System -Display;*display;The display to which connects -Window;window;IMS communication window ID -Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False) -int;format;8 -char;data.b[20];(read/write DATA : MAX 20 byte) (*1) -.sp 6p -_ -.TE -.IP (*1) -If the data is smaller than 20 byte, all data other than available data -must be 0. -.RE -.LP -.B -Property -.LP -.RS -In the case of large data, data will be sent via the Window Property -for the efficiency. There are the following two methods to notify -Property, and transport-version is decided which method is used. -.LP -.IP (1) -The XChangeProperty function is used to store data in the client -communication window, and Atom of the stored data is notified to the -IM Server via ClientMessage event. -.IP (2) -The XChangeProperty function is used to store data in the client -communication window, and Atom of the stored data is notified to the -IM Server via PropertyNotify event. -.LP -The arguments of the XChangeProperty are as follows: -.LP -.ce -Table 4-6; The XChangeProperty event's format -.TS H -tab(:); -l s | l -l l | l. -_ -.sp 6p -.B -Argument:Contents -.sp 6p -_ -.sp 6p -.TH -.R -Display:*display:The display to which connects -Window:window:IMS communication window ID -Atom:property:read/write property Atom (*1) -Atom:type:XA_STRING -int:format:8 -int:mode:PropModeAppend -u_char:*data:read/write DATA -int:nelements:length of DATA -.sp 6p -_ -.TE -.LP -.IP (*1) -The read/write property ATOM allocates the following strings by -\fBXInternAtom\fP. -.RS -``_clientXXX'' -.RE -.LP -The client changes the property with the mode of PropModeAppend and -the IM Server will read it with the delete mode i.e. (delete = True). -.LP -If Atom is notified via ClientMessage event, the format of the ClientMessage -is as follows: -.LP -.ce -Table 4-7; The ClientMessage event's format to send Atom of property -.TS H -tab(:); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member:Contents -.sp 6p -_ -.sp 6p -.TH -.R -int:type:ClientMessage -u_long:serial:Set by the X Window System -Bool:send_event:Set by the X Window System -Display:*display:The display to which connects -Window:window:IMS communication window ID -Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False) -int:format:32 -long:data.l[0]:length of read/write property Atom -long:data.l[1]:read/write property Atom -.sp 6p -_ -.TE -.RE -.LP -.NH 4 -Format for the data from the IM Server to the Client -.XS -\*(SN Format for the data from the Client to the Client -.XE -.LP -.B -ClientMessage -.LP -.RS -The format of the ClientMessage is as follows: -.LP -.ce -Table 4-8; The ClientMessage event's format (first or middle) -.TS H -tab(;); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member;Contents -.sp 6p -_ -.sp 6p -.TH -.R -int;type;ClientMessage -u_long;serial;Set by the X Window System -Bool;send_event ;Set by the X Window System -Display;*display;The display to which connects -Window;window;client communication window ID -Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False) -int;format;8 -char;data.b[20];(read/write DATA : 20 byte) -.sp 6p -_ -.TE -.LP -.ce -Table 4-9; The ClientMessage event's format (only or last) -.TS H -tab(;); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member;Contents -.sp 6p -_ -.sp 6p -.TH -.R -int;type;ClientMessage -u_long;serial;Set by the X Window System -Bool;send_event ;Set by the X Window System -Display;*display;The display to which connects -Window;window;client communication window ID -Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False) -int;format;8 -char;data.b[20];(read/write DATA : MAX 20 byte) (*1) -.sp 6p -_ -.TE -.LP -.IP (*1) -If the data size is smaller than 20 bytes, all data other than available -data must be 0. -.RE -.LP -.B -Property -.LP -.RS -In the case of large data, data will be sent via the Window Property -for the efficiency. There are the following two methods to notify -Property, and transport-version is decided which method is used. -.LP -.IP (1) -The XChangeProperty function is used to store data in the IMS -communication window, and Atom of the property is sent via the -ClientMessage event. -.IP (2) -The XChangeProperty function is used to store data in the IMS -communication window, and Atom of the property is sent via -PropertyNotify event. -.LP -The arguments of the XChangeProperty are as follows: -.LP -.ce -Table 4-10; The XChangeProperty event's format -.TS H -tab(:); -l s | l -l l | l. -_ -.sp 6p -.B -Argument:Contents -.sp 6p -_ -.sp 6p -.TH -.R -Display:*display:The display which to connects -Window:window:client communication window ID -Atom:property:read/write property Atom (*1) -Atom:type:XA_STRING -int:format:8 -int:mode:PropModeAppend -u_char:*data:read/write DATA -int:nelements:length of DATA -.sp 6p -_ -.TE -.LP -.IP (*1) -The read/write property ATOM allocates some strings, which are not -allocated by the client, by \fBXInternAtom\fP. -.LP -The IM Server changes the property with the mode of PropModeAppend and -the client reads it with the delete mode, i.e. (delete = True). -.LP -If Atom is notified via ClientMessage event, the format of the ClientMessage -is as follows: -.LP -.ce -Table 4-11; The ClientMessage event's format to send Atom of property -.TS H -tab(:); -l s | l -l l | l. -_ -.sp 6p -.B -Structure Member:Contents -.sp 6p -_ -.sp 6p -.TH -.R -int:type:ClientMessage -u_long:serial:Set by the X Window System -Bool:send_event:Set by the X Window System -Display:*display:The display to which connects -Window:window:client communication window ID -Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False) -int:format:32 -long:data.l[0]:length of read/write property ATOM -long:data.l[1]:read/write property ATOM -.sp 6p -_ -.TE -.RE -.LP -.NH 3 -Closing Connection -.XS -\*(SN Closing Connection -.XE -.LP -If the client disconnect with the IM Server, shutdown function should -free the communication window properties and etc.. -.LP -.NH 1 -References -.XS -\*(SN References -.XE -.LP -[1] Masahiko Narita and Hideki Hiura, \fI``The Input Method Protocol''\fP -.LP - diff --git a/libX11/specs/i18n/framework/Makefile.am b/libX11/specs/i18n/framework/Makefile.am new file mode 100644 index 000000000..8f6364a03 --- /dev/null +++ b/libX11/specs/i18n/framework/Makefile.am @@ -0,0 +1,32 @@ +# +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS 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. +# + +if ENABLE_SPECS + +specdir = $(docdir)/$(subdir) +doc_sources = framework.xml +dist_spec_DATA = $(doc_sources) framework.svg + +include $(top_srcdir)/specs/xmlrules.in + +endif ENABLE_SPECS diff --git a/libX11/specs/i18n/framework/framework.svg b/libX11/specs/i18n/framework/framework.svg new file mode 100644 index 000000000..7adfc1404 --- /dev/null +++ b/libX11/specs/i18n/framework/framework.svg @@ -0,0 +1,703 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + Application + <<ANSI/MSE API>>(X Contrib) + + <<XLib API>>(X Core) + <<ANSI/MSE API>>(X Contrib) + InputMethod + OutputMethod + <Locl. Serv. API>X Locale Object + C Library + ANSI impl + XLC_XLOCALE- MB_CUR_MAXcodeset infoo char/charseto conv/charset + XLC_FONTSET- fontset info- charset info- font/charset- XLFD,GL/GR + localedef DB- MB_CUR_MAX- codset infoo char/charseto conv/charset + Locale Library + non-ANSI impl. + + + + + + + + XLocale Source (X Core) + System Locale Source + + + + + + + + + + + diff --git a/libX11/specs/i18n/framework/framework.xml b/libX11/specs/i18n/framework/framework.xml new file mode 100644 index 000000000..ab1dac6b6 --- /dev/null +++ b/libX11/specs/i18n/framework/framework.xml @@ -0,0 +1,1620 @@ + + + + + + + X11R6 Sample Implementation Frame Work + X Version 11, Release 7 + + + KatsuhisaYano + TOSHIBA Corporation + + + YoshioHoriuchi + IBM Japan + + + 1994TOSHIBA Corporation + 1994IBM Corporation + + + + +Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice and this permission notice appear in all copies. TOSHIBA Corporation and +IBM Corporation make no representations about the suitability for any purpose of the information in this document. +This documentation is provided as is without express or implied warranty. + + + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files +(the "Software"), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to permit +persons to whom the Software is furnished to do so, subject to the following +conditions: + + + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + + + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN +NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + + + +Except as contained in this notice, the name of The 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. + + +X Window System is a trademark of The Open Group. + + + + + +Framework + +Preface + +This document proposes to define the structures, methods and their +signatures that are expected to be common to all locale dependent +functions within the Xlib sample implementation. The following +illustration (Fig.1) is proposed to outline the separating of +the components within the sample implementation. + + + +Preface drawing. + + + + + + + Frame work of Locale Service API Proposal + + + +Generally speaking, the internationalized portion of Xlib (Locale +Dependent X, LDX) consists of three objects; +locale (LC) , input method (IM) and output method (OM). +The LC provides a set of information that depends on user's language +environment. The IM manages text inputing, and the OM manages text +drawing. Both IM and OM highly depend on LC data. + + + +In X11R5, there are two sample implementations, Ximp and Xsi, for +Xlib internationalization. But in both implementations, IM and OM +actually refer the private extension of LC. It breaks coexistence +of these two sample implementations. For example, if a user creates +a new OM for special purpose as a part of Ximp, it will not work with +Xsi. + + + +As a solution of this problem, we propose to define the standard +APIs between these three objects, and define the structure that are +common to these objects. + + + + +Objective + + + + +Explain the current X11R6 sample implementation + + + + +Document the common set of locale dependent interfaces + + + + +Provide more flexible pluggable layer + + + + + + +Locale Object Binding Functions + + + +This chapter describes functions related locale object binding for +implementing the pluggable layer. + + + +A locale loader is an entry point for locale object, which +instantiates XLCd object and binds locale methods with specified +locale name. The behavior of loader is implementation dependent. +And, what kind of loaders are available is also implementation +dependent. + + + + +The loader is called in +_XOpenLC, +but caller of +_XOpenLC +does not need to care about its inside. For example, if the loader is +implemented with dynamic load functions, and the dynamic module is +expected to be unloaded when the corresponding XLCd is freed, +close methods of XLCdMethods should handle unloading. + + + +Initializing a locale loader list + + +void _XlcInitLoader + + + +The +_XlcInitLoader +function initializes the locale loader list with vendor specific +manner. Each loader is registered with calling +_XlcAddLoader. +The number of loaders and their order in the loader list is +implementation dependent. + + + +Add a loader + + + +typedef XLCd (*XLCdLoadProc)(name); + char *name; + +typedef int XlcPosition; + +#define XlcHead +#define XlcTail + + + + + Bool _XlcAddLoader + XLCdLoadProc proc + XlcPosition position + + + + +The +_XlcAddLoader +function registers the specified locale loader "proc" to the +internal loader list. The position specifies that the loader +"proc" should be placed in the top of the loader list(XlcHead) +or last(XlcTail). + + + +The object loader is called from the top of the loader list in order, +when calling time. + + + +Remove a loader + + + + + void _XlcRemoveLoader + XLCdLoadProc proc + + + + +The +_XlcRemoveLoader +function removes the locale loader specified by "proc" from the +loader list. + + + +Current implementation provides following locale loaders; + + + +_XlcDefaultLoader +_XlcGenericLoader +_XlcEucLoader +_XlcSjisLoader +_XlcUtfLoader +_XaixOsDynamicLoad + + + + + +Locale Method Interface + + +This chapter describes the locale method API, which is a set of +accessible functions from both IM and OM parts. +The locale method API provides the functionalities; obtaining locale +dependent information, handling charset, converting text, etc. + + + +As a result of using these APIs instead of accessing vender private +extension of the locale object, we can keep locale, IM and OM +independently each other. + + + + + +Locale Method Functions + +Open a Locale Method + + + + + XLCd _XOpenLC + char *name + + + + +The +_XOpenLC +function opens a locale method which corresponds to the +specified locale name. +_XOpenLC +calls a locale object loader, which is registered via +_XlcAddLoader into the internal loader list. If the called loader +is valid and successfully opens a locale, +_XOpenLC +returns the XLCd. If the loader is invalid or failed to open a locale, +_XOpenLC +calls the next loader. If all registered loaders cannot open a locale, +_XOpenLC +returns NULL. + + +XLCd _XlcCurrentLC + + +The +_XlcCurrentLC +function returns an XLCd that are bound to current locale. + + + +Close a Locale Method + + + + + void _XCloseLC + XLCd lcd + + + + + +The +_XCloseLC +function close a locale method the specified lcd. + + + +Obtain Locale Method values + + + + + char *_XGetLCValues + XLCd lcd + + + + +The +_XGetLCValues +function returns NULL if no error occurred; otherwise, it returns the +name of the first argument that could not be obtained. +The following values are defined as standard arguments. Other values +are implementation dependent. + + + + + + + + + + Name + Type + Description + + + + + XlcNCodeset + char* + codeset part of locale name + + + XlcNDefaultString + char* + XDefaultString() + + + XlcNEncodingName + char* + encoding name + + + XlcNLanguage + char* + language part of locale name + + + XlcNMbCurMax + int + ANSI C MB_CUR_MAX + + + XlcNStateDependentEncoding + Bool + is state-dependent encoding or not + + + XlcNTerritory + char* + territory part of locale name + + + + + + + + +Charset functions + +The XlcCharSet is an identifier which represents a subset of characters +(character set) in the locale object. + + + +typedef enum { + XlcUnknown, XlcC0, XlcGL, XlcC1, XlcGR, XlcGLGR, XlcOther +} XlcSide; + +typedef struct _XlcCharSetRec *XlcCharSet; + +typedef struct { + char *name; + XPointer value; +} XlcArg, *XlcArgList; + +typedef char* (*XlcGetCSValuesProc)(charset, args, num_args); + XlcCharSet charset; + XlcArgList args; + int num_args; + +typedef struct _XlcCharSetRec { + char *name; + XrmQuark xrm_name; + char *encoding_name; + XrmQuark xrm_encoding_name; + XlcSide side; + int char_size; + int set_size; + char *ct_sequence; + XlcGetCSValuesProc get_values; +} XlcCharSetRec; + + + +Get an XlcCharSet + + + + + XlcCharSet _XlcGetCharSet + char *name + + + + +The +_XlcGetCharSet +function gets an XlcCharSet which corresponds to the charset name +specified by "name". +_XlcGetCharSet +returns NULL, if no XlcCharSet bound to specified "name". + + + +The following character sets are pre-registered. + + + + + + + + + Name + Description + + + + + ISO8859-1:GL + 7-bit ASCII graphics (ANSI X3.4-1968), + + + + Left half of ISO 8859 sets + + + JISX0201.1976-0:GL + Left half of JIS X0201-1976 (reaffirmed 1984), + + + + 8-Bit Alphanumeric-Katakana Code + + + ISO8859-1:GR + Right half of ISO 8859-1, Latin alphabet No. 1 + + + ISO8859-2:GR + Right half of ISO 8859-2, Latin alphabet No. 2 + + + ISO8859-3:GR + Right half of ISO 8859-3, Latin alphabet No. 3 + + + ISO8859-4:GR + Right half of ISO 8859-4, Latin alphabet No. 4 + + + ISO8859-7:GR + Right half of ISO 8859-7, Latin/Greek alphabet + + + ISO8859-6:GR + Right half of ISO 8859-6, Latin/Arabic alphabet + + + ISO8859-8:GR + Right half of ISO 8859-8, Latin/Hebrew alphabet + + + ISO8859-5:GR + Right half of ISO 8859-5, Latin/Cyrillic alphabet + + + ISO8859-9:GR + Right half of ISO 8859-9, Latin alphabet No. 5 + + + JISX0201.1976-0:GR + Right half of JIS X0201-1976 (reaffirmed 1984), + + + + 8-Bit Alphanumeric-Katakana Code + + + GB2312.1980-0:GL + GB2312-1980, China (PRC) Hanzi defined as GL + + + GB2312.1980-0:GR + GB2312-1980, China (PRC) Hanzi defined as GR + + + JISX0208.1983-0:GL + JIS X0208-1983, Japanese Graphic Character Set + + + + defined as GL + + + JISX0208.1983-0:GR + JIS X0208-1983, Japanese Graphic Character Set + + + + defined as GR + + + KSC5601.1987-0:GL + KS C5601-1987, Korean Graphic Character Set + + + + defined as GL + + + KSC5601.1987-0:GR + KS C5601-1987, Korean Graphic Character Set + + + + defined as GR + + + JISX0212.1990-0:GL + JIS X0212-1990, Japanese Graphic Character Set + + + + defined as GL + + + JISX0212.1990-0:GR + JIS X0212-1990, Japanese Graphic Character Set + + + + defined as GR + + + + + + +Add an XlcCharSet + + + + + Bool _XlcAddCharSet + XlcCharSet charset + + + + +The +_XlcAddCharSet +function registers XlcCharSet specified by "charset". + + + + + +Obtain Character Set values + + + + + char * _XlcGetCSValues + XlcCharSet charset + ... + + + + +The +_XlcGetCSValues +function returns NULL if no error occurred; +otherwise, it returns the name of the first argument that could not +be obtained. The following values are defined as standard arguments. +Other values are implementation dependent. + + + + + + + + + + Name + Type + Description + + + + + XlcNName + char* + charset name + + + XlcNEncodingName + char* + XLFD CharSet Registry and Encoding + + + XlcNSide + XlcSide + charset side (GL, GR, ...) + + + XlcNCharSize + int + number of octets per character + + + XlcNSetSize + int + number of character sets + + + XlcNControlSequence + char* + control sequence of Compound Text + + + + + + + + +Converter Functions + +We provide a set of the common converter APIs, that are independent +from both of source and destination text type. + + + +typedef struct _XlcConvRec *XlcConv; + +typedef void (*XlcCloseConverterProc)(conv); + XlcConv conv; + +typedef int (*XlcConvertProc)(conv, from, from_left, to, to_left, args, num_args); + XlcConv conv; + XPointer *from; + int *from_left; + XPointer *to; + int *to_left; + XPointer *args; + int num_args; + +typedef void (*XlcResetConverterProc)(conv); + XlcConv conv; + +typedef struct _XlcConvMethodsRec { + XlcCloseConverterProc close; + XlcConvertProc convert; + XlcResetConverterProc reset; +} XlcConvMethodsRec, *XlcConvMethods; + +typedef struct _XlcConvRec { + XlcConvMethods methods; + XPointer state; +} XlcConvRec; + + + +Open a converter + + + + + XlcConv _XlcOpenConverter + XLCd from_lcd + char *from_type + XLCd to_lcd + char *to_type + + + + +_XlcOpenConverter +function opens the converter which converts a text from specified +"from_type" to specified "to_type" encoding. If the +function cannot find proper converter or cannot open a corresponding +converter, it returns NULL. Otherwise, it returns the conversion +descriptor. + + + +The following types are pre-defined. Other types are implementation +dependent. + + + + + + + + + + + Name + Type + Description + Arguments + + + + + XlcNMultiByte + char * + multibyte + - + + + XlcNWideChar + wchar_t * + wide character + - + + + XlcNCompoundText + char * + COMPOUND_TEXT + - + + + XlcNString + char * + STRING + - + + + XlcNCharSet + char * + per charset + XlcCharSet + + + XlcNChar + char * + per character + XlcCharSet + + + + + + +Close a converter + + + + + void _XlcCloseConverter + XlcConv conv + + + + +The +_XlcCloseConverter +function closes the specified converter "conv". + + + +Code conversion + + + + + int _XlcConvert + XlcConv conv + XPointer *from + int *from_left + XPointer *to + int *to_left + XPointer *args + int num_args + + + + +The +_XlcConvert +function converts a sequence of characters from one type, in the array +specified by "from", into a sequence of corresponding characters +in another type, in the array specified by "to". The types are +those specified in the +_XlcOpenConverter() +call that returned the conversion descriptor, "conv". +The arguments "from", "from_left", "to" and +"to_left" have the same specification of XPG4 iconv function. + + + +For state-dependent encodings, the conversion descriptor "conv" +is placed into its initial shift state by a call for which "from" +is a NULL pointer, or for which "from" points to a null pointer. + + + +The following 2 converters prepared by locale returns appropriate +charset (XlcCharSet) in an area pointed by args[0]. + + + + + + + + + + From + To + Description + + + + + XlcNMultiByte + XlcNCharSet + Segmentation (Decomposing) + + + XlcNWideChar + XlcNCharSet + Segmentation (Decomposing) + + + + + + +The conversion, from XlcNMultiByte/XlcNWideChar to XlcNCharSet, +extracts a segment which has same charset encoding characters. +More than one segment cannot be converted in a call. + + + +Reset a converter + + + + + void _XlcResetConverter + XlcConv conv + + + + +The +_XlcResetConverter +function reset the specified converter "conv". + + + +Register a converter + + + +typedef XlcConv (*XlcOpenConverterProc)(from_lcd, from_type, to_lcd, to_type); + XLCd from_lcd; + char *from_type; + XLCd to_lcd; + char *to_type; + + + + + Bool _XlcSetConverter + XLCd from_lcd + char *from + XLCd to_lcd + char *to + XlcOpenConverterProc converter + + + + +The XlcSetConverter function registers a converter which convert +from "from_type" to "to_type" into the converter list +(in the specified XLCd). + + + + +X Locale Database functions + +X Locale Database contains the subset of user's environment that +depends on language. The following APIs are provided for accessing +X Locale Database and other locale relative files. + + + +For more detail about X Locale Database, please refer +X Locale Database Definition document. + + + +Get a resource from database + + + + + void _XlcGetResource + XLCd lcd + char *category + char *class + char ***value + int *count + + + + +The +_XlcGetResource +function obtains a locale dependent data which is associated with the +locale of specified "lcd". +The locale data is provided by system locale or by X Locale Database +file, and what kind of data is available is implementation dependent. + + + +The specified "category" and "class" are used for +finding out the objective locale data. + + + +The returned value is returned in value argument in string list form, +and the returned count shows the number of strings in the value. + + + +The returned value is owned by locale method, and should not be modified +or freed by caller. + + + +Get a locale relative file name + + + + + char *_XlcFileName + XLCd lcd + char *category + + + + +The +_XlcFileName +functions returns a file name which is bound to the specified "lcd" +and "category", as a null-terminated string. If no file name can +be found, or there is no readable file for the found file name, +_XlcFileName +returns NULL. The returned file name should be freed by caller. + + + +The rule for searching a file name is implementation dependent. +In current implementation, +_XlcFileName +uses "{category}.dir" file as mapping table, which has pairs of +strings, a full locale name and a corresponding file name. + + + + + +Utility Functions + + +Compare Latin-1 strings + + + + + int _XlcCompareISOLatin1 + char*str1, *str2 + + + + + + int _XlcNCompareISOLatin1 + char*str1, *str2 + int len + + + + +The +_XlcCompareIsoLatin1 +function to compares two ISO-8859-1 strings. Bytes representing ASCII lower +case letters are converted to upper case before making the comparison. +The value returned is an integer less than, equal to, or greater than +zero, depending on whether "str1" is lexicographicly less than, +equal to, or greater than "str2". + + + +The +_XlcNCompareIsoLatin1 +function is identical to +_XlcCompareISOLatin1, +except that at most "len" bytes are compared. + + + +Resource Utility + + + + + int XlcNumber + ArrayType array + + + + +Similar to XtNumber. + + + + + void _XlcCopyFromArg + char *src + char *dst + int size + + + + + + void _XlcCopyToArg + char *src + char **dst + int size + + + + +Similar to +_XtCopyFromArg +and +_XtCopyToArg. + + + + + void _XlcCountVaList + va_list var + int *count_ret + + + + +Similar to +_XtCountVaList. + + + + + void _XlcVaToArgList + va_list var + int count + XlcArgList *args_ret + + + + +Similar to +_XtVaToArgList. + + + +typedef struct _XlcResource { + char *name; + XrmQuark xrm_name; + int size; + int offset; + unsigned long mask; +} XlcResource, *XlcResourceList; + + + +#define XlcCreateMask (1L<<0) +#define XlcDefaultMask (1L<<1) +#define XlcGetMask (1L<<2) +#define XlcSetMask (1L<<3) +#define XlcIgnoreMask (1L<<4) + + + + + void _XlcCompileResourceList + XlcResourceList resources + int num_resources + + + + +Similar to +_XtCompileResourceList. + + + + + char * _XlcGetValues + XPointer base + XlcResourceList resources + int num_resources + XlcArgList args + int num_args + unsignedlong mask + + + + +Similar to XtGetSubvalues. + + + + + char * _XlcSetValues + XPointer base + XlcResourceList resources + int num_resources + XlcArgList args + int num_args + unsignedlong mask + + + + +Similar to XtSetSubvalues. + + + +ANSI C Compatible Functions + + + +The following are ANSI C/MSE Compatible Functions for non-ANSI C environment. + + + + + int _Xmblen + char *str + int len + + + + +The +_Xmblen +function returns the number of characters pointed to by "str". +Only "len" bytes in "str" are used in determining the +character count returned. "Str" may point at characters from +any valid codeset in the current locale. + + + +The call +_Xmblen +is equivalent to +_Xmbtowc(_Xmbtowc((wchar_t*)NULL, str, len)) + + + + + int _Xmbtowc + wchar_t *wstr + char *str + int len + + + + +The +_Xmbtowc +function converts the character(s) pointed to by "str" +to their wide character representation(s) pointed to by "wstr". +"Len" is the number of bytes in "str" to be converted. +The return value is the number of characters converted. + + + +The call +_Xmbtowc +is equivalent to +_Xlcmbtowc((XLCd)NULL, wstr, str, len) + + + + + int _Xlcmbtowc + XLCd lcd + wchar_t *wstr + char *str + int len + + + + +The +_Xlcmbtowc +function is identical to +_Xmbtowc, +except that it requires the "lcd" argument. If "lcd" +is (XLCd) NULL, +_Xlcmbtowc, +calls +_XlcCurrentLC +to determine the current locale. + + + + + int _Xwctomb + char *str + wchar_t wc + + + + +The +_Xwctomb +function converts a single wide character pointed to by "wc" to +its multibyte representation pointed to by "str". +On success, the return value is 1. + + + +The call +_Xwctomb +is equivalent to +_Xlcwctomb((XLCd)NULL, str, wstr) + + + + + int _Xlcwctomb + XLCd lcd + char *str + wchar_t wc + + + + +The +_Xlcwctomb +function is identical to _Xwctomb, except that it requires the +"lcd" argument. If "lcd" is (XLCd) NULL, +_Xlcwctomb, +calls +_XlcCurrentLC +to determine the current locale. + + + + + int _Xmbstowcs + wchar_t *wstr + char *str + int len + + + + +The +_Xmbstowcs +function converts the NULL-terminated string pointed to by "str" +to its wide character string representation pointed to by "wstr". +"Len" is the number of characters in "str" to be converted. + + + +The call +_Xmbstowcs +is equivalent to +_Xlcmbstowcs((XLCd)NULL, wstr, str, len) + + + + + int _Xlcmbstowcs + XLCd lcd + wchar_t *wstr + char *str + int len + + + + +The +_Xlcmbstowcs +function is identical to _Xmbstowcs, except that it requires the +"lcd" argument. If "lcd" is (XLCd) NULL, +_Xlcmbstowcs, +calls +_XlcCurrentLC +to determine the current locale. + + + + + int _Xwcstombs + char *str + wchar_t *wstr + int len + + + + +The +_Xwcstombs +function converts the (wchar_t) NULL terminated wide character string +pointed to by "wstr" to the NULL terminated multibyte string +pointed to by "str". + + + +The call +_Xwcstombs +is equivalent to +_Xlcwcstombs((XLCd)NULL, str, wstr, len) + + + + + int _Xlcwcstombs + XLCd lcd + char *str + wchar_t *wstr + int len + + + + +The +_Xlcwcstombs +function is identical to _Xwcstombs, except that it requires the +"lcd" argument. If "lcd" is (XLCd) NULL, +_Xlcwcstombs, +calls +_XlcCurrentLC +to determine the current locale. + + + + + int _Xwcslen + wchar_t *wstr + + + + +The +_Xwcslen +function returns the count of wide characters in the (wchar_t) NULL +terminated wide character string pointed to by "wstr". + + + + + wchar_t * _Xwcscpy + wchar_t *wstr1 + wchar_t *wstr2 + + + + + + wchar_t * _Xwcsncpy + wchar_t *wstr1 + wchar_t *wstr2 + int len + + + + +The +_Xwcscpy +function copies the (wchar_t) NULL terminated wide character string +pointed to by "wstr2" to the object pointed at by "wstr1". +"Wstr1" is (wchar_t) NULL terminated. The return value is a +pointer to "wstr1". + + + +The +_Xwcsncpy +function is identical to +_Xwcscpy, +except that it copies "len" wide characters from the object +pointed to by "wstr2" to the object pointed to "wstr1". + + + + + int _Xwcscmp + wchar_t*wstr1, *wstr2 + + + + + + int _Xwcsncmp + wchar_t*wstr1, *wstr2 + int len + + + + +The +_Xwcscmp +function compares two (wchar_t) NULL terminated wide character strings. +The value returned is an integer less than, equal to, or greater than zero, +depending on whether "wstr1" is lexicographicly less then, equal to, +or greater than "str2". + + + +The +_Xwcsncmp +function is identical to +_XlcCompareISOLatin1, +except that at most "len" wide characters are compared. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/libX11/specs/i18n/localedb/Makefile.am b/libX11/specs/i18n/localedb/Makefile.am new file mode 100644 index 000000000..99b5086da --- /dev/null +++ b/libX11/specs/i18n/localedb/Makefile.am @@ -0,0 +1,32 @@ +# +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS 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. +# + +if ENABLE_SPECS + +specdir = $(docdir)/$(subdir) +doc_sources = localedb.xml +dist_spec_DATA = $(doc_sources) + +include $(top_srcdir)/specs/xmlrules.in + +endif ENABLE_SPECS diff --git a/libX11/specs/i18n/localedb/localedb.xml b/libX11/specs/i18n/localedb/localedb.xml new file mode 100644 index 000000000..e5b96ab84 --- /dev/null +++ b/libX11/specs/i18n/localedb/localedb.xml @@ -0,0 +1,777 @@ + + + + + + + X Locale Database Specification + + + YoshioHoriuchi + IBM Japan + + + 1994IBM Corporation + 1994X Consortium + + + + + +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. + + +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. + + + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files +(the “Software”), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to permit +persons to whom the Software is furnished to do so, subject to the following +conditions: + + + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + + + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN +NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + + + +Except as contained in this notice, the name of The 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. + + +X Window System is a trademark of The Open Group. + + + + + +LocaleDB + + +General + +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. + + + +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. + + + +This document describes; + + + + + +Database Format Definition + + + + +Contents of Database in sample implementation + + + + + + +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. + + + + +Database Format Definition + +The X Locale Database contains one or more category definitions. +This section describes the format of each category definition. + + + +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 (}). + + + +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. + + + +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(}). + + + +The format of category definition is; + + + + + + + + + + CategoryDefinition + ::= + CategoryHeader CategorySpec CategoryTrailer + + + CategoryHeader + ::= + CategoryName NL + + + CategorySpec + ::= + { ClassSpec } + + + CategoryTrailer + ::= + "END" Delimiter CategoryName NL + + + CategoryName + ::= + String + + + ClassSpec + ::= + ClassName Delimiter ClassValue NL + + + ClassName + ::= + String + + + ClassValue + ::= + ValueList | "{" NL { ClassSpec } "}" + + + ValueList + ::= + Value | Value ";" ValueList + + + Value + ::= + ValuePiece | ValuePiece Value + + + ValuePiece + ::= + String | QuotedString | NumericString + + + String + ::= + Char { Char } + + + QuotedString + ::= + """ QuotedChar { QuotedChar } """ + + + NumericString + ::= + "\\o" OctDigit { OctDigit } + + + + | + "\\d" DecDigit { DecDigit } + + + + | + "\\x" HexDigit { HexDigit } + + + Char + ::= + <XPCS except NL, Space or unescaped reserved symbols> + + + QuotedChar + ::= + <XPCS except unescaped """> + + + OctDigit + ::= + <character in the range of "0" - "7"> + + + DecDigit + ::= + <character in the range of "0" - "9"> + + + HexDigit + ::= + <character in the range of "0" - "9", "a" - "f", "A" - "F"> + + + Delimiter + ::= + Space { Space } + + + Space + ::= + <space> | <horizontal tab> + + + NL + ::= + <newline> + + + + + + +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. + + + +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. + + + + +Contents of Database + +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. + + + +In current sample implementation, categories listed below are available. + + + + + + + + + XLC_FONTSET:XFontSet relative information + + + XLC_XLOCALE:Character classification and conversion information + + + + + + + +XLC_FONTSET Category + +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). + + + + + + + + + + class + super class + description + + + + + fsN + + Nth fontset (N=0,1,2, ...) + + + charset + fsN + list of encoding name + + + font + fsN + list of font encoding name + + + + + + + + fsN + + +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'. + + + + + charset + + +Specifies an encoding information to be used internally in Xlib +for this fontset. The format of value is; + + + + + + + + + EncodingInfo + ::= + EncodingName [ ":" EncodingSide ] + + + EncodingName + ::= + CHARSET_REGISTRY-CHARSET_ENCODING + + + EncodingSide + ::= + "GL" | "GR" + + + + + + +For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer +"X Logical Font Descriptions" document. + + +example: + ISO8859-1:GL + + + + + font + + +Specifies a list of encoding information which is used for searching +appropriate font for this fontset. The left most entry has highest +priority. + + + + + + + +XLC_XLOCALE Category + +The XLC_XLOCALE category defines character classification, conversion +and other character attributes. + + + + + + + + + + class + super class + description + + + + + encoding_name + + codeset name + + + mb_cur_max + + MB_CUR_MAX + + + state_depend_encoding + + state dependent or not + + + wc_encoding_mask + + for parsing wc string + + + wc_shift_bits + + for conversion between wc and mb + + + csN + + Nth charset (N=0,1,2,...) + + + side + csN + mapping side (GL, etc) + + + length + csN + length of a character + + + mb_encoding + csN + for parsing mb string + + + wc_encoding + csN + for parsing wc string + + + ct_encoding + csN + list of encoding name for ct + + + + + + + + encoding_name + + +Specifies a codeset name of current locale. + + + + + mb_cur_max + + +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". + + + + + state_depend_encoding + + +Indicates a current locale is state dependent. The value should be +specified "True" or "False". + + + + + wc_encoding_mask + + +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'. + + + + + wc_shift_bits + + +Specifies a number of bit to be shifted for converting from a multi-byte +character to a wide character, and vice-versa. + + + + + csN + + + +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'. + + + + + side + + +Specifies a mapping side of this charset. The format of this value is; + + + Side ::= EncodingSide[":Default"] + + +The suffix ":Default" can be specified. It indicates that a character +belongs to the specified side is mapped to this charset in initial state. + + + + + length + + + +Specifies a number of bytes of a multi-byte character of this charset. +It should not contain the length of any single-shift sequence. + + + + + mb_encoding + + +Specifies a list of shift sequence for parsing multi-byte string. +The format of this value is; + + + + + + + + + MBEncoding + ::= + ShiftType ShiftSequence + + + + | + ShiftType ShiftSequence ";" MBEncoding + + + ShiftType + ::= + "<SS>"|"<LSL>"|"<LSR>" + + + ShiftSequence + ::= + SequenceValue|SequenceValue ShiftSequence + + + SequenceValue + ::= + NumericString + + + + + + +example: + <LSL> \x1b \x28 \x4a; <LSL> \x1b \x28 \x42 + + + + + wc_encoding + + +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. + + + + + ct_encoding + + +Specifies a list of encoding information that can be used for Compound +Text. + + + + + + + +Sample of X Locale Database + +The following is sample X Locale Database file. + + + +# 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 + + + + +Reference + +[1] ISO/IEC 9899:1990 C Language Standard + + +[2] X Logical Font Descriptions + + + + + diff --git a/libX11/specs/i18n/trans/Makefile.am b/libX11/specs/i18n/trans/Makefile.am new file mode 100644 index 000000000..dfdf34f05 --- /dev/null +++ b/libX11/specs/i18n/trans/Makefile.am @@ -0,0 +1,32 @@ +# +# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved. +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS 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. +# + +if ENABLE_SPECS + +specdir = $(docdir)/$(subdir) +doc_sources = trans.xml +dist_spec_DATA = $(doc_sources) + +include $(top_srcdir)/specs/xmlrules.in + +endif ENABLE_SPECS diff --git a/libX11/specs/i18n/trans/trans.xml b/libX11/specs/i18n/trans/trans.xml new file mode 100644 index 000000000..9a01d97f6 --- /dev/null +++ b/libX11/specs/i18n/trans/trans.xml @@ -0,0 +1,1979 @@ + + + + + + + The XIM Transport Specification + Revision 0.1 + X Version 11, Release 7 + + + TakashiFujiwara + FUJITSU LIMITED + + + 1994FUJITSU LIMITED + 1994X Consortium + + Revision 0.1 + + + + +This specification describes the transport layer interfaces between Xlib and IM Server, +which makes various channels usable such as X protocol or TCP/IP, DECnet and etc. + + + + + + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files +(the “Software”), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to permit +persons to whom the Software is furnished to do so, subject to the following +conditions: + + + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + + + +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN +NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + + + +Except as contained in this notice, the name of The 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. + + +X Window System is a trademark of The Open Group. + + + + + +X Transport Specification + + +Introduction + + + + + +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: + + + + + The protocol layer + + +implements overall function of XIM and calls the interface layer +functions when it needs to communicate to IM Server. + + + + + The interface layer + + +separates the implementation of the transport layer from the protocol +layer, in other words, it provides implementation independent hook for +the transport layer functions. + + + + + + The transport layer + + +handles actual data communication with IM Server. It is done by a set +of several functions named transporters. + + + + + + +This specification describes the interface layer and the transport +layer, which makes various communication channels usable such as +X protocol or, TCP/IP, DECnet, STREAM, etc., and provides +the information needed for adding another new transport layer. +In addition, sample implementations for the transporter using the +X connection is described in section 4. + + + + +Initialization + + +Registering structure to initialize + + +The structure typed as TransportSW contains the list of the transport +layer the specific implementations supports. + + + +typedef struct { + char *transport_name; + Bool (*config); +} TransportSW; + + + + + + + + + transport_name + name of transportRefer to "The Input Method Protocol: Appendix B + + + config + initial configuration function + + + + + + +A sample entry for the Xlib supporting transporters is shown below: + + + +TransportSW _XimTransportRec[] = { +/* char *: + * transport_name, Bool (*config)() + */ + "X", _XimXConf, + "tcp", _XimTransConf, + "local", _XimTransConf, + "decnet", _XimTransConf, + "streams", _XimTransConf, + (char *)NULL, (Bool (*)())NULL, +}; + + + + +Initialization function + + + + +The following function will be called once when Xlib configures the +transporter functions. + + + + + Bool (*config) + XIM im + char *transport_data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + transport_data + + + +Specifies the data specific to the transporter, in IM Server address.Refer to "The Input Method Protocol: Appendix B + + + + + + +This function must setup the transporter function pointers. + + + + +The actual config function will be chosen by IM Server at the +pre-connection time, matching by the transport_name specified +in the _XimTransportRec array; The specific members of XimProto +structure listed below must be initialized so that point they +appropriate transporter functions. + + + +If the specified transporter has been configured successfully, this +function returns True. There is no Alternative Entry for config +function itself. + + + +The structure XimProto contains the following function pointers: + + + +Bool (*connect)(); /* Open connection */ +Bool (*shutdown)(); /* Close connection */ +Bool (*write)(); /* Write data */ +Bool (*read)(); /* Read data */ +Bool (*flush)(); /* Flush data buffer */ +Bool (*register_dispatcher)(); /* Register asynchronous data handler */ +Bool (*call_dispatcher)(); /* Call dispatcher */ + + + +These functions are called when Xlib needs to communicate the +IM Server. These functions must process the appropriate procedure +described below. + + + + + +The interface/transport layer functions + +Following functions are used for the transport interface. + + + + The Transport Layer Functions + + + + + + + Alternate Entry (Interface Layer) + XimProto member (Transport Layer) + Section + + + + + _XimConnect + connect + 3.1 + + + _XimShutdown + shutdown + 3.2 + + + _XimWrite + write + 3.3 + + + _XimRead + read + 3.4 + + + _XimFlush + flush + 3.5 + + + _XimRegisterDispatcher + register_dispatcher + 3.6 + + + _XimCallDispatcher + call_dispatcher + 3.7 + + + +
+ + +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. + + + +Opening connection + + +When XOpenIM is called, the following function is called to connect +with the IM Server. + + + + + Bool (*connect) + XIM im + + + + + + + im + + + +Specifies XIM structure address. + + + + + + +This function must establishes the connection to the IM Server. If the +connection is established successfully, this function returns True. +The Alternative Entry for this function is: + + + + + Bool _XimConnect + XIM im + + + + + + + im + + + +Specifies XIM structure address. + + + + + + + +Closing connection + + + + + +When XCloseIM is called, the following function is called to +disconnect the connection with the IM Server. The Alternative Entry +for this function is: + + + + + Bool (*shutdown) + XIM im + + + + + + + im + + + +Specifies XIM structure address. + + + + + + + +This function must close connection with the IM Server. If the +connection is closed successfully, this function returns True. The +Alternative Entry for this function is: + + + + + Bool _XimShutdown + XIM im + + + + + + + im + + + +Specifies XIM structure address. + + + + + + + + +Writing data + +The following function is called, when Xlib needs to write data to the +IM Server. + + + + + Bool _XimWrite + XIM im + INT16 len + XPointer data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + len + + + +Specifies the length of writing data. + + + + + + data + + + +Specifies the writing data. + + + + + + +This function writes the data to the IM Server, regardless +of the contents. The number of bytes is passed to len. The +writing data is passed to data. 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: + + + + + Bool _XimWrite + XIM im + INT16 len + XPointer data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + len + + + +Specifies the length of writing data. + + + + + + data + + + +Specifies the writing data. + + + + + + + +Reading data + +The following function is called when Xlib waits for response from IM +server synchronously. + + + + + Bool _XimRead + XIM im + XPointer read_buf + int buf_len + int *ret_len + + + + + + + im + + + +Specifies XIM structure address. + + + + + + read_buf + + + +Specifies the buffer to store data. + + + + + + buf_len + + + +Specifies the size of the buffer + + + + + + ret_len + + + +Specifies the length of stored data. + + + + + + +This function stores the read data in read_buf, which size is +specified as buf_len. The size of data is set to ret_len. +This function return True, if the data is read normally or reading +data is completed. + + +The Alternative Entry for this function is: + + + + + Bool _XimRead + XIM im + INT16 *ret_len + XPointer buf + int buf_len + Bool (*predicate)() + XPointer predicate_arg + + + + + + + im + + + +Specifies XIM structure address. + + + + + + ret_len + + + +Specifies the size of the data buffer. + + + + + + buf + + + +Specifies the buffer to store data. + + + + + + buf_len + + + +Specifies the length of buffer. + + + + + + predicate + + + +Specifies the predicate for the XIM data. + + + + + + predicate_arg + + + +Specifies the predicate specific data. + + + + + + + +The predicate procedure indicates whether the data is for the +XIM or not. len +This function stores the read data in buf, which size +is specified as buf_len. The size of data is set to +ret_len. If preedicate() +returns True, this function returns True. If not, it calls the registered callback function. + + + +The procedure and its arguments are: + + + + + + void (*predicate) + XIM im + INT16 len + XPointer data + XPointer predicate_arg + + + + + + + im + + + +Specifies XIM structure address. + + + + + + len + + + +Specifies the size of the data buffer. + + + + + + data + + + +Specifies the buffer to store data. + + + + + + predicate_arg + + + +Specifies the predicate specific data. + + + + + + + +Flushing buffer + +The following function is called when Xlib needs to flush the data. + + + + + void (*flush) + XIM im + + + + + + + im + + + +Specifies XIM structure address. + + + + + + +This function must flush the data stored in internal buffer on the +transport layer. If data transfer is completed, the function returns +True. The Alternative Entry for this function is: + + + + + void _XimFlush + XIM im + + + + + + + im + + + +Specifies XIM structure address. + + + + + + + +Registering asynchronous data handler + +Xlib needs to handle asynchronous response from IM Server. This is +because some of the XIM data occur asynchronously to X events. + + + +Those data will be handled in the Filter, +and the Filter +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 +_XimCallDispatcher. + + + +When multiple dispatchers are registered, they will be called +sequentially in order of registration, on arrival of asynchronous +data. The register_dispatcher is declared as following: + + + + + Bool (*register_dispatcher) + XIM im + Bool (*dispatcher)() + XPointer call_data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + dispatcher + + + +Specifies the dispatcher function to register. + + + + + + call_data + + + +Specifies a parameter for the dispatcher. + + + + + + +The dispatcher is a function of the following type: + + + + + Bool (*dispatcher) + XIM im + INT16 len + XPointer data + XPointer call_data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + len + + + +Specifies the size of the data buffer. + + + + + + data + + + +Specifies the buffer to store data. + + + + + + call_data + + + +Specifies a parameter passed to the register_dispatcher. + + + + + + +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. + + + +If the dispatcher function returns True, the Transport Layer assume +that the data has been processed by the upper layer. The Alternative +Entry for this function is: + + + + + Bool _XimRegisterDispatcher + XIM im + Bool (*dispatcher)() + XPointer call_data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + dispatcher + + + +Specifies the dispatcher function to register. + + + + + + call_data + + + +Specifies a parameter for the dispatcher. + + + + + + + +Calling dispatcher + +The following function is used to call the registered dispatcher +function, when the asynchronous response from IM Server has arrived. + + + + + Bool (*call_dispatcher) + XIM im + INT16 len + XPointer data + + + + + + + im + + + +Specifies XIM structure address. + + + + + + len + + + +Specifies the size of data buffer. + + + + + + data + + + +Specifies the buffer to store data. + + + + + + +The call_dispatcher must call the dispatcher function, in order of +their registration. len and data are the data passed to +register_dispatcher. + + + +The return values are checked at each invocation, and if it finds +True, it immediately return with true for its return value. + + + +It is depend on the upper layer whether the read data is XIM +Protocol packet unit or not. +The Alternative Entry for this function is: + + + + + Bool _XimCallDispatcher + XIM im + INT16 len + XPointer call_data + + + + + + +Sample implementations for the Transport Layer + +Sample implementations for the transporter using the X connection is +described here. + + + +X Transport + +At the beginning of the X Transport connection for the XIM transport +mechanism, two different windows must be created either in an Xlib XIM +or in an IM Server, with which the Xlib and the IM Server exchange the +XIM transports by using the ClientMessage events and Window Properties. +In the 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". + + + +Connection + +In order to establish a connection, a communication window is created. +A ClientMessage in the following event's format is sent to the owner +window of XIM_SERVER selection, which the IM Server has created. + + + + +Refer to "The Input Method Protocol" for the XIM_SERVER atom. + + + + The ClientMessage sent to the IMS window. + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_CONNECT", false) + + + int + format + 32 + + + long + data.1[0] + client communication window ID + + + long + data.1[1] + client-major-transport-version(*1) + + + long + data.1[2] + client-major-transport-version(*1) + + + +
+ + +In order to establish the connection (to notify the IM Server communication +window), the IM Server sends a ClientMessage in the following event's +format to the client communication window. + + + + The ClientMessage sent by IM Server. + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_CONNECT", false) + + + int + format + 32 + + + long + data.1[0] + client communication window ID + + + long + data.1[1] + client-major-transport-version(*1) + + + long + data.1[2] + client-major-transport-version(*1) + + + long + data.1[3] + dividing size between ClientMessage and Property(*2) + + + +
+ + +(*1) major/minor-transport-version + + + +The read/write method is decided by the combination of +major/minor-transport-version, as follows: + + + +The read/write method and the major/minor-transport-version + + + + + + + + Transport-version + read/write + + + major + minor + + + + + + 0 + 0 + only-CM & Property-with-CM + + + 1 + only-CM & multi-CM + + + 2 + only-CM & multi-CM & Property-with-CM + + + 1 + 0 + PropertyNotify + + + 2 + 0 + only-CM & PropertyNotify + + + 1 + only-CM & multi-CM & PropertyNotify + + + +
+ + +only-CM : data is sent via a ClientMessage +multi-CM : data is sent via multiple ClientMessages +Property-with-CM : data is written in Property, and its Atom + is send via ClientMessage +PropertyNotify : data is written in Property, and its Atom + is send via PropertyNotify + + + + + +The method to decide major/minor-transport-version is as follows: + + + + + +The client sends 0 as major/minor-transport-version to the IM Server. +The client must support all methods in Table 4-3. +The client may send another number as major/minor-transport-version to +use other method than the above in the future. + + + + +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. + + + + +If major/minor-transport-version number is not available, it is regarded +as 0. + + + + + +(*2) dividing size between ClientMessage and Property + + + +If data is sent via both of multi-CM and Property, specify the dividing +size between ClientMessage and Property. The data, which is smaller than +this size, is sent via multi-CM (or only-CM), and the data, which is +lager than this size, is sent via Property. + + + + + +read/write + +The data is transferred via either ClientMessage or Window Property in +the X Window System. + + + +Format for the data from the Client to the IM Server + +ClientMessage + + + +If data is sent via ClientMessage event, the format is as follows: + + + + The ClientMessage event's format (first or middle) + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_MOREDATA", False) + + + int + format + 8 + + + char + data.b[20] + (read/write DATA : 20 byte) + + + +
+ + + + + The ClientMessage event's format (only or last) + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_PROTOCOL", False) + + + int + format + 8 + + + char + data.b[20] + (read/write DATA : MAX 20 byte) +If the data is smaller +than 20 bytes, all data other than available data must be 0. + + + + + +
+ + +Property + + + +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. + + + + + +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. + + + + +The XChangeProperty function is used to store data in the client +communication window, and Atom of the stored data is notified to the +IM Server via PropertyNotify event. + + + + + +The arguments of the XChangeProperty are as follows: + + + + + The XChangeProperty event's format + + + + + + + + Argument + Contents + + + + + Display + *display + The display to which connects + + + Window + window + IMS communication window ID + + + Atom + property + read/write property Atom (*1) + + + int + format + 8 + + + int + mode + PropModeAppend + + + u_char + *data + read/write DATA + + + int + nelements + length of DATA + + + +
+ + +(*1) The read/write property ATOM allocates the following strings by +XInternAtom. +"_clientXXX" + + + +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). + + + +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: + + + + The ClientMessage event's format to send Atom of property + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_PROTOCOL", False) + + + int + format + 8 + + + long + data.1[0] + length of read/write property Atom + + + long + data.1[1] + read/write property Atom + + + +
+ + + +Format for the data from the IM Server to the Client + +ClientMessage + + + +The format of the ClientMessage is as follows: + + + + The ClientMessage event's format (first or middle) + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_MOREDATA", False) + + + int + format + 8 + + + char + data.b[20] + (read/write DATA : 20 byte) + + + +
+ + + + + + + The ClientMessage event's format (only or last) + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_PROTOCOL", False) + + + int + format + 8 + + + char + data.b[20] + (read/write DATA : MAX 20 byte) (*1) + + + +
+ + +(*1) If the data size is smaller than 20 bytes, all data other than available +data must be 0. + + + +Property + + + +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. + + + + + +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via the +ClientMessage event. + + + + +The XChangeProperty function is used to store data in the IMS +communication window, and Atom of the property is sent via +PropertyNotify event. + + + + + +The arguments of the XChangeProperty are as follows: + + + + The XChangeProperty event's format + + + + + + + + Argument + Contents + + + + + Display + *display + The display to which connects + + + Window + window + IMS communication window ID + + + Atom + property + read/write property Atom (*1) + + + int + format + 8 + + + int + mode + PropModeAppend + + + u_char + *data + read/write DATA + + + int + nelements + length of DATA + + + +
+ + +(*1) The read/write property ATOM allocates some strings, which are not +allocated by the client, by XInternAtom. + + + +The IM Server changes the property with the mode of PropModeAppend and +the client reads it with the delete mode, i.e. (delete = True). + + + +If Atom is notified via ClientMessage event, the format of the ClientMessage +is as follows: + + + + The ClientMessage event's format to send Atom of property + + + + + + + + Structure Member + Contents + + + + + int + type + ClientMessage + + + u_long + serial + Set by the X Window System + + + Bool + send_event + Set by the X Window System + + + Display + *display + The display to which connects + + + Window + window + IMS Window ID + + + Atom + message_type + XInternAtom(display, "_XIM_PROTOCOL", False) + + + int + format + 8 + + + long + data.1[0] + length of read/write property Atom + + + long + data.1[1] + read/write property Atom + + + +
+ + + + +Closing Connection + + +If the client disconnect with the IM Server, shutdown function should +free the communication window properties and etc.. + + + + + + + +References + +[1] Masahiko Narita and Hideki Hiura, "The Input Method Protocol" + + + + + -- cgit v1.2.3