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