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