Logo Search packages:      
Sourcecode: icu version File versions

ures.h File Reference


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 );

Definition in file ures.h.

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

Go to the source code of this file.

Typedefs

typedef struct 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
}

Functions

U_CAPI void U_EXPORT2 ures_close (UResourceBundle *resourceBundle)
U_CAPI int32_t U_EXPORT2 ures_countArrayItems (const UResourceBundle *resourceBundle, const char *resourceKey, UErrorCode *err)
U_CAPI const uint8_t *U_EXPORT2 ures_getBinary (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
U_CAPI UResourceBundle *U_EXPORT2 ures_getByIndex (const UResourceBundle *resourceBundle, int32_t indexR, UResourceBundle *fillIn, UErrorCode *status)
U_CAPI UResourceBundle *U_EXPORT2 ures_getByKey (const UResourceBundle *resourceBundle, const char *key, UResourceBundle *fillIn, UErrorCode *status)
U_CAPI int32_t U_EXPORT2 ures_getInt (const UResourceBundle *resourceBundle, UErrorCode *status)
U_CAPI const int32_t *U_EXPORT2 ures_getIntVector (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
U_CAPI const char *U_EXPORT2 ures_getKey (UResourceBundle *resB)
U_CAPI const char *U_EXPORT2 ures_getLocale (const UResourceBundle *resourceBundle, UErrorCode *status)
U_CAPI UResourceBundle *U_EXPORT2 ures_getNextResource (UResourceBundle *resourceBundle, UResourceBundle *fillIn, UErrorCode *status)
U_CAPI const UChar *U_EXPORT2 ures_getNextString (UResourceBundle *resourceBundle, int32_t *len, const char **key, UErrorCode *status)
U_CAPI int32_t U_EXPORT2 ures_getSize (UResourceBundle *resourceBundle)
U_CAPI const UChar *U_EXPORT2 ures_getString (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
U_CAPI const UChar *U_EXPORT2 ures_getStringByIndex (const UResourceBundle *resB, int32_t indexS, int32_t *len, UErrorCode *status)
U_CAPI const UChar *U_EXPORT2 ures_getStringByKey (const UResourceBundle *resB, const char *key, int32_t *len, UErrorCode *status)
U_CAPI UResType U_EXPORT2 ures_getType (UResourceBundle *resourceBundle)
U_CAPI uint32_t U_EXPORT2 ures_getUInt (const UResourceBundle *resourceBundle, UErrorCode *status)
U_CAPI void U_EXPORT2 ures_getVersion (const UResourceBundle *resB, UVersionInfo versionInfo)
U_CAPI const char *U_EXPORT2 ures_getVersionNumber (const UResourceBundle *resourceBundle)
U_CAPI UBool U_EXPORT2 ures_hasNext (UResourceBundle *resourceBundle)
U_CAPI UResourceBundle *U_EXPORT2 ures_open (const char *path, const char *locale, UErrorCode *status)
U_CAPI UResourceBundle *U_EXPORT2 ures_openDirect (const char *path, const char *locale, UErrorCode *status)
U_CAPI void U_EXPORT2 ures_openFillIn (UResourceBundle *r, const char *path, const char *localeID, UErrorCode *status)
U_CAPI UResourceBundle *U_EXPORT2 ures_openU (const UChar *path, const char *locale, UErrorCode *status)
U_CAPI UResourceBundle *U_EXPORT2 ures_openW (const wchar_t *path, const char *locale, UErrorCode *status)
U_CAPI void U_EXPORT2 ures_resetIterator (UResourceBundle *resourceBundle)


Generated by  Doxygen 1.6.0   Back to index