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