Main Page | Class Hierarchy | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

ures.h File Reference

C API: Resource Bundle. More...

#include "unicode/utypes.h"
#include "unicode/uloc.h"

Go to the source code of this file.

Typedefs

typedef UResourceBundle UResourceBundle
 

Enumerations

enum  UResType {
  RES_NONE = -1, RES_STRING = 0, RES_BINARY = 1, RES_TABLE = 2,
  RES_INT = 7, RES_ARRAY = 8, RES_INT_VECTOR = 14, RES_RESERVED = 15
}
 Numeric constants for types of resource items. More...

Functions

U_CAPI UResourceBundle *U_EXPORT2 ures_open (const char *path, const char *locale, UErrorCode *status)
 Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.
U_CAPI UResourceBundle *U_EXPORT2 ures_openDirect (const char *path, const char *locale, UErrorCode *status)
 This function does not care what kind of localeID is passed in.
U_CAPI UResourceBundle *U_EXPORT2 ures_openW (const wchar_t *path, const char *locale, UErrorCode *status)
 Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.
U_CAPI UResourceBundle *U_EXPORT2 ures_openU (const UChar *path, const char *locale, UErrorCode *status)
 Same as ures_open() but takes a const UChar *path.
U_CAPI int32_t U_EXPORT2 ures_countArrayItems (const UResourceBundle *resourceBundle, const char *resourceKey, UErrorCode *err)
 Returns the number of strings/arrays in resource bundles.
U_CAPI void U_EXPORT2 ures_close (UResourceBundle *resourceBundle)
 close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular bundle are INVALID henceforth.
U_CAPI const char *U_EXPORT2 ures_getVersionNumber (const UResourceBundle *resourceBundle)
 Return the version number associated with this ResourceBundle as a string.
U_CAPI void U_EXPORT2 ures_getVersion (const UResourceBundle *resB, UVersionInfo versionInfo)
 Return the version number associated with this ResourceBundle as a UVersionInfo array.
U_CAPI const char *U_EXPORT2 ures_getLocale (const UResourceBundle *resourceBundle, UErrorCode *status)
 Return the name of the Locale associated with this ResourceBundle.
U_CAPI void U_EXPORT2 ures_openFillIn (UResourceBundle *r, const char *path, const char *localeID, UErrorCode *status)
 Same as ures_open() but uses the fill-in parameter instead of allocating a bundle, if r!=NULL.
U_CAPI const UChar *U_EXPORT2 ures_getString (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
 returns a string from a string resource type
U_CAPI const uint8_t *U_EXPORT2 ures_getBinary (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
 returns a binary data from a resource.
U_CAPI const int32_t *U_EXPORT2 ures_getIntVector (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
 returns a 32 bit integer array from a resource.
U_CAPI uint32_t U_EXPORT2 ures_getUInt (const UResourceBundle *resourceBundle, UErrorCode *status)
 returns an unsigned integer from a resource.
U_CAPI int32_t U_EXPORT2 ures_getInt (const UResourceBundle *resourceBundle, UErrorCode *status)
 returns a signed integer from a resource.
U_CAPI int32_t U_EXPORT2 ures_getSize (UResourceBundle *resourceBundle)
 Returns the size of a resource.
U_CAPI UResType U_EXPORT2 ures_getType (UResourceBundle *resourceBundle)
 Returns the type of a resource.
U_CAPI const char *U_EXPORT2 ures_getKey (UResourceBundle *resB)
 Returns the key associated with a given resource.
U_CAPI void U_EXPORT2 ures_resetIterator (UResourceBundle *resourceBundle)
 Resets the internal context of a resource so that iteration starts from the first element.
U_CAPI UBool U_EXPORT2 ures_hasNext (UResourceBundle *resourceBundle)
 Checks whether the given resource has another element to iterate over.
U_CAPI UResourceBundle *U_EXPORT2 ures_getNextResource (UResourceBundle *resourceBundle, UResourceBundle *fillIn, UErrorCode *status)
 Returns the next resource in a given resource or NULL if there are no more resources to iterate over.
U_CAPI const UChar *U_EXPORT2 ures_getNextString (UResourceBundle *resourceBundle, int32_t *len, const char **key, UErrorCode *status)
 Returns the next string in a given resource or NULL if there are no more resources to iterate over.
U_CAPI UResourceBundle *U_EXPORT2 ures_getByIndex (const UResourceBundle *resourceBundle, int32_t indexR, UResourceBundle *fillIn, UErrorCode *status)
 Returns the resource in a given resource at the specified index.
U_CAPI const UChar *U_EXPORT2 ures_getStringByIndex (const UResourceBundle *resB, int32_t indexS, int32_t *len, UErrorCode *status)
 Returns the string in a given resource at the specified index.
U_CAPI UResourceBundle *U_EXPORT2 ures_getByKey (const UResourceBundle *resourceBundle, const char *key, UResourceBundle *fillIn, UErrorCode *status)
 Returns a resource in a given resource that has a given key.
U_CAPI const UChar *U_EXPORT2 ures_getStringByKey (const UResourceBundle *resB, const char *key, int32_t *len, UErrorCode *status)
 Returns a string in a given resource that has a given key.


Detailed Description

C API: Resource Bundle.

C API: Resource Bundle

C API representing a collection of resource information pertaining to a given locale. A resource bundle provides a way of accessing locale- specific information in a data file. You create a resource bundle that manages the resources for a given locale and then ask it for individual resources.

The resource bundle file is a text (ASCII or Unicode) file with the format:

    locale {
       tag1 {...}
       tag2 {...}
    }
The tags are used to retrieve the data later. You may not have multiple instances of the same tag.

Four data types are supported. These are solitary strings, comma-delimited lists of strings, 2-dimensional arrays of strings, and tagged lists of strings.

Note that all data is textual. Adjacent strings are merged by the low-level tokenizer, so that the following effects occur: foo bar, baz // 2 elements, "foo bar", and "baz" "foo" "bar", baz // 2 elements, "foobar", and "baz" Note that a single intervening space is added between merged strings, unless they are both double quoted. This extends to more than two strings in a row.

Whitespace is ignored, as in a C source file.

Solitary strings have the format:

    Tag { Data }
This is indistinguishable from a comma-delimited list with only one element, and in fact may be retrieved as such (as an array, or as element 0 or an array).

Comma-delimited lists have the format:

    Tag { Data, Data, Data }
Parsing is lenient; a final string, after the last element, is allowed.

Tagged lists have the format:

    Tag { Subtag { Data } Subtag {Data} }
Data is retrieved by specifying the subtag.

Two-dimensional arrays have the format:

    TwoD {
        { r1c1, r1c2, ..., r1cm },
        { r2c1, r2c2, ..., r2cm },
        ...
        { rnc1, rnc2, ..., rncm }
    }
where n is the number of rows, and m is the number of columns. Parsing is lenient (as in other data types). A final comma is always allowed after the last element; either the last string in a row, or the last row itself. Furthermore, since there is no ambiguity, the commas between the rows are entirely optional. (However, if a comma is present, there can only be one comma, no more.) It is possible to have zero columns, as follows:
    Odd { {} {} {} } // 3 x 0 array
But it is impossible to have zero rows. The smallest array is thus a 1 x 0 array, which looks like this:
   Smallest { {} } // 1 x 0 array
The array must be strictly rectangular; that is, each row must have the same number of elements.

Usage model:

Resource bundles contain resources. In code, both types of entities are treated the same and are represented with a same data structure

UResourceBundle
. Resource bundle has a tree structure, where leaf nodes can be strings, binaries and integers while non-leaf nodes (including the root node) can be tables and arrays. One or more resource bundles are used to represent data needed by the application for running in the particular locale. Complete set of resource bundles for an application would contain all the data needed to run in intended locales.

If the data for the requested locale is missing, an effort will be made to obtain most usable data. This process is called fallback. Also, fallback happens when a resource is not present in the given bundle. Then, the other bundles in the fallback chain are also searched for the requested resource.

Retrieving data from resources is possible in several ways, depending on the type of the resources:

1) Access by a key: this approach works only for table resources

2) Access by an index: tables and arrays can be addressed by an index

3) Iteration: works for tables and arrays

To use data in resource bundles, following steps are needed:

1) opening a bundle for a particular locale:

      UErrorCode status = U_ZERO_ERROR;
      UResourceBundle* resB = ures_open("/datadir/resources/GUI", "de_AT_EURO", &status);
Status allows, besides testing for plain error, to see whether fallback occured. There are two extra non error values for status after this operation: U_USING_FALLBACK_ERROR, which implies that the bundle for the requested locale was not found, but that one of the bundles in the fallback chain was used (de_AT and de in this case) and U_USING_DEFAULT_ERROR which implies that not one bundle in the fallback chain was found and that default locale was used. In any case, 'root' locale is always at the end of the chain.

This is an example for using a possible custom resource:

     const char *currentLocale;
     UErrorCode success = U_ZERO_ERROR;
     UResourceBundle* myResources=ures_open("MyResources", currentLocale, &success );
 
     UChar *button1Title, *button2Title;
     button1Title= ures_get(myResources, "OkKey", &success );
     button2Title= ures_get(myResources, "CancelKey", &success );

Enumeration Type Documentation

enum UResType
 

Numeric constants for types of resource items.


Function Documentation

U_CAPI void U_EXPORT2 ures_close UResourceBundle resourceBundle  ) 
 

close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular bundle are INVALID henceforth.

Parameters:
resourceBundle,: a succesfully opened resourceBundle.
status,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
See also:
ures_open

ures_openW

U_CAPI int32_t U_EXPORT2 ures_countArrayItems const UResourceBundle resourceBundle,
const char *  resourceKey,
UErrorCode err
 

Returns the number of strings/arrays in resource bundles.

Parameters:
resourceBundle,: resource bundle containing the desired strings
resourceKey,: key tagging the resource
err,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
: for Arrays: returns the number of strings in the array 2d Arrays: returns the number of 1d arrays taggedArrays: returns the number of strings in the array single string: returns 1
See also:
ures_get

U_CAPI const uint8_t* U_EXPORT2 ures_getBinary const UResourceBundle resourceBundle,
int32_t *  len,
UErrorCode status
 

returns a binary data from a resource.

Can be used at most primitive resource types (binaries, strings, ints)

Parameters:
resourceBundle,: a string resource
len,: fills in the length of resulting byte chunk
status,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a pointer to a chuck of unsigned bytes which live in a memory mapped/DLL file.

U_CAPI UResourceBundle* U_EXPORT2 ures_getByIndex const UResourceBundle resourceBundle,
int32_t  indexR,
UResourceBundle fillIn,
UErrorCode status
 

Returns the resource in a given resource at the specified index.

Features a fill-in parameter.

Parameters:
resourceBundle a resource
indexR an index to the wanted resource.
fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller. Alternatively, you can supply a struct to be filled by this function.
status fills in the outgoing error code
Returns:
a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it

U_CAPI UResourceBundle* U_EXPORT2 ures_getByKey const UResourceBundle resourceBundle,
const char *  key,
UResourceBundle fillIn,
UErrorCode status
 

Returns a resource in a given resource that has a given key.

This procedure works only with table resources. Features a fill-in parameter.

Parameters:
resourceBundle a resource
key a key associated with the wanted resource
fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller. Alternatively, you can supply a struct to be filled by this function.
status fills in the outgoing error code.
Returns:
a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it

U_CAPI int32_t U_EXPORT2 ures_getInt const UResourceBundle resourceBundle,
UErrorCode status
 

returns a signed integer from a resource.

This integer is originally 28 bit and the sign gets propagated.

Parameters:
resourceBundle,: a string resource
status,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
an integer value ICU 2.0

U_CAPI const int32_t* U_EXPORT2 ures_getIntVector const UResourceBundle resourceBundle,
int32_t *  len,
UErrorCode status
 

returns a 32 bit integer array from a resource.

Parameters:
resourceBundle,: an int vector resource
len,: fills in the length of resulting byte chunk
status,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a pointer to a chuck of unsigned bytes which live in a memory mapped/DLL file. ICU 2.0

U_CAPI const char* U_EXPORT2 ures_getKey UResourceBundle resB  ) 
 

Returns the key associated with a given resource.

Not all the resources have a key - only those that are members of a table.

Parameters:
resourceBundle,: a resource
Returns:
a key associated to this resource, or NULL if it doesn't have a key

U_CAPI const char* U_EXPORT2 ures_getLocale const UResourceBundle resourceBundle,
UErrorCode status
 

Return the name of the Locale associated with this ResourceBundle.

Parameters:
resourceBundle,: resource bundle in question
status,: just for catching illegal arguments
Returns:
A Locale name

U_CAPI UResourceBundle* U_EXPORT2 ures_getNextResource UResourceBundle resourceBundle,
UResourceBundle fillIn,
UErrorCode status
 

Returns the next resource in a given resource or NULL if there are no more resources to iterate over.

Features a fill-in parameter.

Parameters:
resourceBundle a resource
fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller. Alternatively, you can supply a struct to be filled by this function.
status fills in the outgoing error code
Returns:
a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it

U_CAPI const UChar* U_EXPORT2 ures_getNextString UResourceBundle resourceBundle,
int32_t *  len,
const char **  key,
UErrorCode status
 

Returns the next string in a given resource or NULL if there are no more resources to iterate over.

Parameters:
resourceBundle a resource
len fill in length of the string
key fill in for key associated with this string
status fills in the outgoing error code
Returns:
a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

U_CAPI int32_t U_EXPORT2 ures_getSize UResourceBundle resourceBundle  ) 
 

Returns the size of a resource.

Size for scalar types is always 1, and for vector/table types is the number of child resources.

Parameters:
resourceBundle,: a resource
Returns:
number of resources in a given resource.

U_CAPI const UChar* U_EXPORT2 ures_getString const UResourceBundle resourceBundle,
int32_t *  len,
UErrorCode status
 

returns a string from a string resource type

Parameters:
resourceBundle,: a string resource
len,: fills in the length of resulting string
status,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

U_CAPI const UChar* U_EXPORT2 ures_getStringByIndex const UResourceBundle resB,
int32_t  indexS,
int32_t *  len,
UErrorCode status
 

Returns the string in a given resource at the specified index.

Parameters:
resourceBundle a resource
indexS an index to the wanted string.
len fill in length of the string
status fills in the outgoing error code
Returns:
a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

U_CAPI const UChar* U_EXPORT2 ures_getStringByKey const UResourceBundle resB,
const char *  key,
int32_t *  len,
UErrorCode status
 

Returns a string in a given resource that has a given key.

This procedure works only with table resources.

Parameters:
resB a resource
key a key associated with the wanted string
len fill in length of the string
status fills in the outgoing error code
Returns:
a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

U_CAPI UResType U_EXPORT2 ures_getType UResourceBundle resourceBundle  ) 
 

Returns the type of a resource.

Available types are defined in enum UResType

Parameters:
resourceBundle,: a resource
Returns:
type of the given resource.

U_CAPI uint32_t U_EXPORT2 ures_getUInt const UResourceBundle resourceBundle,
UErrorCode status
 

returns an unsigned integer from a resource.

This integer is originally 28 bits.

Parameters:
resourceBundle,: a string resource
status,: fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</t> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
an integer value ICU 2.0

U_CAPI void U_EXPORT2 ures_getVersion const UResourceBundle resB,
UVersionInfo  versionInfo
 

Return the version number associated with this ResourceBundle as a UVersionInfo array.

Parameters:
resourceBundle The resource bundle for which the version is checked.
versionInfo A UVersionInfo array that is filled with the version number as specified in the resource bundle or its parent.

U_CAPI const char* U_EXPORT2 ures_getVersionNumber const UResourceBundle resourceBundle  ) 
 

Return the version number associated with this ResourceBundle as a string.

Parameters:
resourceBundle The resource bundle for which the version is checked.
Returns:
A version number string as specified in the resource bundle or its parent. The caller does not own this string.

U_CAPI UBool U_EXPORT2 ures_hasNext UResourceBundle resourceBundle  ) 
 

Checks whether the given resource has another element to iterate over.

Parameters:
resourceBundle a resource
Returns:
TRUE if there are more elements, FALSE if there is no more elements

U_CAPI UResourceBundle* U_EXPORT2 ures_open const char *  path,
const char *  locale,
UErrorCode status
 

Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.

Note that the caller is responsible of calling ures_close on each succesfully opened resource bundle.

Parameters:
path : string containing the full path pointing to the directory where the resources reside followed by the package name e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. if NULL, ICU default data files will be used.
locale,: specifies the locale for which we want to open the resource if NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
status : fills in the outgoing error code. The UErrorCode err parameter is used to return status information to the user. To check whether the construction succeeded or not, you should check the value of U_SUCCESS(err). If you wish more detailed information, you can check for informational error results which still indicate success. U_USING_FALLBACK_ERROR indicates that a fall back locale was used. For example, 'de_CH' was requested, but nothing was found there, so 'de' was used. U_USING_DEFAULT_ERROR indicates that the default locale data or root locale data was used; neither the requested locale nor any of its fall back locales could be found.
Returns:
a newly allocated resource bundle.
See also:
ures_close

U_CAPI UResourceBundle* U_EXPORT2 ures_openDirect const char *  path,
const char *  locale,
UErrorCode status
 

This function does not care what kind of localeID is passed in.

It simply opens a bundle with that name. Fallback mechanism is disabled for the new bundle. If the requested bundle contains an %ALIAS directive, the results are undefined.

Parameters:
path : string containing the full path pointing to the directory where the resources reside followed by the package name e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. if NULL, ICU default data files will be used.
locale,: specifies the locale for which we want to open the resource if NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
status fills in the outgoing error code. Either U_ZERO_ERROR or U_MISSING_RESOURCE_ERROR
Returns:
a newly allocated resource bundle or NULL if it doesn't exist.
See also:
ures_close ICU 2.0

U_CAPI void U_EXPORT2 ures_openFillIn UResourceBundle r,
const char *  path,
const char *  localeID,
UErrorCode status
 

Same as ures_open() but uses the fill-in parameter instead of allocating a bundle, if r!=NULL.

TODO need to revisit usefulness of this function and usage model for fillIn parameters without knowing sizeof(UResourceBundle)

For internal use only.

U_CAPI UResourceBundle* U_EXPORT2 ures_openU const UChar path,
const char *  locale,
UErrorCode status
 

Same as ures_open() but takes a const UChar *path.

This path will be converted to char * using the default converter, then ures_open() is called.

U_CAPI UResourceBundle* U_EXPORT2 ures_openW const wchar_t *  path,
const char *  locale,
UErrorCode status
 

Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.

This version of open requires the path string to be of type const wchar_t*. Note that the caller is responsible of calling ures_close on each succesfully opened resource bundle.

Parameters:
path,: string containing the full path pointing to the directory where the resources reside (should end with a directory separator. e.g. "/usr/resource/my_app/resources/" on a Unix system if NULL will use the system's current data directory
locale,: specifies the locale for which we want to open the resource if NULL will use the default locale
status,: fills in the outgoing error code.
See also:
ures_close
Returns:
: a newly allocated resource bundle. remove after Aug 2002

U_CAPI void U_EXPORT2 ures_resetIterator UResourceBundle resourceBundle  ) 
 

Resets the internal context of a resource so that iteration starts from the first element.

Parameters:
resourceBundle,: a resource


Generated on Tue Jul 26 18:11:53 2005 for ICU 2.1 by  doxygen 1.4.3-20050530