icuSources/common/unicode/ucat.h

   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  * &lt;set_num&gt;%&lt;msg_num&gt; 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*/