ucat.h (5478B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ********************************************************************** 5 * Copyright (c) 2003-2004, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ********************************************************************** 8 * Author: Alan Liu 9 * Created: March 19 2003 10 * Since: ICU 2.6 11 ********************************************************************** 12 */ 13 #ifndef UCAT_H 14 #define UCAT_H 15 16 #include "unicode/utypes.h" 17 #include "unicode/ures.h" 18 19 /** 20 * \file 21 * \brief C API: Message Catalog Wrappers 22 * 23 * This C API provides look-alike functions that deliberately resemble 24 * the POSIX catopen, catclose, and catgets functions. The underlying 25 * implementation is in terms of ICU resource bundles, rather than 26 * POSIX message catalogs. 27 * 28 * The ICU resource bundles obey standard ICU inheritance policies. 29 * To facilitate this, sets and messages are flattened into one tier. 30 * This is done by creating resource bundle keys of the form 31 * <set_num>%<msg_num> where set_num is the set number and msg_num is 32 * the message number, formatted as decimal strings. 33 * 34 * Example: Consider a message catalog containing two sets: 35 * 36 * Set 1: Message 4 = "Good morning." 37 * Message 5 = "Good afternoon." 38 * Message 7 = "Good evening." 39 * Message 8 = "Good night." 40 * Set 4: Message 14 = "Please " 41 * Message 19 = "Thank you." 42 * Message 20 = "Sincerely," 43 * 44 * The ICU resource bundle source file would, assuming it is named 45 * "greet.txt", would look like this: 46 * 47 * greet 48 * { 49 * 1%4 { "Good morning." } 50 * 1%5 { "Good afternoon." } 51 * 1%7 { "Good evening." } 52 * 1%8 { "Good night." } 53 * 54 * 4%14 { "Please " } 55 * 4%19 { "Thank you." } 56 * 4%20 { "Sincerely," } 57 * } 58 * 59 * The catgets function is commonly used in combination with functions 60 * like printf and strftime. ICU components like message format can 61 * be used instead, although they use a different format syntax. 62 * There is an ICU package, icuio, that provides some of 63 * the POSIX-style formatting API. 64 */ 65 66 U_CDECL_BEGIN 67 68 /** 69 * An ICU message catalog descriptor, analogous to nl_catd. 70 * 71 * @stable ICU 2.6 72 */ 73 typedef UResourceBundle* u_nl_catd; 74 75 /** 76 * Open and return an ICU message catalog descriptor. The descriptor 77 * may be passed to u_catgets() to retrieve localized strings. 78 * 79 * @param name string containing the full path pointing to the 80 * directory where the resources reside followed by the package name 81 * e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. 82 * If NULL, ICU default data files will be used. 83 * 84 * Unlike POSIX, environment variables are not interpolated within the 85 * name. 86 * 87 * @param locale the locale for which we want to open the resource. If 88 * NULL, the default ICU locale will be used (see uloc_getDefault). If 89 * strlen(locale) == 0, the root locale will be used. 90 * 91 * @param ec input/output error code. Upon output, 92 * U_USING_FALLBACK_WARNING indicates that a fallback locale was 93 * used. For example, 'de_CH' was requested, but nothing was found 94 * there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the 95 * default locale data or root locale data was used; neither the 96 * requested locale nor any of its fallback locales were found. 97 * 98 * @return a message catalog descriptor that may be passed to 99 * u_catgets(). If the ec parameter indicates success, then the caller 100 * is responsible for calling u_catclose() to close the message 101 * catalog. If the ec parameter indicates failure, then NULL will be 102 * returned. 103 * 104 * @stable ICU 2.6 105 */ 106 U_CAPI u_nl_catd U_EXPORT2 107 u_catopen(const char* name, const char* locale, UErrorCode* ec); 108 109 /** 110 * Close an ICU message catalog, given its descriptor. 111 * 112 * @param catd a message catalog descriptor to be closed. May be NULL, 113 * in which case no action is taken. 114 * 115 * @stable ICU 2.6 116 */ 117 U_CAPI void U_EXPORT2 118 u_catclose(u_nl_catd catd); 119 120 /** 121 * Retrieve a localized string from an ICU message catalog. 122 * 123 * @param catd a message catalog descriptor returned by u_catopen. 124 * 125 * @param set_num the message catalog set number. Sets need not be 126 * numbered consecutively. 127 * 128 * @param msg_num the message catalog message number within the 129 * set. Messages need not be numbered consecutively. 130 * 131 * @param s the default string. This is returned if the string 132 * specified by the set_num and msg_num is not found. It must be 133 * zero-terminated. 134 * 135 * @param len fill-in parameter to receive the length of the result. 136 * May be NULL, in which case it is ignored. 137 * 138 * @param ec input/output error code. May be U_USING_FALLBACK_WARNING 139 * or U_USING_DEFAULT_WARNING. U_MISSING_RESOURCE_ERROR indicates that 140 * the set_num/msg_num tuple does not specify a valid message string 141 * in this catalog. 142 * 143 * @return a pointer to a zero-terminated UChar array which lives in 144 * an internal buffer area, typically a memory mapped/DLL file. The 145 * caller must NOT delete this pointer. If the call is unsuccessful 146 * for any reason, then s is returned. This includes the situation in 147 * which ec indicates a failing error code upon entry to this 148 * function. 149 * 150 * @stable ICU 2.6 151 */ 152 U_CAPI const UChar* U_EXPORT2 153 u_catgets(u_nl_catd catd, int32_t set_num, int32_t msg_num, 154 const UChar* s, 155 int32_t* len, UErrorCode* ec); 156 157 U_CDECL_END 158 159 #endif /*UCAT_H*/ 160 /*eof*/