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