icuSources/common/unicode/ures.h

   1 /*
   2 **********************************************************************
   3 *   Copyright (C) 1997-2004, International Business Machines
   4 *   Corporation and others.  All Rights Reserved.
   5 **********************************************************************
   6 *
   7 * File URES.H (formerly CRESBUND.H)
   8 *
   9 * Modification History:
  10 *
  11 *   Date        Name        Description
  12 *   04/01/97    aliu        Creation.
  13 *   02/22/99    damiba      overhaul.
  14 *   04/04/99    helena      Fixed internal header inclusion.
  15 *   04/15/99    Madhu       Updated Javadoc
  16 *   06/14/99    stephen     Removed functions taking a filename suffix.
  17 *   07/20/99    stephen     Language-independent ypedef to void*
  18 *   11/09/99    weiv        Added ures_getLocale()
  19 *   06/24/02    weiv        Added support for resource sharing
  20 ******************************************************************************
  21 */
  22
  23 #ifndef URES_H
  24 #define URES_H
  25
  26 #include "unicode/utypes.h"
  27 #include "unicode/uloc.h"
  28
  29 /**
  30  * \file
  31  * \brief C API: Resource Bundle
  32  *
  33  * <h2>C API: Resource Bundle</h2>
  34  *
  35  * C API representing a collection of resource information pertaining to a given
  36  * locale. A resource bundle provides a way of accessing locale- specific information in
  37  * a data file. You create a resource bundle that manages the resources for a given
  38  * locale and then ask it for individual resources.
  39  * <P>
  40  * Resource bundles in ICU4C are currently defined using text files which conform to the following
  41  * <a href="http://oss.software.ibm.com/cvs/icu/~checkout~/icuhtml/design/bnf_rb.txt">BNF definition</a>.
  42  * More on resource bundle concepts and syntax can be found in the
  43  * <a href="http://oss.software.ibm.com/icu/userguide/ResourceManagement.html">Users Guide</a>.
  44  * <P>
  45  */
  46
  47 /**
  48  * UResourceBundle is an opaque type for handles for resource bundles in C APIs.
  49  * @stable ICU 2.0
  50  */
  51 struct UResourceBundle;
  52
  53 /**
  54  * @stable ICU 2.0
  55  */
  56 typedef struct UResourceBundle UResourceBundle;
  57
  58 /**
  59  * Numeric constants for types of resource items.
  60  * @see ures_getType
  61  * @stable ICU 2.0
  62  */
  63 typedef enum {
  64     /** Resource type constant for "no resource". @stable ICU 2.6 */
  65     URES_NONE=-1,
  66
  67     /** Resource type constant for 16-bit Unicode strings. @stable ICU 2.6 */
  68     URES_STRING=0,
  69
  70     /** Resource type constant for binary data. @stable ICU 2.6 */
  71     URES_BINARY=1,
  72
  73     /** Resource type constant for tables of key-value pairs. @stable ICU 2.6 */
  74     URES_TABLE=2,
  75
  76     /**
  77      * Resource type constant for aliases;
  78      * internally stores a string which identifies the actual resource
  79      * storing the data (can be in a different resource bundle).
  80      * Resolved internally before delivering the actual resource through the API.
  81      * @stable ICU 2.6
  82      */
  83     URES_ALIAS=3,
  84
  85     /**
  86      * Internal use only.
  87      * Alternative resource type constant for tables of key-value pairs.
  88      * Never returned by ures_getType().
  89      * @internal
  90      */
  91     URES_TABLE32=4,
  92
  93     /**
  94      * Resource type constant for a single 28-bit integer, interpreted as
  95      * signed or unsigned by the ures_getInt() or ures_getUInt() function.
  96      * @see ures_getInt
  97      * @see ures_getUInt
  98      * @stable ICU 2.6
  99      */
 100     URES_INT=7,
 101
 102     /** Resource type constant for arrays of resources. @stable ICU 2.6 */
 103     URES_ARRAY=8,
 104
 105     /**
 106      * Resource type constant for vectors of 32-bit integers.
 107      * @see ures_getIntVector
 108      * @stable ICU 2.6
 109      */
 110     URES_INT_VECTOR=14,
 111
 112 #ifndef U_HIDE_DEPRECATED_API
 113     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 114     RES_NONE=URES_NONE,
 115     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 116     RES_STRING=URES_STRING,
 117     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 118     RES_BINARY=URES_BINARY,
 119     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 120     RES_TABLE=URES_TABLE,
 121     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 122     RES_ALIAS=URES_ALIAS,
 123     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 124     RES_INT=URES_INT,
 125     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 126     RES_ARRAY=URES_ARRAY,
 127     /** @deprecated ICU 2.6 Use the URES_ constant instead. */
 128     RES_INT_VECTOR=URES_INT_VECTOR,
 129 #endif /* U_HIDE_DEPRECATED_API */
 130
 131     /** @deprecated ICU 2.6 Not used. */
 132     RES_RESERVED=15
 133 } UResType;
 134
 135 /*
 136  * Functions to create and destroy resource bundles.
 137  */
 138
 139 /**
 140  * Opens a UResourceBundle, from which users can extract strings by using
 141  * their corresponding keys.
 142  * Note that the caller is responsible of calling <TT>ures_close</TT> on each succesfully
 143  * opened resource bundle.
 144  * @param path    string containing the full path pointing to the directory
 145  *                where the resources reside followed by the package name
 146  *                e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.
 147  *                if NULL, ICU default data files 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*    path,
 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 path    string containing the full path pointing to the directory
 176  *                where the resources reside followed by the package name
 177  *                e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system.
 178  *                if NULL, ICU default data files will be used.
 179  * @param locale  specifies the locale for which we want to open the resource
 180  *                if NULL, the default locale will be used. If strlen(locale) == 0
 181  *                root locale will be used.
 182  *
 183  * @param status fills in the outgoing error code. Either U_ZERO_ERROR or U_MISSING_RESOURCE_ERROR
 184  * @return      a newly allocated resource bundle or NULL if it doesn't exist.
 185  * @see ures_close
 186  * @stable ICU 2.0
 187  */
 188 U_STABLE UResourceBundle* U_EXPORT2
 189 ures_openDirect(const char* path,
 190                 const char* locale,
 191                 UErrorCode* status);
 192
 193 /**
 194  * Same as ures_open() but takes a const UChar *path.
 195  * This path will be converted to char * using the default converter,
 196  * then ures_open() is called.
 197  *
 198  * @param path    string containing the full path pointing to the directory
 199  *                where the resources reside followed by the package name
 200  * @param locale  specifies the locale for which we want to open the resource
 201  *                if NULL, the default locale will be used. If strlen(locale) == 0
 202  *                root locale will be used.
 203  * @param status  fills in the outgoing error code.
 204  * @return      a newly allocated resource bundle.
 205  * @see ures_open
 206  * @stable ICU 2.0
 207  */
 208 U_STABLE UResourceBundle* U_EXPORT2
 209 ures_openU(const UChar* path,
 210            const char* locale,
 211            UErrorCode* status);
 212
 213 /**
 214  * Returns the number of strings/arrays in resource bundles.
 215  * Better to use ures_getSize, as this function will be deprecated.
 216  *
 217  *@param resourceBundle resource bundle containing the desired strings
 218  *@param resourceKey key tagging the resource
 219  *@param err fills in the outgoing error code
 220  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 221  *                could be a non-failing error
 222  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_FALLBACK_WARNING </TT>
 223  *@return: for    <STRONG>Arrays</STRONG>: returns the number of resources in the array
 224  *                <STRONG>Tables</STRONG>: returns the number of resources in the table
 225  *                <STRONG>single string</STRONG>: returns 1
 226  *@see ures_getSize
 227  * @deprecated ICU 2.8 User ures_getSize instead
 228  */
 229 U_DEPRECATED int32_t U_EXPORT2
 230 ures_countArrayItems(const UResourceBundle* resourceBundle,
 231                      const char* resourceKey,
 232                      UErrorCode* err);
 233 /**
 234  * Close a resource bundle, all pointers returned from the various ures_getXXX calls
 235  * on this particular bundle should be considered invalid henceforth.
 236  *
 237  * @param resourceBundle a pointer to a resourceBundle struct. Can be NULL.
 238  * @see ures_open
 239  * @stable ICU 2.0
 240  */
 241 U_STABLE void U_EXPORT2
 242 ures_close(UResourceBundle* resourceBundle);
 243
 244 /**
 245  * Return the version number associated with this ResourceBundle as a string. Please
 246  * use ures_getVersion as this function is going to be deprecated.
 247  *
 248  * @param resourceBundle The resource bundle for which the version is checked.
 249  * @return  A version number string as specified in the resource bundle or its parent.
 250  *          The caller does not own this string.
 251  * @see ures_getVersion
 252  * @deprecated ICU 2.8 Use ures_getVersion instead.
 253  */
 254 U_DEPRECATED const char* U_EXPORT2
 255 ures_getVersionNumber(const UResourceBundle*   resourceBundle);
 256
 257 /**
 258  * Return the version number associated with this ResourceBundle as an
 259  * UVersionInfo array.
 260  *
 261  * @param resB The resource bundle for which the version is checked.
 262  * @param versionInfo A UVersionInfo array that is filled with the version number
 263  *                    as specified in the resource bundle or its parent.
 264  * @stable ICU 2.0
 265  */
 266 U_STABLE void U_EXPORT2
 267 ures_getVersion(const UResourceBundle* resB,
 268                 UVersionInfo versionInfo);
 269
 270 /**
 271  * Return the name of the Locale associated with this ResourceBundle. This API allows
 272  * you to query for the real locale of the resource. For example, if you requested
 273  * "en_US_CALIFORNIA" and only "en_US" bundle exists, "en_US" will be returned.
 274  * For subresources, the locale where this resource comes from will be returned.
 275  * If fallback has occured, getLocale will reflect this.
 276  *
 277  * @param resourceBundle resource bundle in question
 278  * @param status just for catching illegal arguments
 279  * @return  A Locale name
 280  * @deprecated ICU 2.8 Use ures_getLocaleByType instead.
 281  */
 282 U_DEPRECATED const char* U_EXPORT2
 283 ures_getLocale(const UResourceBundle* resourceBundle,
 284                UErrorCode* status);
 285
 286
 287 /**
 288  * Return the name of the Locale associated with this ResourceBundle.
 289  * You can choose between requested, valid and real locale.
 290  *
 291  * @param resourceBundle resource bundle in question
 292  * @param type You can choose between requested, valid and actual
 293  *             locale. For description see the definition of
 294  *             ULocDataLocaleType in uloc.h
 295  * @param status just for catching illegal arguments
 296  * @return  A Locale name
 297  * @draft ICU 2.8
 298  */
 299 U_DRAFT const char* U_EXPORT2
 300 ures_getLocaleByType(const UResourceBundle* resourceBundle,
 301                      ULocDataLocaleType type,
 302                      UErrorCode* status);
 303
 304
 305 /**
 306  * Same as ures_open() but uses the fill-in parameter instead of allocating
 307  * a bundle, if r!=NULL.
 308  * TODO need to revisit usefulness of this function
 309  *      and usage model for fillIn parameters without knowing sizeof(UResourceBundle)
 310  * @param r The resourcebundle to open
 311  * @param path String containing the full path pointing to the directory
 312  *             where the resources reside followed by the package name
 313  * @param localeID specifies the locale for which we want to open the resource
 314  * @param status The error code
 315  * @return a newly allocated resource bundle or NULL if it doesn't exist.
 316  * @internal
 317  */
 318 U_INTERNAL void U_EXPORT2
 319 ures_openFillIn(UResourceBundle *r,
 320                 const char* path,
 321                 const char* localeID,
 322                 UErrorCode* status);
 323
 324 /**
 325  * Returns a string from a string resource type
 326  *
 327  * @param resourceBundle a string resource
 328  * @param len    fills in the length of resulting string
 329  * @param status fills in the outgoing error code
 330  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 331  *                Always check the value of status. Don't count on returning NULL.
 332  *                could be a non-failing error
 333  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 334  * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 335  * @see ures_getBinary
 336  * @see ures_getIntVector
 337  * @see ures_getInt
 338  * @see ures_getUInt
 339  * @stable ICU 2.0
 340  */
 341 U_STABLE const UChar* U_EXPORT2
 342 ures_getString(const UResourceBundle* resourceBundle,
 343                int32_t* len,
 344                UErrorCode* status);
 345
 346 /**
 347  * Returns a binary data from a binary resource.
 348  *
 349  * @param resourceBundle a string resource
 350  * @param len    fills in the length of resulting byte chunk
 351  * @param status fills in the outgoing error code
 352  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 353  *                Always check the value of status. Don't count on returning NULL.
 354  *                could be a non-failing error
 355  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 356  * @return a pointer to a chuck of unsigned bytes which live in a memory mapped/DLL file.
 357  * @see ures_getString
 358  * @see ures_getIntVector
 359  * @see ures_getInt
 360  * @see ures_getUInt
 361  * @stable ICU 2.0
 362  */
 363 U_STABLE const uint8_t* U_EXPORT2
 364 ures_getBinary(const UResourceBundle* resourceBundle,
 365                int32_t* len,
 366                UErrorCode* status);
 367
 368 /**
 369  * Returns a 32 bit integer array from a resource.
 370  *
 371  * @param resourceBundle an int vector resource
 372  * @param len    fills in the length of resulting byte chunk
 373  * @param status fills in the outgoing error code
 374  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 375  *                Always check the value of status. Don't count on returning NULL.
 376  *                could be a non-failing error
 377  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 378  * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
 379  * @see ures_getBinary
 380  * @see ures_getString
 381  * @see ures_getInt
 382  * @see ures_getUInt
 383  * @stable ICU 2.0
 384  */
 385 U_STABLE const int32_t* U_EXPORT2
 386 ures_getIntVector(const UResourceBundle* resourceBundle,
 387                   int32_t* len,
 388                   UErrorCode* status);
 389
 390 /**
 391  * Returns an unsigned integer from a resource.
 392  * This integer is originally 28 bits.
 393  *
 394  * @param resourceBundle a string resource
 395  * @param status fills in the outgoing error code
 396  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 397  *                could be a non-failing error
 398  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 399  * @return an integer value
 400  * @see ures_getInt
 401  * @see ures_getIntVector
 402  * @see ures_getBinary
 403  * @see ures_getString
 404  * @stable ICU 2.0
 405  */
 406 U_STABLE uint32_t U_EXPORT2
 407 ures_getUInt(const UResourceBundle* resourceBundle,
 408              UErrorCode *status);
 409
 410 /**
 411  * Returns a signed integer from a resource.
 412  * This integer is originally 28 bit and the sign gets propagated.
 413  *
 414  * @param resourceBundle a string resource
 415  * @param status  fills in the outgoing error code
 416  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 417  *                could be a non-failing error
 418  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 419  * @return an integer value
 420  * @see ures_getUInt
 421  * @see ures_getIntVector
 422  * @see ures_getBinary
 423  * @see ures_getString
 424  * @stable ICU 2.0
 425  */
 426 U_STABLE int32_t U_EXPORT2
 427 ures_getInt(const UResourceBundle* resourceBundle,
 428             UErrorCode *status);
 429
 430 /**
 431  * Returns the size of a resource. Size for scalar types is always 1,
 432  * and for vector/table types is the number of child resources.
 433  * @warning Integer array is treated as a scalar type. There are no
 434  *          APIs to access individual members of an integer array. It
 435  *          is always returned as a whole.
 436  * @param resourceBundle a resource
 437  * @return number of resources in a given resource.
 438  * @stable ICU 2.0
 439  */
 440 U_STABLE int32_t U_EXPORT2
 441 ures_getSize(const UResourceBundle *resourceBundle);
 442
 443 /**
 444  * Returns the type of a resource. Available types are defined in enum UResType
 445  *
 446  * @param resourceBundle a resource
 447  * @return type of the given resource.
 448  * @see UResType
 449  * @stable ICU 2.0
 450  */
 451 U_STABLE UResType U_EXPORT2
 452 ures_getType(const UResourceBundle *resourceBundle);
 453
 454 /**
 455  * Returns the key associated with a given resource. Not all the resources have a key - only
 456  * those that are members of a table.
 457  *
 458  * @param resourceBundle a resource
 459  * @return a key associated to this resource, or NULL if it doesn't have a key
 460  * @stable ICU 2.0
 461  */
 462 U_STABLE const char * U_EXPORT2
 463 ures_getKey(const UResourceBundle *resourceBundle);
 464
 465 /* ITERATION API
 466     This API provides means for iterating through a resource
 467 */
 468
 469 /**
 470  * Resets the internal context of a resource so that iteration starts from the first element.
 471  *
 472  * @param resourceBundle a resource
 473  * @stable ICU 2.0
 474  */
 475 U_STABLE void U_EXPORT2
 476 ures_resetIterator(UResourceBundle *resourceBundle);
 477
 478 /**
 479  * Checks whether the given resource has another element to iterate over.
 480  *
 481  * @param resourceBundle a resource
 482  * @return TRUE if there are more elements, FALSE if there is no more elements
 483  * @stable ICU 2.0
 484  */
 485 U_STABLE UBool U_EXPORT2
 486 ures_hasNext(const UResourceBundle *resourceBundle);
 487
 488 /**
 489  * Returns the next resource in a given resource or NULL if there are no more resources
 490  * to iterate over. Features a fill-in parameter.
 491  *
 492  * @param resourceBundle    a resource
 493  * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
 494  *                          Alternatively, you can supply a struct to be filled by this function.
 495  * @param status            fills in the outgoing error code. You may still get a non NULL result even if an
 496  *                          error occured. Check status instead.
 497  * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 498  * @stable ICU 2.0
 499  */
 500 U_STABLE UResourceBundle* U_EXPORT2
 501 ures_getNextResource(UResourceBundle *resourceBundle,
 502                      UResourceBundle *fillIn,
 503                      UErrorCode *status);
 504
 505 /**
 506  * Returns the next string in a given resource or NULL if there are no more resources
 507  * to iterate over.
 508  *
 509  * @param resourceBundle    a resource
 510  * @param len               fill in length of the string
 511  * @param key               fill in for key associated with this string. NULL if no key
 512  * @param status            fills in the outgoing error code. If an error occured, we may return NULL, but don't
 513  *                          count on it. Check status instead!
 514  * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 515  * @stable ICU 2.0
 516  */
 517 U_STABLE const UChar* U_EXPORT2
 518 ures_getNextString(UResourceBundle *resourceBundle,
 519                    int32_t* len,
 520                    const char ** key,
 521                    UErrorCode *status);
 522
 523 /**
 524  * Returns the resource in a given resource at the specified index. Features a fill-in parameter.
 525  *
 526  * @param resourceBundle    the resource bundle from which to get a sub-resource
 527  * @param indexR            an index to the wanted resource.
 528  * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
 529  *                          Alternatively, you can supply a struct to be filled by this function.
 530  * @param status            fills in the outgoing error code. Don't count on NULL being returned if an error has
 531  *                          occured. Check status instead.
 532  * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 533  * @stable ICU 2.0
 534  */
 535 U_STABLE UResourceBundle* U_EXPORT2
 536 ures_getByIndex(const UResourceBundle *resourceBundle,
 537                 int32_t indexR,
 538                 UResourceBundle *fillIn,
 539                 UErrorCode *status);
 540
 541 /**
 542  * Returns the string in a given resource at the specified index.
 543  *
 544  * @param resourceBundle    a resource
 545  * @param indexS            an index to the wanted string.
 546  * @param len               fill in length of the string
 547  * @param status            fills in the outgoing error code. If an error occured, we may return NULL, but don't
 548  *                          count on it. Check status instead!
 549  * @return                  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 550  * @stable ICU 2.0
 551  */
 552 U_STABLE const UChar* U_EXPORT2
 553 ures_getStringByIndex(const UResourceBundle *resourceBundle,
 554                       int32_t indexS,
 555                       int32_t* len,
 556                       UErrorCode *status);
 557
 558 /**
 559  * Returns a resource in a given resource that has a given key. This procedure works only with table
 560  * resources. Features a fill-in parameter.
 561  *
 562  * @param resourceBundle    a resource
 563  * @param key               a key associated with the wanted resource
 564  * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
 565  *                          Alternatively, you can supply a struct to be filled by this function.
 566  * @param status            fills in the outgoing error code.
 567  * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 568  * @stable ICU 2.0
 569  */
 570 U_STABLE UResourceBundle* U_EXPORT2
 571 ures_getByKey(const UResourceBundle *resourceBundle,
 572               const char* key,
 573               UResourceBundle *fillIn,
 574               UErrorCode *status);
 575
 576 /**
 577  * Returns a string in a given resource that has a given key. This procedure works only with table
 578  * resources.
 579  *
 580  * @param resB              a resource
 581  * @param key               a key associated with the wanted string
 582  * @param len               fill in length of the string
 583  * @param status            fills in the outgoing error code. If an error occured, we may return NULL, but don't
 584  *                          count on it. Check status instead!
 585  * @return                  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
 586  * @stable ICU 2.0
 587  */
 588 U_STABLE const UChar* U_EXPORT2
 589 ures_getStringByKey(const UResourceBundle *resB,
 590                     const char* key,
 591                     int32_t* len,
 592                     UErrorCode *status);
 593
 594 #ifdef XP_CPLUSPLUS
 595 #include "unicode/unistr.h"
 596
 597 U_NAMESPACE_BEGIN
 598 /**
 599  * returns a string from a string resource type
 600  *
 601  * @param resB              a resource
 602  * @param status: fills in the outgoing error code
 603  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 604  *                could be a non-failing error
 605  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 606  * @return        an UnicodeString object. If there is an error, string is bogus
 607  * @stable ICU 2.0
 608  */
 609 inline UnicodeString
 610 ures_getUnicodeString(const UResourceBundle *resB,
 611                       UErrorCode* status)
 612 {
 613     int32_t len = 0;
 614     const UChar *r = ures_getString(resB, &len, status);
 615     return UnicodeString(TRUE, r, len);
 616 }
 617
 618 /**
 619  * Returns the next string in a resource or NULL if there are no more resources
 620  * to iterate over.
 621  *
 622  * @param resB              a resource
 623  * @param key               fill in for key associated with this string
 624  * @param status            fills in the outgoing error code
 625  * @return an UnicodeString object.
 626  * @stable ICU 2.0
 627  */
 628 inline UnicodeString
 629 ures_getNextUnicodeString(UResourceBundle *resB,
 630                           const char ** key,
 631                           UErrorCode* status)
 632 {
 633     int32_t len = 0;
 634     const UChar* r = ures_getNextString(resB, &len, key, status);
 635     return UnicodeString(TRUE, r, len);
 636 }
 637
 638 /**
 639  * Returns the string in a given resource at the specified index.
 640  *
 641  * @param resB              a resource
 642  * @param index             an index to the wanted string.
 643  * @param status            fills in the outgoing error code
 644  * @return                  an UnicodeString object. If there is an error, string is bogus
 645  * @stable ICU 2.0
 646  */
 647 inline UnicodeString
 648 ures_getUnicodeStringByIndex(const UResourceBundle *resB,
 649                              int32_t indexS,
 650                              UErrorCode* status)
 651 {
 652     int32_t len = 0;
 653     const UChar* r = ures_getStringByIndex(resB, indexS, &len, status);
 654     return UnicodeString(TRUE, r, len);
 655 }
 656
 657 /**
 658  * Returns a string in a resource that has a given key. This procedure works only with table
 659  * resources.
 660  *
 661  * @param resB              a resource
 662  * @param key               a key associated with the wanted string
 663  * @param status            fills in the outgoing error code
 664  * @return                  an UnicodeString object. If there is an error, string is bogus
 665  * @stable ICU 2.0
 666  */
 667 inline UnicodeString
 668 ures_getUnicodeStringByKey(const UResourceBundle *resB,
 669                            const char* key,
 670                            UErrorCode* status)
 671 {
 672     int32_t len = 0;
 673     const UChar* r = ures_getStringByKey(resB, key, &len, status);
 674     return UnicodeString(TRUE, r, len);
 675 }
 676
 677 U_NAMESPACE_END
 678
 679 #endif
 680
 681
 682 /**
 683  * Get a resource with multi-level fallback. Normally only the top level resources will
 684  * fallback to its parent. This performs fallback on subresources. For example, when a table
 685  * is defined in a resource bundle and a parent resource bundle, normally no fallback occurs
 686  * on the sub-resources because the table is defined in the current resource bundle, but this
 687  * function can perform fallback on the sub-resources of the table.
 688  * @param resB              a resource
 689  * @param inKey             a key associated with the requested resource
 690  * @param fillIn            if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
 691  *                          Alternatively, you can supply a struct to be filled by this function.
 692  * @param status: fills in the outgoing error code
 693  *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 694  *                could be a non-failing error
 695  *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 696  * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 697  * @internal ICU 3.0
 698  */
 699 U_INTERNAL UResourceBundle* U_EXPORT2
 700 ures_getByKeyWithFallback(const UResourceBundle *resB,
 701                           const char* inKey,
 702                           UResourceBundle *fillIn,
 703                           UErrorCode *status);
 704
 705
 706 /**
 707  * Create a string enumerator, owned by the caller, of all locales located within
 708  * the specified resource tree.
 709  * @param path path to the tree, such as (NULL) or U_ICUDATA_ALIAS or  or "ICUDATA-coll"
 710  * This call is similar to uloc_getAvailable().
 711  * @param status error code
 712  * @draft ICU 3.2
 713  */
 714 U_DRAFT UEnumeration* U_EXPORT2
 715 ures_openAvailableLocales(const char *path, UErrorCode *status);
 716
 717
 718 #endif /*_URES*/
 719 /*eof*/