X11R6 Sample Implementation Frame Work

Katsuhisa Yano
TOSHIBA Corporation
Yoshio Horiuchi
IBM Japan

Copyright © 1994 by TOSHIBA Corporation
Copyright © 1994 by 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 the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.

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

1. PrefaceThis document proposes to define the structures, methods andtheir signatures that are expected to be common to alllocale dependent functions within the Xlib sampleimplementation. The following illustration (Fig.1) isproposed to outline the separating of the components withinthe sample implementation.... 0.237 5.796 5.24 10.14 ... 0.000i 4.344i 5.003i0.000iFig.1 : Frame Work of Locale Service API ProposalGenerally speaking, the internationalized portion of Xlib(Locale Dependent X, LDX) consists of three objects; locale(LC) , input method (IM) and output method (OM). The LCprovides a set of information that depends on user’slanguage environment. The IM manages text inputing, and theOM manages text drawing. Both IM and OM highly depend on LCdata.In X11R5, there are two sample implementations, Ximp andXsi, for Xlib internationalization. But in bothimplementations, IM and OM actually refer the privateextension of LC. It breaks coexistence of these two sampleimplementations. For example, if a user creates a new OMfor special purpose as a part of Ximp, it will not work withXsi.As a solution of this problem, we propose to define thestandard APIs between these three objects, and define thestructure that are common to these objects.2. Objective• Explain the current X11R6 sample implementation• Document the common set of locale dependent interfaces• Provide more flexible pluggable layer3. Locale Object Binding FunctionsThis chapter describes functions related locale objectbinding for implementing the pluggable layer.A locale loader is an entry point for locale object, whichinstantiates XLCd object and binds locale methods withspecified locale name. The behavior of loader isimplementation dependent. And, what kind of loaders areavailable is also implementation dependent.The loader is called in _XOpenLC, but caller of _XOpenLCdoes not need to care about its inside. For example, if theloader is implemented with dynamic load functions, and thedynamic module is expected to be unloaded when thecorresponding XLCd is freed, close methods of XLCdMethodsshould handle unloading.Initializing a locale loader listvoid _XlcInitLoader()The _XlcInitLoader function initializes the locale loaderlist with vendor specific manner. Each loader is registeredwith calling _XlcAddLoader. The number of loaders and theirorder in the loader list is implementation dependent.Add a loadertypedef XLCd (*XLCdLoadProc)(name);char *name;typedef int XlcPosition;Bool _XlcAddLoader(proc, position)XLCdLoadProc proc;XlcPosition position;The _XlcAddLoader function registers the specified localeloader ‘‘proc’’ to the internal loader list. The positionspecifies that the loader ‘‘proc’’ should be placed in thetop of the loader list(XlcHead) or last(XlcTail).The object loader is called from the top of the loader listin order, when calling time.Remove a loadervoid _XlcRemoveLoader(proc)XLCdLoadProc proc;The _XlcRemoveLoader function removes the locale loaderspecified by ‘‘proc’’ from the loader list.Current implementation provides following locale loaders;_XlcDefaultLoader_XlcGenericLoader_XlcEucLoader_XlcSjisLoader_XlcUtfLoader_XaixOsDynamicLoad4. Locale Method InterfaceThis chapter describes the locale method API, which is a setof accessible functions from both IM and OM parts. Thelocale method API provides the functionalities; obtaininglocale dependent information, handling charset, convertingtext, etc.As a result of using these APIs instead of accessing venderprivate extension of the locale object, we can keep locale,IM and OM independently each other.5. Locale Method FunctionsOpen a Locale MethodXLCd _XOpenLC(name)char *name;The _XOpenLC function opens a locale method whichcorresponds to the specified locale name. _XOpenLC calls alocale object loader, which is registered via_XlcAddLoaderinto is valid and successfully opens a locale,_XOpenLC returns the XLCd. If the loader is invalid orfailed to open a locale, _XOpenLC calls the next loader. Ifall registered loaders cannot open a locale, _XOpenLCreturns NULL.XLCd _XlcCurrentLC()The _XlcCurrentLC function returns an XLCd that are bound tocurrent locale.Close a Locale Methodvoid _XCloseLC(lcd)XLCd lcd;The _XCloseLC function close a locale method the specifiedlcd.Obtain Locale Method valueschar * _XGetLCValues(lcd, ...)XLCd lcd;The _XGetLCValues function returns NULL if no erroroccurred; otherwise, it returns the name of the firstargument that could not be obtained. The following valuesare defined as standard arguments. Other values areimplementation dependent.6. Charset functionsThe XlcCharSet is an identifier which represents a subset ofcharacters (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 XlcCharSetXlcCharSet _XlcGetCharSet(name)char *name;The _XlcGetCharSet function gets an XlcCharSet whichcorresponds to the charset name specified by ‘‘name’’._XlcGetCharSet returns NULL, if no XlcCharSet bound tospecified ‘‘name’’.The following character sets are pre-registered.Add an XlcCharSetBool _XlcAddCharSet(charset)XlcCharSet charset;The _XlcAddCharSet function registers XlcCharSet specifiedby ‘‘charset’’.Obtain Character Set valueschar * _XlcGetCSValues(charset, ...)XlcCharSet charset;The _XlcGetCSValues function returns NULL if no erroroccurred; otherwise, it returns the name of the firstargument that could not be obtained. The following valuesare defined as standard arguments. Other values areimplementation dependent.7. Converter FunctionsWe provide a set of the common converter APIs, that areindependent 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 converterXlcConv _XlcOpenConverter(from_lcd, from_type, to_lcd, to_type)XLCd from_lcd;char *from_type;XLCd to_lcd;char *to_type;_XlcOpenConverter function opens the converter whichconverts a text from specified ‘‘from_type’’ to specified‘‘to_type’’ encoding. If the function cannot find properconverter or cannot open a corresponding converter, itreturns NULL. Otherwise, it returns the conversiondescriptor.The following types are pre-defined. Other types areimplementation dependent.Close a convertervoid _XlcCloseConverter(conv)XlcConv conv;The _XlcCloseConverter function closes the specifiedconverter ‘‘conv’’.Code conversionint _XlcConvert(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;The _XlcConvert function converts a sequence of charactersfrom one type, in the array specified by ‘‘from’’, into asequence of corresponding characters in another type, in thearray specified by ‘‘to’’. The types are those specified inthe _XlcOpenConverter() call that returned the conversiondescriptor, ‘‘conv’’. The arguments ‘‘from’’,‘‘from_left’’, ‘‘to’’ and ‘‘to_left’’ have the samespecification of XPG4 iconv function.For state-dependent encodings, the conversion descriptor‘‘conv’’ is placed into its initial shift state by a callfor which ‘‘from’’ is a NULL pointer, or for which ‘‘from’’points to a null pointer.The following 2 converters prepared by locale returnsappropriate charset (XlcCharSet) in an area pointed byargs[0].The conversion, from XlcNMultiByte/XlcNWideChar toXlcNCharSet, extracts a segment which has same charsetencoding characters. More than one segment cannot beconverted in a call.Reset a convertervoid _XlcResetConverter(conv)XlcConv conv;The _XlcResetConverter function reset the specifiedconverter ‘‘conv’’.Register a convertertypedef XlcConv (*XlcOpenConverterProc)(from_lcd, from_type, to_lcd, to_type);XLCd from_lcd;char *from_type;XLCd to_lcd;char *to_type;Bool _XlcSetConverter(from_lcd, from, to_lcd, to, converter)XLCd from_lcd;char *from;XLCd to_lcd;char *to;XlcOpenConverterProc converter;The XlcSetConverter function registers a converter whichconvert from ‘‘from_type’’ to ‘‘to_type’’ into the converterlist (in the specified XLCd).8. X Locale Database functionsX Locale Database contains the subset of user’s environmentthat depends on language. The following APIs are providedfor accessing X Locale Database and other locale relativefiles.For more detail about X Locale Database, please refer XLocale Database Definition document.Get a resource from databasevoid _XlcGetResource(lcd, category, class, value, count)XLCd lcd;char *category;char *class;char ***value;int *count;The _XlcGetResource function obtains a locale dependent datawhich is associated with the locale of specified ‘‘lcd’’.The locale data is provided by system locale or by X LocaleDatabase file, and what kind of data is available isimplementation dependent.The specified ‘‘category’’ and ‘‘class’’ are used forfinding out the objective locale data.The returned value is returned in value argument in stringlist form, and the returned count shows the number ofstrings in the value.The returned value is owned by locale method, and should notbe modified or freed by caller.Get a locale relative file namechar * _XlcFileName(lcd, category)XLCd lcd;char *category;The _XlcFileName functions returns a file name which isbound to the specified ‘‘lcd’’ and ‘‘category’’, as anull-terminated string. If no file name can be found, orthere is no readable file for the found file name,_XlcFileName returns NULL. The returned file name should befreed by caller.The rule for searching a file name is implementationdependent. In current implementation, _XlcFileName uses‘‘{category}.dir’’ file as mapping table, which has pairs ofstrings, a full locale name and a corresponding file name.9. Utility FunctionsCompare Latin-1 stringsint _XlcCompareISOLatin1(str1, str2)char *str1, *str2;int _XlcNCompareISOLatin1(str1, str2, len)char *str1, *str2;int len;The _XlcCompareIsoLatin1 function to compares two ISO-8859-1strings. Bytes representing ASCII lower case letters areconverted to upper case before making the comparison. Thevalue returned is an integer less than, equal to, or greaterthan zero, depending on whether ‘‘str1’’ is lexicographiclyless than, equal to, or greater than ‘‘str2’’.The _XlcNCompareIsoLatin1 function is identical to_XlcCompareISOLatin1, except that at most ‘‘len’’ bytes arecompared.Resource Utilityint XlcNumber(array)ArrayType array;Similar to XtNumber.void _XlcCopyFromArg(src, dst, size)char *src;char *dst;int size;void _XlcCopyToArg(src, dst, size)char *src;char **dst;int size;Similar to _XtCopyFromArg and _XtCopyToArg.void _XlcCountVaList(var, count_ret)va_list var;int *count_ret;Similar to _XtCountVaList.void _XlcVaToArgList(var, count, args_ret)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;void _XlcCompileResourceList(resources, num_resources)XlcResourceList resources;int num_resources;Similar to _XtCompileResourceList.char * _XlcGetValues(base, resources, num_resources, args, num_args, mask)XPointer base;XlcResourceList resources;int num_resources;XlcArgList args;int num_args;unsigned long mask;Similar to XtGetSubvalues.char * _XlcSetValues(base, resources, num_resources, args, num_args, mask)XPointer base;XlcResourceList resources;int num_resources;XlcArgList args;int num_args;unsigned long mask;Similar to XtSetSubvalues.ANSI C Compatible FunctionsThe following are ANSI C/MSE Compatible Functions fornon-ANSI C environment.int _Xmblen(str, len)char *str;int len;The _Xmblen function returns the number of characterspointed to by ‘‘str’’. Only ‘‘len’’ bytes in ‘‘str’’ areused in determining the character count returned. ‘‘Str’’may point at characters from any valid codeset in thecurrent locale.The call _Xmblen is equivalent to_Xmbtowc(_Xmbtowc((wchar_t*)NULL, str, len))int _Xmbtowc(wstr, str, len)wchar_t *wstr;char *str;int len;The _Xmbtowc function converts the character(s) pointed toby ‘‘str’’ to their wide character representation(s) pointedto by ‘‘wstr’’. ‘‘Len’’ is the number of bytes in ‘‘str’’to be converted. The return value is the number ofcharacters converted.The call _Xmbtowc is equivalent to_Xlcmbtowc((XLCd)NULL, wstr, str, len)int _Xlcmbtowc(lcd, wstr, str, len)XLCd lcd;wchar_t *wstr;char *str;int len;The _Xlcmbtowc function is identical to _Xmbtowc, exceptthat it requires the ‘‘lcd’’ argument. If ‘‘lcd’’ is (XLCd)NULL, _Xlcmbtowc, calls _XlcCurrentLC to determine thecurrent locale.int _Xwctomb(str, wc)char *str;wchar_t wc;The _Xwctomb function converts a single wide characterpointed to by ‘‘wc’’ to its multibyte representation pointedto by ‘‘str’’. On success, the return value is 1.The call _Xwctomb is equivalent to_Xlcwctomb((XLCd)NULL, str, wstr)int _Xlcwctomb(lcd, str, wc)XLCd lcd;char *str;wchar_t wc;The _Xlcwctomb function is identical to _Xwctomb, exceptthat it requires the ‘‘lcd’’ argument. If ‘‘lcd’’ is (XLCd)NULL, _Xlcwctomb, calls _XlcCurrentLC to determine thecurrent locale.int _Xmbstowcs(wstr, str, len)wchar_t *wstr;char *str;int len;The _Xmbstowcs function converts the NULL-terminated stringpointed to by ‘‘str’’ to its wide character stringrepresentation pointed to by ‘‘wstr’’. ‘‘Len’’ is thenumber of characters in ‘‘str’’ to be converted.The call _Xmbstowcs is equivalent to_Xlcmbstowcs((XLCd)NULL, wstr, str, len)int _Xlcmbstowcs(lcd, wstr, str, len)XLCd lcd;wchar_t *wstr;char *str;int len;The _Xlcmbstowcs function is identical to _Xmbstowcs, exceptthat it requires the ‘‘lcd’’ argument. If ‘‘lcd’’ is (XLCd)NULL, _Xlcmbstowcs, calls _XlcCurrentLC to determine thecurrent locale.int _Xwcstombs(str, wstr, len)char *str;wchar_t *wstr;int len;The _Xwcstombs function converts the (wchar_t) NULLterminated wide character string pointed to by ‘‘wstr’’ tothe NULL terminated multibyte string pointed to by ‘‘str’’.The call _Xwcstombs is equivalent to_Xlcwcstombs((XLCd)NULL, str, wstr, len)int _Xlcwcstombs(lcd, str, wstr, len)XLCd lcd;char *str;wchar_t *wstr;int len;The _Xlcwcstombs function is identical to _Xwcstombs, exceptthat it requires the ‘‘lcd’’ argument. If ‘‘lcd’’ is (XLCd)NULL, _Xlcwcstombs, calls _XlcCurrentLC to determine thecurrent locale.int _Xwcslen(wstr)wchar_t *wstr;The _Xwcslen function returns the count of wide charactersin the (wchar_t) NULL terminated wide character stringpointed to by ‘‘wstr’’.wchar_t * _Xwcscpy(wstr1, wstr2)wchar_t *wstr1, *wstr2;wchar_t * _Xwcsncpy(wstr1, wstr2, len)wchar_t *wstr1, *wstr2;int len;The _Xwcscpy function copies the (wchar_t) NULL terminatedwide character string pointed to by ‘‘wstr2’’ to the objectpointed at by ‘‘wstr1’’. ‘‘Wstr1’’ is (wchar_t) NULLterminated. The return value is a pointer to ‘‘wstr1’’.The _Xwcsncpy function is identical to _Xwcscpy, except thatit copies ‘‘len’’ wide characters from the object pointed toby ‘‘wstr2’’ to the object pointed to ‘‘wstr1’’.int _Xwcscmp(wstr1, wstr2)wchar_t *wstr1, *wstr2;int _Xwcsncmp(wstr1, wstr2, len)wchar_t *wstr1, *wstr2;int len;The _Xwcscmp function compares two (wchar_t) NULLterminated wide character strings. The value returned is aninteger less than, equal to, or greater than zero, dependingon 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.1