/* ********************************************************************** * Copyright (c) 2003-2004, International Business Machines * Corporation and others. All Rights Reserved. ********************************************************************** * Author: Alan Liu * Created: March 19 2003 * Since: ICU 2.6 ********************************************************************** */ #ifndef UCAT_H #define UCAT_H #include "unicode/utypes.h" #include "unicode/ures.h" /** * \file * \brief C API: Message Catalog Wrappers * * This C API provides look-alike functions that deliberately resemble * the POSIX catopen, catclose, and catgets functions. The underlying * implementation is in terms of ICU resource bundles, rather than * POSIX message catalogs. * * The ICU resource bundles obey standard ICU inheritance policies. * To facilitate this, sets and messages are flattened into one tier. * This is done by creating resource bundle keys of the form * <set_num>%<msg_num> where set_num is the set number and msg_num is * the message number, formatted as decimal strings. * * Example: Consider a message catalog containing two sets: * * Set 1: Message 4 = "Good morning." * Message 5 = "Good afternoon." * Message 7 = "Good evening." * Message 8 = "Good night." * Set 4: Message 14 = "Please " * Message 19 = "Thank you." * Message 20 = "Sincerely," * * The ICU resource bundle source file would, assuming it is named * "greet.txt", would look like this: * * greet * { * 1%4 { "Good morning." } * 1%5 { "Good afternoon." } * 1%7 { "Good evening." } * 1%8 { "Good night." } * * 4%14 { "Please " } * 4%19 { "Thank you." } * 4%20 { "Sincerely," } * } * * The catgets function is commonly used in combination with functions * like printf and strftime. ICU components like message format can * be used instead, although they use a different format syntax. * There is an ICU package, icuio, that provides some of * the POSIX-style formatting API. */ U_CDECL_BEGIN /** * An ICU message catalog descriptor, analogous to nl_catd. * * @stable ICU 2.6 */ typedef UResourceBundle* u_nl_catd; /** * Open and return an ICU message catalog descriptor. The descriptor * may be passed to u_catgets() to retrieve localized strings. * * @param name string containing the full path pointing to the * directory where the resources reside followed by the package name * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. * If NULL, ICU default data files will be used. * * Unlike POSIX, environment variables are not interpolated within the * name. * * @param locale the locale for which we want to open the resource. If * NULL, the default ICU locale will be used (see uloc_getDefault). If * strlen(locale) == 0, the root locale will be used. * * @param ec input/output error code. Upon output, * U_USING_FALLBACK_WARNING indicates that a fallback locale was * used. For example, 'de_CH' was requested, but nothing was found * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the * default locale data or root locale data was used; neither the * requested locale nor any of its fallback locales were found. * * @return a message catalog descriptor that may be passed to * u_catgets(). If the ec parameter indicates success, then the caller * is responsible for calling u_catclose() to close the message * catalog. If the ec parameter indicates failure, then NULL will be * returned. * * @stable ICU 2.6 */ U_STABLE u_nl_catd U_EXPORT2 u_catopen(const char* name, const char* locale, UErrorCode* ec); /** * Close an ICU message catalog, given its descriptor. * * @param catd a message catalog descriptor to be closed. May be NULL, * in which case no action is taken. * * @stable ICU 2.6 */ U_STABLE void U_EXPORT2 u_catclose(u_nl_catd catd); /** * Retrieve a localized string from an ICU message catalog. * * @param catd a message catalog descriptor returned by u_catopen. * * @param set_num the message catalog set number. Sets need not be * numbered consecutively. * * @param msg_num the message catalog message number within the * set. Messages need not be numbered consecutively. * * @param s the default string. This is returned if the string * specified by the set_num and msg_num is not found. It must be * zero-terminated. * * @param len fill-in parameter to receive the length of the result. * May be NULL, in which case it is ignored. * * @param ec input/output error code. May be U_USING_FALLBACK_WARNING * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that * the set_num/msg_num tuple does not specify a valid message string * in this catalog. * * @return a pointer to a zero-terminated UChar array which lives in * an internal buffer area, typically a memory mapped/DLL file. The * caller must NOT delete this pointer. If the call is unsuccessful * for any reason, then s is returned. This includes the situation in * which ec indicates a failing error code upon entry to this * function. * * @stable ICU 2.6 */ U_STABLE const UChar* U_EXPORT2 u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num, const UChar* s, int32_t* len, UErrorCode* ec); U_CDECL_END #endif /*UCAT_H*/ /*eof*/