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*/ 159