]>
Commit | Line | Data |
---|---|---|
b75a7d8f A |
1 | /* |
2 | ********************************************************************** | |
729e4ab9 | 3 | * Copyright (C) 1997-2010, International Business Machines |
b75a7d8f A |
4 | * Corporation and others. All Rights Reserved. |
5 | ********************************************************************** | |
6 | * | |
7 | * File URES.H (formerly CRESBUND.H) | |
8 | * | |
9 | * Modification History: | |
10 | * | |
11 | * Date Name Description | |
12 | * 04/01/97 aliu Creation. | |
13 | * 02/22/99 damiba overhaul. | |
14 | * 04/04/99 helena Fixed internal header inclusion. | |
15 | * 04/15/99 Madhu Updated Javadoc | |
16 | * 06/14/99 stephen Removed functions taking a filename suffix. | |
17 | * 07/20/99 stephen Language-independent ypedef to void* | |
18 | * 11/09/99 weiv Added ures_getLocale() | |
19 | * 06/24/02 weiv Added support for resource sharing | |
20 | ****************************************************************************** | |
21 | */ | |
22 | ||
23 | #ifndef URES_H | |
24 | #define URES_H | |
25 | ||
26 | #include "unicode/utypes.h" | |
27 | #include "unicode/uloc.h" | |
729e4ab9 | 28 | #include "unicode/localpointer.h" |
b75a7d8f A |
29 | |
30 | /** | |
31 | * \file | |
32 | * \brief C API: Resource Bundle | |
33 | * | |
34 | * <h2>C API: Resource Bundle</h2> | |
35 | * | |
36 | * C API representing a collection of resource information pertaining to a given | |
37 | * locale. A resource bundle provides a way of accessing locale- specific information in | |
38 | * a data file. You create a resource bundle that manages the resources for a given | |
39 | * locale and then ask it for individual resources. | |
40 | * <P> | |
41 | * Resource bundles in ICU4C are currently defined using text files which conform to the following | |
46f4442e | 42 | * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>. |
b75a7d8f | 43 | * More on resource bundle concepts and syntax can be found in the |
46f4442e | 44 | * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>. |
b75a7d8f A |
45 | * <P> |
46 | */ | |
47 | ||
48 | /** | |
49 | * UResourceBundle is an opaque type for handles for resource bundles in C APIs. | |
50 | * @stable ICU 2.0 | |
51 | */ | |
52 | struct UResourceBundle; | |
53 | ||
54 | /** | |
55 | * @stable ICU 2.0 | |
56 | */ | |
57 | typedef struct UResourceBundle UResourceBundle; | |
58 | ||
59 | /** | |
60 | * Numeric constants for types of resource items. | |
61 | * @see ures_getType | |
62 | * @stable ICU 2.0 | |
63 | */ | |
64 | typedef enum { | |
374ca955 | 65 | /** Resource type constant for "no resource". @stable ICU 2.6 */ |
b75a7d8f A |
66 | URES_NONE=-1, |
67 | ||
374ca955 | 68 | /** Resource type constant for 16-bit Unicode strings. @stable ICU 2.6 */ |
b75a7d8f A |
69 | URES_STRING=0, |
70 | ||
374ca955 | 71 | /** Resource type constant for binary data. @stable ICU 2.6 */ |
b75a7d8f A |
72 | URES_BINARY=1, |
73 | ||
374ca955 | 74 | /** Resource type constant for tables of key-value pairs. @stable ICU 2.6 */ |
b75a7d8f A |
75 | URES_TABLE=2, |
76 | ||
77 | /** | |
78 | * Resource type constant for aliases; | |
79 | * internally stores a string which identifies the actual resource | |
80 | * storing the data (can be in a different resource bundle). | |
81 | * Resolved internally before delivering the actual resource through the API. | |
374ca955 | 82 | * @stable ICU 2.6 |
b75a7d8f A |
83 | */ |
84 | URES_ALIAS=3, | |
85 | ||
86 | /** | |
87 | * Resource type constant for a single 28-bit integer, interpreted as | |
88 | * signed or unsigned by the ures_getInt() or ures_getUInt() function. | |
89 | * @see ures_getInt | |
90 | * @see ures_getUInt | |
374ca955 | 91 | * @stable ICU 2.6 |
b75a7d8f A |
92 | */ |
93 | URES_INT=7, | |
94 | ||
374ca955 | 95 | /** Resource type constant for arrays of resources. @stable ICU 2.6 */ |
b75a7d8f A |
96 | URES_ARRAY=8, |
97 | ||
98 | /** | |
99 | * Resource type constant for vectors of 32-bit integers. | |
100 | * @see ures_getIntVector | |
374ca955 | 101 | * @stable ICU 2.6 |
b75a7d8f | 102 | */ |
73c04bcf | 103 | URES_INT_VECTOR = 14, |
374ca955 | 104 | #ifndef U_HIDE_DEPRECATED_API |
b75a7d8f A |
105 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ |
106 | RES_NONE=URES_NONE, | |
107 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
108 | RES_STRING=URES_STRING, | |
109 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
110 | RES_BINARY=URES_BINARY, | |
111 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
112 | RES_TABLE=URES_TABLE, | |
113 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
114 | RES_ALIAS=URES_ALIAS, | |
115 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
116 | RES_INT=URES_INT, | |
117 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
118 | RES_ARRAY=URES_ARRAY, | |
119 | /** @deprecated ICU 2.6 Use the URES_ constant instead. */ | |
120 | RES_INT_VECTOR=URES_INT_VECTOR, | |
73c04bcf A |
121 | /** @deprecated ICU 2.6 Not used. */ |
122 | RES_RESERVED=15, | |
374ca955 A |
123 | #endif /* U_HIDE_DEPRECATED_API */ |
124 | ||
73c04bcf | 125 | URES_LIMIT = 16 |
b75a7d8f A |
126 | } UResType; |
127 | ||
128 | /* | |
129 | * Functions to create and destroy resource bundles. | |
130 | */ | |
131 | ||
132 | /** | |
133 | * Opens a UResourceBundle, from which users can extract strings by using | |
134 | * their corresponding keys. | |
135 | * Note that the caller is responsible of calling <TT>ures_close</TT> on each succesfully | |
136 | * opened resource bundle. | |
73c04bcf A |
137 | * @param packageName The packageName and locale together point to an ICU udata object, |
138 | * as defined by <code> udata_open( packageName, "res", locale, err) </code> | |
139 | * or equivalent. Typically, packageName will refer to a (.dat) file, or to | |
140 | * a package registered with udata_setAppData(). Using a full file or directory | |
141 | * pathname for packageName is deprecated. If NULL, ICU data will be used. | |
b75a7d8f A |
142 | * @param locale specifies the locale for which we want to open the resource |
143 | * if NULL, the default locale will be used. If strlen(locale) == 0 | |
144 | * root locale will be used. | |
145 | * | |
146 | * @param status fills in the outgoing error code. | |
147 | * The UErrorCode err parameter is used to return status information to the user. To | |
148 | * check whether the construction succeeded or not, you should check the value of | |
149 | * U_SUCCESS(err). If you wish more detailed information, you can check for | |
150 | * informational status results which still indicate success. U_USING_FALLBACK_WARNING | |
151 | * indicates that a fall back locale was used. For example, 'de_CH' was requested, | |
152 | * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that | |
153 | * the default locale data or root locale data was used; neither the requested locale | |
154 | * nor any of its fall back locales could be found. Please see the users guide for more | |
155 | * information on this topic. | |
156 | * @return a newly allocated resource bundle. | |
157 | * @see ures_close | |
158 | * @stable ICU 2.0 | |
159 | */ | |
374ca955 | 160 | U_STABLE UResourceBundle* U_EXPORT2 |
73c04bcf | 161 | ures_open(const char* packageName, |
b75a7d8f A |
162 | const char* locale, |
163 | UErrorCode* status); | |
164 | ||
165 | ||
166 | /** This function does not care what kind of localeID is passed in. It simply opens a bundle with | |
167 | * that name. Fallback mechanism is disabled for the new bundle. If the requested bundle contains | |
168 | * an %%ALIAS directive, the results are undefined. | |
73c04bcf A |
169 | * @param packageName The packageName and locale together point to an ICU udata object, |
170 | * as defined by <code> udata_open( packageName, "res", locale, err) </code> | |
171 | * or equivalent. Typically, packageName will refer to a (.dat) file, or to | |
172 | * a package registered with udata_setAppData(). Using a full file or directory | |
173 | * pathname for packageName is deprecated. If NULL, ICU data will be used. | |
b75a7d8f A |
174 | * @param locale specifies the locale for which we want to open the resource |
175 | * if NULL, the default locale will be used. If strlen(locale) == 0 | |
176 | * root locale will be used. | |
177 | * | |
178 | * @param status fills in the outgoing error code. Either U_ZERO_ERROR or U_MISSING_RESOURCE_ERROR | |
179 | * @return a newly allocated resource bundle or NULL if it doesn't exist. | |
180 | * @see ures_close | |
181 | * @stable ICU 2.0 | |
182 | */ | |
374ca955 | 183 | U_STABLE UResourceBundle* U_EXPORT2 |
73c04bcf | 184 | ures_openDirect(const char* packageName, |
b75a7d8f A |
185 | const char* locale, |
186 | UErrorCode* status); | |
187 | ||
188 | /** | |
189 | * Same as ures_open() but takes a const UChar *path. | |
190 | * This path will be converted to char * using the default converter, | |
191 | * then ures_open() is called. | |
192 | * | |
73c04bcf A |
193 | * @param packageName The packageName and locale together point to an ICU udata object, |
194 | * as defined by <code> udata_open( packageName, "res", locale, err) </code> | |
195 | * or equivalent. Typically, packageName will refer to a (.dat) file, or to | |
196 | * a package registered with udata_setAppData(). Using a full file or directory | |
197 | * pathname for packageName is deprecated. If NULL, ICU data will be used. | |
b75a7d8f A |
198 | * @param locale specifies the locale for which we want to open the resource |
199 | * if NULL, the default locale will be used. If strlen(locale) == 0 | |
200 | * root locale will be used. | |
201 | * @param status fills in the outgoing error code. | |
202 | * @return a newly allocated resource bundle. | |
203 | * @see ures_open | |
204 | * @stable ICU 2.0 | |
205 | */ | |
374ca955 | 206 | U_STABLE UResourceBundle* U_EXPORT2 |
73c04bcf | 207 | ures_openU(const UChar* packageName, |
b75a7d8f A |
208 | const char* locale, |
209 | UErrorCode* status); | |
210 | ||
211 | /** | |
212 | * Returns the number of strings/arrays in resource bundles. | |
213 | * Better to use ures_getSize, as this function will be deprecated. | |
214 | * | |
215 | *@param resourceBundle resource bundle containing the desired strings | |
216 | *@param resourceKey key tagging the resource | |
217 | *@param err fills in the outgoing error code | |
374ca955 | 218 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
219 | * could be a non-failing error |
220 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_FALLBACK_WARNING </TT> | |
221 | *@return: for <STRONG>Arrays</STRONG>: returns the number of resources in the array | |
222 | * <STRONG>Tables</STRONG>: returns the number of resources in the table | |
223 | * <STRONG>single string</STRONG>: returns 1 | |
224 | *@see ures_getSize | |
374ca955 | 225 | * @deprecated ICU 2.8 User ures_getSize instead |
b75a7d8f | 226 | */ |
374ca955 | 227 | U_DEPRECATED int32_t U_EXPORT2 |
b75a7d8f A |
228 | ures_countArrayItems(const UResourceBundle* resourceBundle, |
229 | const char* resourceKey, | |
230 | UErrorCode* err); | |
231 | /** | |
232 | * Close a resource bundle, all pointers returned from the various ures_getXXX calls | |
233 | * on this particular bundle should be considered invalid henceforth. | |
234 | * | |
235 | * @param resourceBundle a pointer to a resourceBundle struct. Can be NULL. | |
236 | * @see ures_open | |
237 | * @stable ICU 2.0 | |
238 | */ | |
374ca955 | 239 | U_STABLE void U_EXPORT2 |
b75a7d8f A |
240 | ures_close(UResourceBundle* resourceBundle); |
241 | ||
729e4ab9 A |
242 | #if U_SHOW_CPLUSPLUS_API |
243 | ||
244 | U_NAMESPACE_BEGIN | |
245 | ||
246 | /** | |
247 | * \class LocalUResourceBundlePointer | |
248 | * "Smart pointer" class, closes a UResourceBundle via ures_close(). | |
249 | * For most methods see the LocalPointerBase base class. | |
250 | * | |
251 | * @see LocalPointerBase | |
252 | * @see LocalPointer | |
253 | * @stable ICU 4.4 | |
254 | */ | |
255 | U_DEFINE_LOCAL_OPEN_POINTER(LocalUResourceBundlePointer, UResourceBundle, ures_close); | |
256 | ||
257 | U_NAMESPACE_END | |
258 | ||
259 | #endif | |
260 | ||
b75a7d8f A |
261 | /** |
262 | * Return the version number associated with this ResourceBundle as a string. Please | |
263 | * use ures_getVersion as this function is going to be deprecated. | |
264 | * | |
265 | * @param resourceBundle The resource bundle for which the version is checked. | |
266 | * @return A version number string as specified in the resource bundle or its parent. | |
267 | * The caller does not own this string. | |
268 | * @see ures_getVersion | |
374ca955 | 269 | * @deprecated ICU 2.8 Use ures_getVersion instead. |
b75a7d8f | 270 | */ |
374ca955 | 271 | U_DEPRECATED const char* U_EXPORT2 |
b75a7d8f A |
272 | ures_getVersionNumber(const UResourceBundle* resourceBundle); |
273 | ||
274 | /** | |
275 | * Return the version number associated with this ResourceBundle as an | |
276 | * UVersionInfo array. | |
277 | * | |
278 | * @param resB The resource bundle for which the version is checked. | |
279 | * @param versionInfo A UVersionInfo array that is filled with the version number | |
280 | * as specified in the resource bundle or its parent. | |
281 | * @stable ICU 2.0 | |
282 | */ | |
374ca955 | 283 | U_STABLE void U_EXPORT2 |
b75a7d8f A |
284 | ures_getVersion(const UResourceBundle* resB, |
285 | UVersionInfo versionInfo); | |
286 | ||
287 | /** | |
288 | * Return the name of the Locale associated with this ResourceBundle. This API allows | |
289 | * you to query for the real locale of the resource. For example, if you requested | |
290 | * "en_US_CALIFORNIA" and only "en_US" bundle exists, "en_US" will be returned. | |
291 | * For subresources, the locale where this resource comes from will be returned. | |
292 | * If fallback has occured, getLocale will reflect this. | |
293 | * | |
294 | * @param resourceBundle resource bundle in question | |
295 | * @param status just for catching illegal arguments | |
296 | * @return A Locale name | |
374ca955 | 297 | * @deprecated ICU 2.8 Use ures_getLocaleByType instead. |
b75a7d8f | 298 | */ |
374ca955 | 299 | U_DEPRECATED const char* U_EXPORT2 |
b75a7d8f A |
300 | ures_getLocale(const UResourceBundle* resourceBundle, |
301 | UErrorCode* status); | |
302 | ||
374ca955 A |
303 | |
304 | /** | |
305 | * Return the name of the Locale associated with this ResourceBundle. | |
306 | * You can choose between requested, valid and real locale. | |
307 | * | |
308 | * @param resourceBundle resource bundle in question | |
309 | * @param type You can choose between requested, valid and actual | |
310 | * locale. For description see the definition of | |
311 | * ULocDataLocaleType in uloc.h | |
312 | * @param status just for catching illegal arguments | |
313 | * @return A Locale name | |
73c04bcf | 314 | * @stable ICU 2.8 |
374ca955 | 315 | */ |
73c04bcf | 316 | U_STABLE const char* U_EXPORT2 |
374ca955 A |
317 | ures_getLocaleByType(const UResourceBundle* resourceBundle, |
318 | ULocDataLocaleType type, | |
319 | UErrorCode* status); | |
320 | ||
321 | ||
b75a7d8f A |
322 | /** |
323 | * Same as ures_open() but uses the fill-in parameter instead of allocating | |
324 | * a bundle, if r!=NULL. | |
325 | * TODO need to revisit usefulness of this function | |
326 | * and usage model for fillIn parameters without knowing sizeof(UResourceBundle) | |
327 | * @param r The resourcebundle to open | |
73c04bcf A |
328 | * @param packageName The packageName and locale together point to an ICU udata object, |
329 | * as defined by <code> udata_open( packageName, "res", locale, err) </code> | |
330 | * or equivalent. Typically, packageName will refer to a (.dat) file, or to | |
331 | * a package registered with udata_setAppData(). Using a full file or directory | |
332 | * pathname for packageName is deprecated. If NULL, ICU data will be used. | |
b75a7d8f A |
333 | * @param localeID specifies the locale for which we want to open the resource |
334 | * @param status The error code | |
335 | * @return a newly allocated resource bundle or NULL if it doesn't exist. | |
336 | * @internal | |
337 | */ | |
374ca955 | 338 | U_INTERNAL void U_EXPORT2 |
b75a7d8f | 339 | ures_openFillIn(UResourceBundle *r, |
73c04bcf | 340 | const char* packageName, |
b75a7d8f A |
341 | const char* localeID, |
342 | UErrorCode* status); | |
343 | ||
344 | /** | |
345 | * Returns a string from a string resource type | |
346 | * | |
347 | * @param resourceBundle a string resource | |
348 | * @param len fills in the length of resulting string | |
349 | * @param status fills in the outgoing error code | |
374ca955 | 350 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
351 | * Always check the value of status. Don't count on returning NULL. |
352 | * could be a non-failing error | |
353 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT> | |
354 | * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file. | |
355 | * @see ures_getBinary | |
356 | * @see ures_getIntVector | |
357 | * @see ures_getInt | |
358 | * @see ures_getUInt | |
359 | * @stable ICU 2.0 | |
360 | */ | |
374ca955 | 361 | U_STABLE const UChar* U_EXPORT2 |
b75a7d8f A |
362 | ures_getString(const UResourceBundle* resourceBundle, |
363 | int32_t* len, | |
364 | UErrorCode* status); | |
365 | ||
73c04bcf A |
366 | /** |
367 | * Returns a UTF-8 string from a string resource. | |
368 | * The UTF-8 string may be returnable directly as a pointer, or | |
369 | * it may need to be copied, or transformed from UTF-16 using u_strToUTF8() | |
370 | * or equivalent. | |
371 | * | |
372 | * If forceCopy==TRUE, then the string is always written to the dest buffer | |
373 | * and dest is returned. | |
374 | * | |
375 | * If forceCopy==FALSE, then the string is returned as a pointer if possible, | |
376 | * without needing a dest buffer (it can be NULL). If the string needs to be | |
377 | * copied or transformed, then it may be placed into dest at an arbitrary offset. | |
378 | * | |
379 | * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and | |
380 | * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual. | |
381 | * | |
382 | * If the string is transformed from UTF-16, then a conversion error may occur | |
383 | * if an unpaired surrogate is encountered. If the function is successful, then | |
384 | * the output UTF-8 string is always well-formed. | |
385 | * | |
386 | * @param resB Resource bundle. | |
387 | * @param dest Destination buffer. Can be NULL only if capacity=*length==0. | |
388 | * @param length Input: Capacity of destination buffer. | |
389 | * Output: Actual length of the UTF-8 string, not counting the | |
390 | * terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR. | |
391 | * Can be NULL, meaning capacity=0 and the string length is not | |
392 | * returned to the caller. | |
393 | * @param forceCopy If TRUE, then the output string will always be written to | |
394 | * dest, with U_BUFFER_OVERFLOW_ERROR and | |
395 | * U_STRING_NOT_TERMINATED_WARNING set if appropriate. | |
396 | * If FALSE, then the dest buffer may or may not contain a | |
397 | * copy of the string. dest may or may not be modified. | |
398 | * If a copy needs to be written, then the UErrorCode parameter | |
399 | * indicates overflow etc. as usual. | |
400 | * @param status Pointer to a standard ICU error code. Its input value must | |
401 | * pass the U_SUCCESS() test, or else the function returns | |
402 | * immediately. Check for U_FAILURE() on output or use with | |
403 | * function chaining. (See User Guide for details.) | |
404 | * @return The pointer to the UTF-8 string. It may be dest, or at some offset | |
405 | * from dest (only if !forceCopy), or in unrelated memory. | |
406 | * Always NUL-terminated unless the string was written to dest and | |
407 | * length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set). | |
408 | * | |
409 | * @see ures_getString | |
410 | * @see u_strToUTF8 | |
46f4442e | 411 | * @stable ICU 3.6 |
73c04bcf | 412 | */ |
46f4442e | 413 | U_STABLE const char * U_EXPORT2 |
73c04bcf A |
414 | ures_getUTF8String(const UResourceBundle *resB, |
415 | char *dest, int32_t *length, | |
416 | UBool forceCopy, | |
417 | UErrorCode *status); | |
418 | ||
b75a7d8f A |
419 | /** |
420 | * Returns a binary data from a binary resource. | |
421 | * | |
422 | * @param resourceBundle a string resource | |
423 | * @param len fills in the length of resulting byte chunk | |
424 | * @param status fills in the outgoing error code | |
374ca955 | 425 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
426 | * Always check the value of status. Don't count on returning NULL. |
427 | * could be a non-failing error | |
428 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT> | |
729e4ab9 | 429 | * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file. |
b75a7d8f A |
430 | * @see ures_getString |
431 | * @see ures_getIntVector | |
432 | * @see ures_getInt | |
433 | * @see ures_getUInt | |
434 | * @stable ICU 2.0 | |
435 | */ | |
374ca955 | 436 | U_STABLE const uint8_t* U_EXPORT2 |
b75a7d8f A |
437 | ures_getBinary(const UResourceBundle* resourceBundle, |
438 | int32_t* len, | |
439 | UErrorCode* status); | |
440 | ||
441 | /** | |
442 | * Returns a 32 bit integer array from a resource. | |
443 | * | |
444 | * @param resourceBundle an int vector resource | |
445 | * @param len fills in the length of resulting byte chunk | |
446 | * @param status fills in the outgoing error code | |
374ca955 | 447 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
448 | * Always check the value of status. Don't count on returning NULL. |
449 | * could be a non-failing error | |
450 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT> | |
729e4ab9 | 451 | * @return a pointer to a chunk of integers which live in a memory mapped/DLL file. |
b75a7d8f A |
452 | * @see ures_getBinary |
453 | * @see ures_getString | |
454 | * @see ures_getInt | |
455 | * @see ures_getUInt | |
456 | * @stable ICU 2.0 | |
457 | */ | |
374ca955 | 458 | U_STABLE const int32_t* U_EXPORT2 |
b75a7d8f A |
459 | ures_getIntVector(const UResourceBundle* resourceBundle, |
460 | int32_t* len, | |
461 | UErrorCode* status); | |
462 | ||
463 | /** | |
464 | * Returns an unsigned integer from a resource. | |
465 | * This integer is originally 28 bits. | |
466 | * | |
467 | * @param resourceBundle a string resource | |
468 | * @param status fills in the outgoing error code | |
374ca955 | 469 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
470 | * could be a non-failing error |
471 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT> | |
472 | * @return an integer value | |
473 | * @see ures_getInt | |
474 | * @see ures_getIntVector | |
475 | * @see ures_getBinary | |
476 | * @see ures_getString | |
477 | * @stable ICU 2.0 | |
478 | */ | |
374ca955 | 479 | U_STABLE uint32_t U_EXPORT2 |
b75a7d8f A |
480 | ures_getUInt(const UResourceBundle* resourceBundle, |
481 | UErrorCode *status); | |
482 | ||
483 | /** | |
484 | * Returns a signed integer from a resource. | |
485 | * This integer is originally 28 bit and the sign gets propagated. | |
486 | * | |
487 | * @param resourceBundle a string resource | |
488 | * @param status fills in the outgoing error code | |
374ca955 | 489 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
490 | * could be a non-failing error |
491 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT> | |
492 | * @return an integer value | |
493 | * @see ures_getUInt | |
494 | * @see ures_getIntVector | |
495 | * @see ures_getBinary | |
496 | * @see ures_getString | |
497 | * @stable ICU 2.0 | |
498 | */ | |
374ca955 | 499 | U_STABLE int32_t U_EXPORT2 |
b75a7d8f A |
500 | ures_getInt(const UResourceBundle* resourceBundle, |
501 | UErrorCode *status); | |
502 | ||
503 | /** | |
504 | * Returns the size of a resource. Size for scalar types is always 1, | |
505 | * and for vector/table types is the number of child resources. | |
374ca955 A |
506 | * @warning Integer array is treated as a scalar type. There are no |
507 | * APIs to access individual members of an integer array. It | |
508 | * is always returned as a whole. | |
b75a7d8f A |
509 | * @param resourceBundle a resource |
510 | * @return number of resources in a given resource. | |
511 | * @stable ICU 2.0 | |
512 | */ | |
374ca955 A |
513 | U_STABLE int32_t U_EXPORT2 |
514 | ures_getSize(const UResourceBundle *resourceBundle); | |
b75a7d8f A |
515 | |
516 | /** | |
517 | * Returns the type of a resource. Available types are defined in enum UResType | |
518 | * | |
519 | * @param resourceBundle a resource | |
520 | * @return type of the given resource. | |
521 | * @see UResType | |
522 | * @stable ICU 2.0 | |
523 | */ | |
374ca955 A |
524 | U_STABLE UResType U_EXPORT2 |
525 | ures_getType(const UResourceBundle *resourceBundle); | |
b75a7d8f A |
526 | |
527 | /** | |
528 | * Returns the key associated with a given resource. Not all the resources have a key - only | |
529 | * those that are members of a table. | |
530 | * | |
531 | * @param resourceBundle a resource | |
532 | * @return a key associated to this resource, or NULL if it doesn't have a key | |
533 | * @stable ICU 2.0 | |
534 | */ | |
374ca955 A |
535 | U_STABLE const char * U_EXPORT2 |
536 | ures_getKey(const UResourceBundle *resourceBundle); | |
b75a7d8f A |
537 | |
538 | /* ITERATION API | |
539 | This API provides means for iterating through a resource | |
540 | */ | |
541 | ||
542 | /** | |
543 | * Resets the internal context of a resource so that iteration starts from the first element. | |
544 | * | |
545 | * @param resourceBundle a resource | |
546 | * @stable ICU 2.0 | |
547 | */ | |
374ca955 | 548 | U_STABLE void U_EXPORT2 |
b75a7d8f A |
549 | ures_resetIterator(UResourceBundle *resourceBundle); |
550 | ||
551 | /** | |
552 | * Checks whether the given resource has another element to iterate over. | |
553 | * | |
554 | * @param resourceBundle a resource | |
555 | * @return TRUE if there are more elements, FALSE if there is no more elements | |
556 | * @stable ICU 2.0 | |
557 | */ | |
374ca955 A |
558 | U_STABLE UBool U_EXPORT2 |
559 | ures_hasNext(const UResourceBundle *resourceBundle); | |
b75a7d8f A |
560 | |
561 | /** | |
562 | * Returns the next resource in a given resource or NULL if there are no more resources | |
563 | * to iterate over. Features a fill-in parameter. | |
564 | * | |
565 | * @param resourceBundle a resource | |
73c04bcf | 566 | * @param fillIn if NULL a new UResourceBundle struct is allocated and must be closed by the caller. |
b75a7d8f A |
567 | * Alternatively, you can supply a struct to be filled by this function. |
568 | * @param status fills in the outgoing error code. You may still get a non NULL result even if an | |
569 | * error occured. Check status instead. | |
73c04bcf | 570 | * @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it |
b75a7d8f A |
571 | * @stable ICU 2.0 |
572 | */ | |
374ca955 | 573 | U_STABLE UResourceBundle* U_EXPORT2 |
b75a7d8f A |
574 | ures_getNextResource(UResourceBundle *resourceBundle, |
575 | UResourceBundle *fillIn, | |
576 | UErrorCode *status); | |
577 | ||
578 | /** | |
579 | * Returns the next string in a given resource or NULL if there are no more resources | |
580 | * to iterate over. | |
581 | * | |
582 | * @param resourceBundle a resource | |
583 | * @param len fill in length of the string | |
584 | * @param key fill in for key associated with this string. NULL if no key | |
585 | * @param status fills in the outgoing error code. If an error occured, we may return NULL, but don't | |
586 | * count on it. Check status instead! | |
587 | * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file. | |
588 | * @stable ICU 2.0 | |
589 | */ | |
374ca955 | 590 | U_STABLE const UChar* U_EXPORT2 |
b75a7d8f A |
591 | ures_getNextString(UResourceBundle *resourceBundle, |
592 | int32_t* len, | |
593 | const char ** key, | |
594 | UErrorCode *status); | |
595 | ||
596 | /** | |
597 | * Returns the resource in a given resource at the specified index. Features a fill-in parameter. | |
598 | * | |
599 | * @param resourceBundle the resource bundle from which to get a sub-resource | |
600 | * @param indexR an index to the wanted resource. | |
73c04bcf | 601 | * @param fillIn if NULL a new UResourceBundle struct is allocated and must be closed by the caller. |
b75a7d8f A |
602 | * Alternatively, you can supply a struct to be filled by this function. |
603 | * @param status fills in the outgoing error code. Don't count on NULL being returned if an error has | |
604 | * occured. Check status instead. | |
73c04bcf | 605 | * @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it |
b75a7d8f A |
606 | * @stable ICU 2.0 |
607 | */ | |
374ca955 | 608 | U_STABLE UResourceBundle* U_EXPORT2 |
b75a7d8f A |
609 | ures_getByIndex(const UResourceBundle *resourceBundle, |
610 | int32_t indexR, | |
611 | UResourceBundle *fillIn, | |
612 | UErrorCode *status); | |
613 | ||
614 | /** | |
615 | * Returns the string in a given resource at the specified index. | |
616 | * | |
617 | * @param resourceBundle a resource | |
618 | * @param indexS an index to the wanted string. | |
619 | * @param len fill in length of the string | |
620 | * @param status fills in the outgoing error code. If an error occured, we may return NULL, but don't | |
621 | * count on it. Check status instead! | |
622 | * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file. | |
623 | * @stable ICU 2.0 | |
624 | */ | |
374ca955 | 625 | U_STABLE const UChar* U_EXPORT2 |
b75a7d8f A |
626 | ures_getStringByIndex(const UResourceBundle *resourceBundle, |
627 | int32_t indexS, | |
628 | int32_t* len, | |
629 | UErrorCode *status); | |
630 | ||
73c04bcf A |
631 | /** |
632 | * Returns a UTF-8 string from a resource at the specified index. | |
633 | * The UTF-8 string may be returnable directly as a pointer, or | |
634 | * it may need to be copied, or transformed from UTF-16 using u_strToUTF8() | |
635 | * or equivalent. | |
636 | * | |
637 | * If forceCopy==TRUE, then the string is always written to the dest buffer | |
638 | * and dest is returned. | |
639 | * | |
640 | * If forceCopy==FALSE, then the string is returned as a pointer if possible, | |
641 | * without needing a dest buffer (it can be NULL). If the string needs to be | |
642 | * copied or transformed, then it may be placed into dest at an arbitrary offset. | |
643 | * | |
644 | * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and | |
645 | * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual. | |
646 | * | |
647 | * If the string is transformed from UTF-16, then a conversion error may occur | |
648 | * if an unpaired surrogate is encountered. If the function is successful, then | |
649 | * the output UTF-8 string is always well-formed. | |
650 | * | |
651 | * @param resB Resource bundle. | |
729e4ab9 | 652 | * @param stringIndex An index to the wanted string. |
73c04bcf A |
653 | * @param dest Destination buffer. Can be NULL only if capacity=*length==0. |
654 | * @param pLength Input: Capacity of destination buffer. | |
655 | * Output: Actual length of the UTF-8 string, not counting the | |
656 | * terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR. | |
657 | * Can be NULL, meaning capacity=0 and the string length is not | |
658 | * returned to the caller. | |
659 | * @param forceCopy If TRUE, then the output string will always be written to | |
660 | * dest, with U_BUFFER_OVERFLOW_ERROR and | |
661 | * U_STRING_NOT_TERMINATED_WARNING set if appropriate. | |
662 | * If FALSE, then the dest buffer may or may not contain a | |
663 | * copy of the string. dest may or may not be modified. | |
664 | * If a copy needs to be written, then the UErrorCode parameter | |
665 | * indicates overflow etc. as usual. | |
666 | * @param status Pointer to a standard ICU error code. Its input value must | |
667 | * pass the U_SUCCESS() test, or else the function returns | |
668 | * immediately. Check for U_FAILURE() on output or use with | |
669 | * function chaining. (See User Guide for details.) | |
670 | * @return The pointer to the UTF-8 string. It may be dest, or at some offset | |
671 | * from dest (only if !forceCopy), or in unrelated memory. | |
672 | * Always NUL-terminated unless the string was written to dest and | |
673 | * length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set). | |
674 | * | |
675 | * @see ures_getStringByIndex | |
676 | * @see u_strToUTF8 | |
46f4442e | 677 | * @stable ICU 3.6 |
73c04bcf | 678 | */ |
46f4442e | 679 | U_STABLE const char * U_EXPORT2 |
73c04bcf | 680 | ures_getUTF8StringByIndex(const UResourceBundle *resB, |
729e4ab9 | 681 | int32_t stringIndex, |
73c04bcf A |
682 | char *dest, int32_t *pLength, |
683 | UBool forceCopy, | |
684 | UErrorCode *status); | |
685 | ||
b75a7d8f A |
686 | /** |
687 | * Returns a resource in a given resource that has a given key. This procedure works only with table | |
688 | * resources. Features a fill-in parameter. | |
689 | * | |
690 | * @param resourceBundle a resource | |
691 | * @param key a key associated with the wanted resource | |
73c04bcf | 692 | * @param fillIn if NULL a new UResourceBundle struct is allocated and must be closed by the caller. |
b75a7d8f A |
693 | * Alternatively, you can supply a struct to be filled by this function. |
694 | * @param status fills in the outgoing error code. | |
73c04bcf | 695 | * @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it |
b75a7d8f A |
696 | * @stable ICU 2.0 |
697 | */ | |
374ca955 | 698 | U_STABLE UResourceBundle* U_EXPORT2 |
b75a7d8f A |
699 | ures_getByKey(const UResourceBundle *resourceBundle, |
700 | const char* key, | |
701 | UResourceBundle *fillIn, | |
702 | UErrorCode *status); | |
703 | ||
704 | /** | |
705 | * Returns a string in a given resource that has a given key. This procedure works only with table | |
706 | * resources. | |
707 | * | |
708 | * @param resB a resource | |
709 | * @param key a key associated with the wanted string | |
710 | * @param len fill in length of the string | |
711 | * @param status fills in the outgoing error code. If an error occured, we may return NULL, but don't | |
712 | * count on it. Check status instead! | |
713 | * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file. | |
714 | * @stable ICU 2.0 | |
715 | */ | |
374ca955 | 716 | U_STABLE const UChar* U_EXPORT2 |
b75a7d8f A |
717 | ures_getStringByKey(const UResourceBundle *resB, |
718 | const char* key, | |
719 | int32_t* len, | |
720 | UErrorCode *status); | |
721 | ||
73c04bcf A |
722 | /** |
723 | * Returns a UTF-8 string from a resource and a key. | |
724 | * This function works only with table resources. | |
725 | * | |
726 | * The UTF-8 string may be returnable directly as a pointer, or | |
727 | * it may need to be copied, or transformed from UTF-16 using u_strToUTF8() | |
728 | * or equivalent. | |
729 | * | |
730 | * If forceCopy==TRUE, then the string is always written to the dest buffer | |
731 | * and dest is returned. | |
732 | * | |
733 | * If forceCopy==FALSE, then the string is returned as a pointer if possible, | |
734 | * without needing a dest buffer (it can be NULL). If the string needs to be | |
735 | * copied or transformed, then it may be placed into dest at an arbitrary offset. | |
736 | * | |
737 | * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and | |
738 | * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual. | |
739 | * | |
740 | * If the string is transformed from UTF-16, then a conversion error may occur | |
741 | * if an unpaired surrogate is encountered. If the function is successful, then | |
742 | * the output UTF-8 string is always well-formed. | |
743 | * | |
744 | * @param resB Resource bundle. | |
745 | * @param key A key associated with the wanted resource | |
746 | * @param dest Destination buffer. Can be NULL only if capacity=*length==0. | |
747 | * @param pLength Input: Capacity of destination buffer. | |
748 | * Output: Actual length of the UTF-8 string, not counting the | |
749 | * terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR. | |
750 | * Can be NULL, meaning capacity=0 and the string length is not | |
751 | * returned to the caller. | |
752 | * @param forceCopy If TRUE, then the output string will always be written to | |
753 | * dest, with U_BUFFER_OVERFLOW_ERROR and | |
754 | * U_STRING_NOT_TERMINATED_WARNING set if appropriate. | |
755 | * If FALSE, then the dest buffer may or may not contain a | |
756 | * copy of the string. dest may or may not be modified. | |
757 | * If a copy needs to be written, then the UErrorCode parameter | |
758 | * indicates overflow etc. as usual. | |
759 | * @param status Pointer to a standard ICU error code. Its input value must | |
760 | * pass the U_SUCCESS() test, or else the function returns | |
761 | * immediately. Check for U_FAILURE() on output or use with | |
762 | * function chaining. (See User Guide for details.) | |
763 | * @return The pointer to the UTF-8 string. It may be dest, or at some offset | |
764 | * from dest (only if !forceCopy), or in unrelated memory. | |
765 | * Always NUL-terminated unless the string was written to dest and | |
766 | * length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set). | |
767 | * | |
768 | * @see ures_getStringByKey | |
769 | * @see u_strToUTF8 | |
46f4442e | 770 | * @stable ICU 3.6 |
73c04bcf | 771 | */ |
46f4442e | 772 | U_STABLE const char * U_EXPORT2 |
73c04bcf A |
773 | ures_getUTF8StringByKey(const UResourceBundle *resB, |
774 | const char *key, | |
775 | char *dest, int32_t *pLength, | |
776 | UBool forceCopy, | |
777 | UErrorCode *status); | |
778 | ||
729e4ab9 | 779 | #if U_SHOW_CPLUSPLUS_API |
b75a7d8f A |
780 | #include "unicode/unistr.h" |
781 | ||
782 | U_NAMESPACE_BEGIN | |
783 | /** | |
784 | * returns a string from a string resource type | |
785 | * | |
73c04bcf | 786 | * @param resB a resource |
b75a7d8f | 787 | * @param status: fills in the outgoing error code |
374ca955 | 788 | * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found |
b75a7d8f A |
789 | * could be a non-failing error |
790 | * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT> | |
73c04bcf | 791 | * @return a UnicodeString object. If there is an error, string is bogus |
b75a7d8f A |
792 | * @stable ICU 2.0 |
793 | */ | |
794 | inline UnicodeString | |
795 | ures_getUnicodeString(const UResourceBundle *resB, | |
796 | UErrorCode* status) | |
797 | { | |
798 | int32_t len = 0; | |
799 | const UChar *r = ures_getString(resB, &len, status); | |
800 | return UnicodeString(TRUE, r, len); | |
801 | } | |
802 | ||
803 | /** | |
804 | * Returns the next string in a resource or NULL if there are no more resources | |
805 | * to iterate over. | |
806 | * | |
807 | * @param resB a resource | |
808 | * @param key fill in for key associated with this string | |
809 | * @param status fills in the outgoing error code | |
810 | * @return an UnicodeString object. | |
811 | * @stable ICU 2.0 | |
812 | */ | |
813 | inline UnicodeString | |
814 | ures_getNextUnicodeString(UResourceBundle *resB, | |
815 | const char ** key, | |
816 | UErrorCode* status) | |
817 | { | |
818 | int32_t len = 0; | |
819 | const UChar* r = ures_getNextString(resB, &len, key, status); | |
820 | return UnicodeString(TRUE, r, len); | |
821 | } | |
822 | ||
823 | /** | |
824 | * Returns the string in a given resource at the specified index. | |
825 | * | |
826 | * @param resB a resource | |
827 | * @param index an index to the wanted string. | |
828 | * @param status fills in the outgoing error code | |
829 | * @return an UnicodeString object. If there is an error, string is bogus | |
830 | * @stable ICU 2.0 | |
831 | */ | |
832 | inline UnicodeString | |
833 | ures_getUnicodeStringByIndex(const UResourceBundle *resB, | |
834 | int32_t indexS, | |
835 | UErrorCode* status) | |
836 | { | |
837 | int32_t len = 0; | |
838 | const UChar* r = ures_getStringByIndex(resB, indexS, &len, status); | |
839 | return UnicodeString(TRUE, r, len); | |
840 | } | |
841 | ||
842 | /** | |
843 | * Returns a string in a resource that has a given key. This procedure works only with table | |
844 | * resources. | |
845 | * | |
846 | * @param resB a resource | |
847 | * @param key a key associated with the wanted string | |
848 | * @param status fills in the outgoing error code | |
849 | * @return an UnicodeString object. If there is an error, string is bogus | |
850 | * @stable ICU 2.0 | |
851 | */ | |
852 | inline UnicodeString | |
853 | ures_getUnicodeStringByKey(const UResourceBundle *resB, | |
854 | const char* key, | |
855 | UErrorCode* status) | |
856 | { | |
857 | int32_t len = 0; | |
858 | const UChar* r = ures_getStringByKey(resB, key, &len, status); | |
859 | return UnicodeString(TRUE, r, len); | |
860 | } | |
861 | ||
862 | U_NAMESPACE_END | |
863 | ||
864 | #endif | |
865 | ||
374ca955 A |
866 | /** |
867 | * Create a string enumerator, owned by the caller, of all locales located within | |
868 | * the specified resource tree. | |
73c04bcf | 869 | * @param packageName name of the tree, such as (NULL) or U_ICUDATA_ALIAS or or "ICUDATA-coll" |
374ca955 A |
870 | * This call is similar to uloc_getAvailable(). |
871 | * @param status error code | |
73c04bcf | 872 | * @stable ICU 3.2 |
374ca955 | 873 | */ |
73c04bcf A |
874 | U_STABLE UEnumeration* U_EXPORT2 |
875 | ures_openAvailableLocales(const char *packageName, UErrorCode *status); | |
374ca955 A |
876 | |
877 | ||
b75a7d8f A |
878 | #endif /*_URES*/ |
879 | /*eof*/ |