# X11R6 Sample Implementation Frame Work

X Version 11, Release &fullrelvers;
Katsuhisa
Yano
TOSHIBA Corporation
Yoshio
Horiuchi
IBM Japan
1994
TOSHIBA Corporation
IBM 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.

Copyright © 1994 X Consortium

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 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 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 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 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 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 function opens a locale method which corresponds to the specified locale name. 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, returns the XLCd. If the loader is invalid or failed to open a locale, calls the next loader. If all registered loaders cannot open a locale, 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 function close a locale method the specified lcd.

Obtain Locale Method values

      char *_XGetLCValues
      XLCd lcd

The 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 function gets an XlcCharSet which corresponds to the charset name specified by "name". 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 function registers XlcCharSet specified by "charset".

`Obtain Character Set values`

      char *  _XlcGetCSValues
      XlcCharSet charset
       ...

The 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

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 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 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 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 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 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, returns NULL. The returned file name should be freed by caller.

The rule for searching a file name is implementation dependent. In current implementation, 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 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 is equivalent to _Xmbtowc(_Xmbtowc((wchar_t*)NULL, str, len))

      int  _Xmbtowc
      wchar_t *wstr
      char *str
      int len

The 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 is equivalent to _Xlcmbtowc((XLCd)NULL, wstr, str, len)

      int  _Xlcmbtowc
      XLCd lcd
      wchar_t *wstr
      char *str
      int len

The 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 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 is equivalent to _Xlcwctomb((XLCd)NULL, str, wstr)

      int  _Xlcwctomb
      XLCd lcd
      char *str
      wchar_t wc

The 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 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 is equivalent to _Xlcmbstowcs((XLCd)NULL, wstr, str, len)

      int  _Xlcmbstowcs
      XLCd lcd
      wchar_t *wstr
      char *str
      int len

The 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 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 is equivalent to _Xlcwcstombs((XLCd)NULL, str, wstr, len)

      int  _Xlcwcstombs
      XLCd lcd
      char *str
      wchar_t *wstr
      int len

The 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 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 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 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 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 function is identical to `_XlcCompareISOLatin1,` except that at most "len" wide characters are compared.