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