Home | History | Annotate | Download | only in unicode
      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
    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
    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
    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
    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