icuSources/common/unicode/ures.h

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