1 /*

     2 **********************************************************************

     3 * Copyright (c) 2003-2004, International Business Machines

     4 * Corporation and others.  All Rights Reserved.

     5 **********************************************************************

     6 * Author: Alan Liu

     7 * Created: March 19 2003

     8 * Since: ICU 2.6

     9 **********************************************************************

    10 */

    11 #ifndef UCAT_H

    12 #define UCAT_H

    13 

    14 #include "unicode/utypes.h"

    15 #include "unicode/ures.h"

    16 

    17 /**

    18  * \file

    19  * \brief C API: Message Catalog Wrappers

    20  *

    21  * This C API provides look-alike functions that deliberately resemble

    22  * the POSIX catopen, catclose, and catgets functions.  The underlying

    23  * implementation is in terms of ICU resource bundles, rather than

    24  * POSIX message catalogs.

    25  *

    26  * The ICU resource bundles obey standard ICU inheritance policies.

    27  * To facilitate this, sets and messages are flattened into one tier.

    28  * This is done by creating resource bundle keys of the form

    29  * <set_num>%<msg_num> where set_num is the set number and msg_num is

    30  * the message number, formatted as decimal strings.

    31  *

    32  * Example:  Consider a message catalog containing two sets:

    33  *

    34  * Set 1: Message 4  = "Good morning."

    35  *        Message 5  = "Good afternoon."

    36  *        Message 7  = "Good evening."

    37  *        Message 8  = "Good night."

    38  * Set 4: Message 14 = "Please "

    39  *        Message 19 = "Thank you."

    40  *        Message 20 = "Sincerely,"

    41  *

    42  * The ICU resource bundle source file would, assuming it is named

    43  * "greet.txt", would look like this:

    44  *

    45  * greet

    46  * {

    47  *     1%4  { "Good morning." }

    48  *     1%5  { "Good afternoon." }

    49  *     1%7  { "Good evening." }

    50  *     1%8  { "Good night." }

    51  * 

    52  *     4%14 { "Please " }

    53  *     4%19 { "Thank you." }

    54  *     4%20 { "Sincerely," }

    55  * }

    56  *

    57  * The catgets function is commonly used in combination with functions

    58  * like printf and strftime.  ICU components like message format can

    59  * be used instead, although they use a different format syntax.

    60  * There is an ICU package, icuio, that provides some of

    61  * the POSIX-style formatting API.

    62  */

    63 

    64 U_CDECL_BEGIN

    65 

    66 /**

    67  * An ICU message catalog descriptor, analogous to nl_catd.

    68  * 

    69  * @stable ICU 2.6

    70  */

    71 typedef UResourceBundle* u_nl_catd;

    72 

    73 /**

    74  * Open and return an ICU message catalog descriptor. The descriptor

    75  * may be passed to u_catgets() to retrieve localized strings.

    76  *

    77  * @param name string containing the full path pointing to the

    78  * directory where the resources reside followed by the package name

    79  * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.

    80  * If NULL, ICU default data files will be used.

    81  *

    82  * Unlike POSIX, environment variables are not interpolated within the

    83  * name.

    84  *

    85  * @param locale the locale for which we want to open the resource. If

    86  * NULL, the default ICU locale will be used (see uloc_getDefault). If

    87  * strlen(locale) == 0, the root locale will be used.

    88  *

    89  * @param ec input/output error code. Upon output,

    90  * U_USING_FALLBACK_WARNING indicates that a fallback locale was

    91  * used. For example, 'de_CH' was requested, but nothing was found

    92  * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the

    93  * default locale data or root locale data was used; neither the

    94  * requested locale nor any of its fallback locales were found.

    95  *

    96  * @return a message catalog descriptor that may be passed to

    97  * u_catgets(). If the ec parameter indicates success, then the caller

    98  * is responsible for calling u_catclose() to close the message

    99  * catalog. If the ec parameter indicates failure, then NULL will be

   100  * returned.

   101  * 

   102  * @stable ICU 2.6

   103  */

   104 U_STABLE u_nl_catd U_EXPORT2

   105 u_catopen(const char* name, const char* locale, UErrorCode* ec);

   106 

   107 /**

   108  * Close an ICU message catalog, given its descriptor.

   109  *

   110  * @param catd a message catalog descriptor to be closed. May be NULL,

   111  * in which case no action is taken.

   112  * 

   113  * @stable ICU 2.6

   114  */

   115 U_STABLE void U_EXPORT2

   116 u_catclose(u_nl_catd catd);

   117 

   118 /**

   119  * Retrieve a localized string from an ICU message catalog.

   120  *

   121  * @param catd a message catalog descriptor returned by u_catopen.

   122  *

   123  * @param set_num the message catalog set number. Sets need not be

   124  * numbered consecutively.

   125  *

   126  * @param msg_num the message catalog message number within the

   127  * set. Messages need not be numbered consecutively.

   128  *

   129  * @param s the default string. This is returned if the string

   130  * specified by the set_num and msg_num is not found. It must be

   131  * zero-terminated.

   132  *

   133  * @param len fill-in parameter to receive the length of the result.

   134  * May be NULL, in which case it is ignored.

   135  *

   136  * @param ec input/output error code. May be U_USING_FALLBACK_WARNING

   137  * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that

   138  * the set_num/msg_num tuple does not specify a valid message string

   139  * in this catalog.

   140  *

   141  * @return a pointer to a zero-terminated UChar array which lives in

   142  * an internal buffer area, typically a memory mapped/DLL file. The

   143  * caller must NOT delete this pointer. If the call is unsuccessful

   144  * for any reason, then s is returned.  This includes the situation in

   145  * which ec indicates a failing error code upon entry to this

   146  * function.

   147  * 

   148  * @stable ICU 2.6

   149  */

   150 U_STABLE const UChar* U_EXPORT2

   151 u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num,

   152           const UChar* s,

   153           int32_t* len, UErrorCode* ec);

   154 

   155 U_CDECL_END

   156 

   157 #endif /*UCAT_H*/

   158 /*eof*/