XpSetLocaleHinter(3Xp)   XPRINT FUNCTIONS  XpSetLocaleHinter(3Xp)



NAME
       XpSetLocaleHinter  -   Sets a "locale hinter" function and
       description of it.

SYNOPSIS
             cc [ flag... ] file... -lXp [ library... ]
             #include 

       void XpSetLocaleHinter ( hinter_proc hinter_desc )
             XPHinterProc hinter_proc;
             char *hinter_desc;

ARGUMENTS
       hinter_proc
              A pointer to a "hinter proc".

       hinter_desc
              A  pointer  to  contextual  information  about  the
              locale hinter proc.

DESCRIPTION
       Since  (to  date) there is no single industry standard for
       locale values, locale information about the current client
       required  by  XpCreateContext, XpGetPrinterList and XpGet-
       PdmStartParams is at best considered a "hint" when  trans-
       mitted  to  the  X  Print Server and PDM. In single vendor
       environments, the locale hint  should  be  consistent  and
       understood.  In  multi-vendor  environments  however,  the
       locale hint may or  may  not  be  understood.  The  caller
       locale will be used as the fallback default.

       XpSetLocaleHinter  and XpGetLocaleHinter access hooks that
       are used to register more  advanced  hint  generators.  By
       default,  Xp  uses  a  hinter proc that calls setlocale on
       the CTYPE category on POSIX systems,  and  hinter_desc  is
       NULL.

       XpSetLocaleHinter  sets  the  hinter_proc  and hinter_desc
       which will be subsequently used by the Xp calls  requiring
       a  locale  hint  (see above).  hinter_proc is the function
       that will generate the locale hint (for example, "C"), and
       hinter_desc  is  a  string, with or without the embeddable
       keyword %locale%, that provides a higher level context for
       the results of hinter_proc.

       If  hinter_proc is set to NULL, then the default Xp hinter
       proc is installed.  XpSetLocaleHinter makes its  own  pri-
       vate copy of hinter_desc prior to returning.

       An example set call might look as follows:

           XpSetLocaleHinter( my_hinter, "%locale%;CDElocale" );

       Where my_hinter might look as follows:

          char *my_hinter()
          {
              /*
               * Use setlocale() to retrieve the current locale.
               */
              return( my_x_strdup( setlocale(LC_CTYPE, (char *) NULL) ) );
          }



       When  the  client's  locale is needed, if both hinter_desc
       and the results of hinter_proc are non-NULL, and the  key-
       word  %locale%  is  found in hinter_desc, then the keyword
       will be replaced with  the  result  of  hinter_proc.   The
       resulting string will be used as the locale hint by the Xp
       calls.

       If both hinter_desc and the  results  of  hinter_proc  are
       non-NULL,  but  the  keyword %locale% is not found in hin-
       ter_desc, then hinter_desc, as is, becomes the string used
       as the locale hint by the Xp calls.

       If  one  of  hinter_desc  or the results of hinter_proc is
       NULL, then the other non-NULL  value  becomes  the  string
       used as the locale hint by the Xp calls.

       If  hinter_desc  and  the results of hinter_proc are NULL,
       then a NULL (i.e. (char *) NULL) locale hint  is  sent  by
       the Xp calls.

       The syntax for hinter_desc is a variation of the unadopted
       X/Open standard for a "String Network Locale-Specification
       Syntax"  (X/Open,  Distributed  Internationalization  Ser-
       vices, Version 2, 1994 Snapshot). The Xp hinter_desc  syn-
       tax is:

           name_spec[;registry_spec[;ver_spec[;encoding_spec]]]


       In Xp, the first item is the locale name, followed by pro-
       gressively more  detailed  information  about  the  locale
       name, with each piece of information separated by a `;'.

STRUCTURES
       The  signature  for  hinter_proc is defined in  as follows:

           typedef char * (*XPHinterProc)();

       hinter_proc is expected to return a  string  that  can  be
       freed using XFree by the Xp calls themselves.

       Some  examples  include  (  hinter_desc  to left, expanded
       results to the right):

           CFRENCH                                CFRENCH
           %locale%                               C
           %locale%;CDElocale                     C;CDElocale
           %locale%;HP                            C;HP
           %locale%;IBM                           C;IBM
           %locale%;XOPEN;01_11;XFN-001001        de_DE;XOPEN;01_11;XFN-001001


FILES
       
SEE ALSO
       XpCreateContext(3Xp),  XpGetLocaleHinter(3Xp),   XpGetPdm-
       StartParams(3Xp),  XpGetPrinterList(3Xp),  XpSetLocaleHin-
       ter(3Xp)



X Version 11               libXp 1.0.0     XpSetLocaleHinter(3Xp)