OLD | NEW |
| (Empty) |
1 /* | |
2 ********************************************************************** | |
3 * Copyright (C) 1997-2010, International Business Machines | |
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" | |
28 #include "unicode/localpointer.h" | |
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 inform
ation in | |
38 * a data file. You create a resource bundle that manages the resources for a gi
ven | |
39 * locale and then ask it for individual resources. | |
40 * <P> | |
41 * Resource bundles in ICU4C are currently defined using text files which confor
m to the following | |
42 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.
txt">BNF definition</a>. | |
43 * More on resource bundle concepts and syntax can be found in the | |
44 * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guid
e</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 { | |
65 /** Resource type constant for "no resource". @stable ICU 2.6 */ | |
66 URES_NONE=-1, | |
67 | |
68 /** Resource type constant for 16-bit Unicode strings. @stable ICU 2.6 */ | |
69 URES_STRING=0, | |
70 | |
71 /** Resource type constant for binary data. @stable ICU 2.6 */ | |
72 URES_BINARY=1, | |
73 | |
74 /** Resource type constant for tables of key-value pairs. @stable ICU 2.6 */ | |
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
. | |
82 * @stable ICU 2.6 | |
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 | |
91 * @stable ICU 2.6 | |
92 */ | |
93 URES_INT=7, | |
94 | |
95 /** Resource type constant for arrays of resources. @stable ICU 2.6 */ | |
96 URES_ARRAY=8, | |
97 | |
98 /** | |
99 * Resource type constant for vectors of 32-bit integers. | |
100 * @see ures_getIntVector | |
101 * @stable ICU 2.6 | |
102 */ | |
103 URES_INT_VECTOR = 14, | |
104 #ifndef U_HIDE_DEPRECATED_API | |
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, | |
121 /** @deprecated ICU 2.6 Not used. */ | |
122 RES_RESERVED=15, | |
123 #endif /* U_HIDE_DEPRECATED_API */ | |
124 | |
125 URES_LIMIT = 16 | |
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 su
ccesfully | |
136 * opened resource bundle. | |
137 * @param packageName The packageName and locale together point to an ICU udat
a object, | |
138 * as defined by <code> udata_open( packageName, "res", loc
ale, err) </code> | |
139 * or equivalent. Typically, packageName will refer to a (
.dat) file, or to | |
140 * a package registered with udata_setAppData(). Using a fu
ll file or directory | |
141 * pathname for packageName is deprecated. If NULL, ICU dat
a will be used. | |
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 o
f | |
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_W
ARNING | |
151 * indicates that a fall back locale was used. For example, 'de_CH' was requeste
d, | |
152 * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indica
tes that | |
153 * the default locale data or root locale data was used; neither the requested l
ocale | |
154 * nor any of its fall back locales could be found. Please see the users guide f
or more | |
155 * information on this topic. | |
156 * @return a newly allocated resource bundle. | |
157 * @see ures_close | |
158 * @stable ICU 2.0 | |
159 */ | |
160 U_STABLE UResourceBundle* U_EXPORT2 | |
161 ures_open(const char* packageName, | |
162 const char* locale, | |
163 UErrorCode* status); | |
164 | |
165 | |
166 /** This function does not care what kind of localeID is passed in. It simply op
ens a bundle with | |
167 * that name. Fallback mechanism is disabled for the new bundle. If the request
ed bundle contains | |
168 * an %%ALIAS directive, the results are undefined. | |
169 * @param packageName The packageName and locale together point to an ICU udat
a object, | |
170 * as defined by <code> udata_open( packageName, "res", loc
ale, err) </code> | |
171 * or equivalent. Typically, packageName will refer to a (
.dat) file, or to | |
172 * a package registered with udata_setAppData(). Using a fu
ll file or directory | |
173 * pathname for packageName is deprecated. If NULL, ICU dat
a will be used. | |
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_MISS
ING_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 */ | |
183 U_STABLE UResourceBundle* U_EXPORT2 | |
184 ures_openDirect(const char* packageName, | |
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 * | |
193 * @param packageName The packageName and locale together point to an ICU udat
a object, | |
194 * as defined by <code> udata_open( packageName, "res", loc
ale, err) </code> | |
195 * or equivalent. Typically, packageName will refer to a (
.dat) file, or to | |
196 * a package registered with udata_setAppData(). Using a fu
ll file or directory | |
197 * pathname for packageName is deprecated. If NULL, ICU dat
a will be used. | |
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 */ | |
206 U_STABLE UResourceBundle* U_EXPORT2 | |
207 ures_openU(const UChar* packageName, | |
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 | |
218 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
219 * could be a non-failing error | |
220 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_FALLBACK_W
ARNING </TT> | |
221 *@return: for <STRONG>Arrays</STRONG>: returns the number of resources in th
e array | |
222 * <STRONG>Tables</STRONG>: returns the number of resources in th
e table | |
223 * <STRONG>single string</STRONG>: returns 1 | |
224 *@see ures_getSize | |
225 * @deprecated ICU 2.8 User ures_getSize instead | |
226 */ | |
227 U_DEPRECATED int32_t U_EXPORT2 | |
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 c
alls | |
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 */ | |
239 U_STABLE void U_EXPORT2 | |
240 ures_close(UResourceBundle* resourceBundle); | |
241 | |
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_c
lose); | |
256 | |
257 U_NAMESPACE_END | |
258 | |
259 #endif | |
260 | |
261 /** | |
262 * Return the version number associated with this ResourceBundle as a string. Pl
ease | |
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 p
arent. | |
267 * The caller does not own this string. | |
268 * @see ures_getVersion | |
269 * @deprecated ICU 2.8 Use ures_getVersion instead. | |
270 */ | |
271 U_DEPRECATED const char* U_EXPORT2 | |
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 numbe
r | |
280 * as specified in the resource bundle or its parent. | |
281 * @stable ICU 2.0 | |
282 */ | |
283 U_STABLE void U_EXPORT2 | |
284 ures_getVersion(const UResourceBundle* resB, | |
285 UVersionInfo versionInfo); | |
286 | |
287 /** | |
288 * Return the name of the Locale associated with this ResourceBundle. This API a
llows | |
289 * you to query for the real locale of the resource. For example, if you request
ed | |
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 | |
297 * @deprecated ICU 2.8 Use ures_getLocaleByType instead. | |
298 */ | |
299 U_DEPRECATED const char* U_EXPORT2 | |
300 ures_getLocale(const UResourceBundle* resourceBundle, | |
301 UErrorCode* status); | |
302 | |
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 | |
314 * @stable ICU 2.8 | |
315 */ | |
316 U_STABLE const char* U_EXPORT2 | |
317 ures_getLocaleByType(const UResourceBundle* resourceBundle, | |
318 ULocDataLocaleType type, | |
319 UErrorCode* status); | |
320 | |
321 | |
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(UResourceBu
ndle) | |
327 * @param r The resourcebundle to open | |
328 * @param packageName The packageName and locale together point to an ICU udat
a object, | |
329 * as defined by <code> udata_open( packageName, "res", loc
ale, err) </code> | |
330 * or equivalent. Typically, packageName will refer to a (
.dat) file, or to | |
331 * a package registered with udata_setAppData(). Using a fu
ll file or directory | |
332 * pathname for packageName is deprecated. If NULL, ICU dat
a will be used. | |
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 */ | |
338 U_INTERNAL void U_EXPORT2 | |
339 ures_openFillIn(UResourceBundle *r, | |
340 const char* packageName, | |
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 | |
350 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
351 * Always check the value of status. Don't count on returning NUL
L. | |
352 * could be a non-failing error | |
353 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WA
RNING </TT> | |
354 * @return a pointer to a zero-terminated UChar array which lives in a memory ma
pped/DLL file. | |
355 * @see ures_getBinary | |
356 * @see ures_getIntVector | |
357 * @see ures_getInt | |
358 * @see ures_getUInt | |
359 * @stable ICU 2.0 | |
360 */ | |
361 U_STABLE const UChar* U_EXPORT2 | |
362 ures_getString(const UResourceBundle* resourceBundle, | |
363 int32_t* len, | |
364 UErrorCode* status); | |
365 | |
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 se
t). | |
408 * | |
409 * @see ures_getString | |
410 * @see u_strToUTF8 | |
411 * @stable ICU 3.6 | |
412 */ | |
413 U_STABLE const char * U_EXPORT2 | |
414 ures_getUTF8String(const UResourceBundle *resB, | |
415 char *dest, int32_t *length, | |
416 UBool forceCopy, | |
417 UErrorCode *status); | |
418 | |
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 | |
425 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
426 * Always check the value of status. Don't count on returning NUL
L. | |
427 * could be a non-failing error | |
428 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WA
RNING </TT> | |
429 * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/
DLL file. | |
430 * @see ures_getString | |
431 * @see ures_getIntVector | |
432 * @see ures_getInt | |
433 * @see ures_getUInt | |
434 * @stable ICU 2.0 | |
435 */ | |
436 U_STABLE const uint8_t* U_EXPORT2 | |
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 | |
447 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
448 * Always check the value of status. Don't count on returning NUL
L. | |
449 * could be a non-failing error | |
450 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WA
RNING </TT> | |
451 * @return a pointer to a chunk of integers which live in a memory mapped/DLL fi
le. | |
452 * @see ures_getBinary | |
453 * @see ures_getString | |
454 * @see ures_getInt | |
455 * @see ures_getUInt | |
456 * @stable ICU 2.0 | |
457 */ | |
458 U_STABLE const int32_t* U_EXPORT2 | |
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 | |
469 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
470 * could be a non-failing error | |
471 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WA
RNING </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 */ | |
479 U_STABLE uint32_t U_EXPORT2 | |
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 | |
489 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
490 * could be a non-failing error | |
491 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WA
RNING </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 */ | |
499 U_STABLE int32_t U_EXPORT2 | |
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. | |
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. | |
509 * @param resourceBundle a resource | |
510 * @return number of resources in a given resource. | |
511 * @stable ICU 2.0 | |
512 */ | |
513 U_STABLE int32_t U_EXPORT2 | |
514 ures_getSize(const UResourceBundle *resourceBundle); | |
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 */ | |
524 U_STABLE UResType U_EXPORT2 | |
525 ures_getType(const UResourceBundle *resourceBundle); | |
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 */ | |
535 U_STABLE const char * U_EXPORT2 | |
536 ures_getKey(const UResourceBundle *resourceBundle); | |
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 f
irst element. | |
544 * | |
545 * @param resourceBundle a resource | |
546 * @stable ICU 2.0 | |
547 */ | |
548 U_STABLE void U_EXPORT2 | |
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 */ | |
558 U_STABLE UBool U_EXPORT2 | |
559 ures_hasNext(const UResourceBundle *resourceBundle); | |
560 | |
561 /** | |
562 * Returns the next resource in a given resource or NULL if there are no more re
sources | |
563 * to iterate over. Features a fill-in parameter. | |
564 * | |
565 * @param resourceBundle a resource | |
566 * @param fillIn if NULL a new UResourceBundle struct is allocated an
d must be closed by the caller. | |
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. | |
570 * @return a pointer to a UResourceBundle struct. If fill in pa
ram was NULL, caller must close it | |
571 * @stable ICU 2.0 | |
572 */ | |
573 U_STABLE UResourceBundle* U_EXPORT2 | |
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 reso
urces | |
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 occure
d, 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 ma
pped/DLL file. | |
588 * @stable ICU 2.0 | |
589 */ | |
590 U_STABLE const UChar* U_EXPORT2 | |
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 f
ill-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. | |
601 * @param fillIn if NULL a new UResourceBundle struct is allocated an
d must be closed by the caller. | |
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 NUL
L being returned if an error has | |
604 * occured. Check status instead. | |
605 * @return a pointer to a UResourceBundle struct. If fill in pa
ram was NULL, caller must close it | |
606 * @stable ICU 2.0 | |
607 */ | |
608 U_STABLE UResourceBundle* U_EXPORT2 | |
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 occure
d, 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 liv
es in a memory mapped/DLL file. | |
623 * @stable ICU 2.0 | |
624 */ | |
625 U_STABLE const UChar* U_EXPORT2 | |
626 ures_getStringByIndex(const UResourceBundle *resourceBundle, | |
627 int32_t indexS, | |
628 int32_t* len, | |
629 UErrorCode *status); | |
630 | |
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. | |
652 * @param stringIndex An index to the wanted string. | |
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 se
t). | |
674 * | |
675 * @see ures_getStringByIndex | |
676 * @see u_strToUTF8 | |
677 * @stable ICU 3.6 | |
678 */ | |
679 U_STABLE const char * U_EXPORT2 | |
680 ures_getUTF8StringByIndex(const UResourceBundle *resB, | |
681 int32_t stringIndex, | |
682 char *dest, int32_t *pLength, | |
683 UBool forceCopy, | |
684 UErrorCode *status); | |
685 | |
686 /** | |
687 * Returns a resource in a given resource that has a given key. This procedure w
orks 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 | |
692 * @param fillIn if NULL a new UResourceBundle struct is allocated an
d must be closed by the caller. | |
693 * Alternatively, you can supply a struct to be filled
by this function. | |
694 * @param status fills in the outgoing error code. | |
695 * @return a pointer to a UResourceBundle struct. If fill in pa
ram was NULL, caller must close it | |
696 * @stable ICU 2.0 | |
697 */ | |
698 U_STABLE UResourceBundle* U_EXPORT2 | |
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 wor
ks 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 occure
d, 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 liv
es in a memory mapped/DLL file. | |
714 * @stable ICU 2.0 | |
715 */ | |
716 U_STABLE const UChar* U_EXPORT2 | |
717 ures_getStringByKey(const UResourceBundle *resB, | |
718 const char* key, | |
719 int32_t* len, | |
720 UErrorCode *status); | |
721 | |
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 se
t). | |
767 * | |
768 * @see ures_getStringByKey | |
769 * @see u_strToUTF8 | |
770 * @stable ICU 3.6 | |
771 */ | |
772 U_STABLE const char * U_EXPORT2 | |
773 ures_getUTF8StringByKey(const UResourceBundle *resB, | |
774 const char *key, | |
775 char *dest, int32_t *pLength, | |
776 UBool forceCopy, | |
777 UErrorCode *status); | |
778 | |
779 #if U_SHOW_CPLUSPLUS_API | |
780 #include "unicode/unistr.h" | |
781 | |
782 U_NAMESPACE_BEGIN | |
783 /** | |
784 * returns a string from a string resource type | |
785 * | |
786 * @param resB a resource | |
787 * @param status: fills in the outgoing error code | |
788 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not f
ound | |
789 * could be a non-failing error | |
790 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WA
RNING </TT> | |
791 * @return a UnicodeString object. If there is an error, string is bogus | |
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, strin
g 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 onl
y 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, strin
g 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 | |
866 /** | |
867 * Create a string enumerator, owned by the caller, of all locales located withi
n | |
868 * the specified resource tree. | |
869 * @param packageName name of the tree, such as (NULL) or U_ICUDATA_ALIAS or or
"ICUDATA-coll" | |
870 * This call is similar to uloc_getAvailable(). | |
871 * @param status error code | |
872 * @stable ICU 3.2 | |
873 */ | |
874 U_STABLE UEnumeration* U_EXPORT2 | |
875 ures_openAvailableLocales(const char *packageName, UErrorCode *status); | |
876 | |
877 | |
878 #endif /*_URES*/ | |
879 /*eof*/ | |
OLD | NEW |