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

source code of include/unicode/ures.h