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