[apple/icu.git] / icuSources / common / uresimp.h

/*
**********************************************************************
*   Copyright (C) 2000-2006, International Business Machines
*   Corporation and others.  All Rights Reserved.
**********************************************************************
*/

#ifndef URESIMP_H
#define URESIMP_H

#include "unicode/ures.h"

#include "uresdata.h"

#define kRootLocaleName         "root"

/*
 The default minor version and the version separator must be exactly one
 character long.
*/

#define kDefaultMinorVersion    "0"
#define kVersionSeparator       "."
#define kVersionTag             "Version"

#define MAGIC1 19700503
#define MAGIC2 19641227

#define URES_MAX_ALIAS_LEVEL 256
#define URES_MAX_BUFFER_SIZE 256

/*
enum UResEntryType {
    ENTRY_OK = 0,
    ENTRY_GOTO_ROOT = 1,
    ENTRY_GOTO_DEFAULT = 2,
    ENTRY_INVALID = 3
};

typedef enum UResEntryType UResEntryType;
*/

struct UResourceDataEntry;
typedef struct UResourceDataEntry UResourceDataEntry;

struct UResourceDataEntry {
    char *fName; /* name of the locale for bundle - still to decide whether it is original or fallback */
    char *fPath; /* path to bundle - used for distinguishing between resources with the same name */
    uint32_t fCountExisting; /* how much is this resource used */
    ResourceData fData; /* data for low level access */
    UResourceDataEntry *fParent; /*next resource in fallback chain*/
/*    UResEntryType fStatus;*/
    UErrorCode fBogus;
    int32_t fHashKey; /* for faster access in the hashtable */
};

#define RES_BUFSIZE 64
#define RES_PATH_SEPARATOR   '/'
#define RES_PATH_SEPARATOR_S   "/"

struct UResourceBundle {
    const char *fKey; /*tag*/
    UResourceDataEntry *fData; /*for low-level access*/
    char *fVersion;
    char *fResPath; /* full path to the resource: "zh_TW/CollationElements/Sequence" */
    char fResBuf[RES_BUFSIZE];
    int32_t fResPathLen;
    UBool fHasFallback;
    UBool fIsTopLevel;
    uint32_t fMagic1;   /* For determining if it's a stack object */
    uint32_t fMagic2;   /* For determining if it's a stack object */
    int32_t fIndex;
    int32_t fSize;
    ResourceData fResData;
    Resource fRes;

    UResourceDataEntry *fTopLevelData; /* for getting the valid locale */
    const UResourceBundle *fParentRes; /* needed to get the actual locale for a child resource */

};

U_CAPI void U_EXPORT2 ures_initStackObject(UResourceBundle* resB);

/* Some getters used by the copy constructor */
U_CFUNC const char* ures_getName(const UResourceBundle* resB);
U_CFUNC const char* ures_getPath(const UResourceBundle* resB);
/*U_CFUNC void ures_appendResPath(UResourceBundle *resB, const char* toAdd, int32_t lenToAdd);*/
/*U_CFUNC void ures_setResPath(UResourceBundle *resB, const char* toAdd);*/
/*U_CFUNC void ures_freeResPath(UResourceBundle *resB);*/

/* Candidates for export */
U_CFUNC UResourceBundle *ures_copyResb(UResourceBundle *r, const UResourceBundle *original, UErrorCode *status);

/**
 * Returns a resource that can be located using the pathToResource argument. One needs optional package, locale
 * and path inside the locale, for example: "/myData/en/zoneStrings/3". Keys and indexes are supported. Keys
 * need to reference data in named structures, while indexes can reference both named and anonymous resources.
 * Features a fill-in parameter. 
 * 
 * Note, this function does NOT have a syntax for specifying items within a tree.  May want to consider a
 * syntax that delineates between package/tree and resource.  
 *
 * @param pathToResource    a path that will lead to the requested resource
 * @param 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.
 * @param status            fills in the outgoing error code.
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 * @draft ICU 2.2
 */
U_CAPI UResourceBundle* U_EXPORT2
ures_findResource(const char* pathToResource, 
                  UResourceBundle *fillIn, UErrorCode *status); 

/**
 * Returns a sub resource that can be located using the pathToResource argument. One needs a path inside 
 * the supplied resource, for example, if you have "en_US" resource bundle opened, you might ask for
 * "zoneStrings/3". Keys and indexes are supported. Keys
 * need to reference data in named structures, while indexes can reference both 
 * named and anonymous resources.
 * Features a fill-in parameter. 
 *
 * @param resourceBundle    a resource
 * @param pathToResource    a path that will lead to the requested resource
 * @param 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.
 * @param status            fills in the outgoing error code.
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 * @draft ICU 2.2
 */
U_CAPI UResourceBundle* U_EXPORT2
ures_findSubResource(const UResourceBundle *resB, 
                     char* pathToResource, 
                     UResourceBundle *fillIn, UErrorCode *status);

/**
 * Returns a functionally equivalent locale (considering keywords) for the specified keyword.
 * @param result fillin for the equivalent locale
 * @param resultCapacity capacity of the fillin buffer
 * @param path path to the tree, or NULL for ICU data
 * @param resName top level resource. Example: "collations"
 * @param keyword locale keyword. Example: "collation"
 * @param locid The requested locale
 * @param isAvailable If non-null, pointer to fillin parameter that indicates whether the 
 * requested locale was available. The locale is defined as 'available' if it physically 
 * exists within the specified tree.
 * @param omitDefault if TRUE, omit keyword and value if default. 'de_DE\@collation=standard' -> 'de_DE'
 * @param status error code
 * @return  the actual buffer size needed for the full locale.  If it's greater 
 * than resultCapacity, the returned full name will be truncated and an error code will be returned.
 * @internal ICU 3.0
 */
U_INTERNAL int32_t U_EXPORT2
ures_getFunctionalEquivalent(char *result, int32_t resultCapacity, 
                             const char *path, const char *resName, const char *keyword, const char *locid,
                             UBool *isAvailable, UBool omitDefault, UErrorCode *status);

/**
 * Given a tree path and keyword, return a string enumeration of all possible values for that keyword.
 * @param path path to the tree, or NULL for ICU data
 * @param keyword a particular keyword to consider, must match a top level resource name 
 * within the tree.
 * @param status error code
 * @internal ICU 3.0
 */
U_INTERNAL UEnumeration* U_EXPORT2
ures_getKeywordValues(const char *path, const char *keyword, UErrorCode *status);

/**
 * Test if 2 resource bundles are equal
 * @param res1
 * @param res2
 * @param status error code
 * @internal ICU 3.6
 */
U_INTERNAL UBool U_EXPORT2
ures_equal(const UResourceBundle* res1, const UResourceBundle* res2);

/**
 * Clones the given resource bundle
 * @param res
 * @param status error code
 * @internal ICU 3.6
 */
U_INTERNAL UResourceBundle* U_EXPORT2
ures_clone(const UResourceBundle* res, UErrorCode* status);

/**
 * Returns the parent bundle. Internal. DONOT close the returned bundle!!!
 * @param res
 * @internal ICU 3.6
 */
U_INTERNAL const UResourceBundle* U_EXPORT2
ures_getParentBundle(const UResourceBundle* res);


/**
 * Get a resource with multi-level fallback. Normally only the top level resources will
 * fallback to its parent. This performs fallback on subresources. For example, when a table
 * is defined in a resource bundle and a parent resource bundle, normally no fallback occurs
 * on the sub-resources because the table is defined in the current resource bundle, but this
 * function can perform fallback on the sub-resources of the table.
 * @param resB              a resource
 * @param inKey             a key associated with the requested resource
 * @param 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.
 * @param status: fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                could be a non-failing error 
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 * @internal ICU 3.0
 */
U_INTERNAL UResourceBundle* U_EXPORT2 
ures_getByKeyWithFallback(const UResourceBundle *resB, 
                          const char* inKey, 
                          UResourceBundle *fillIn, 
                          UErrorCode *status);


/**
 * Get a String with multi-level fallback. Normally only the top level resources will
 * fallback to its parent. This performs fallback on subresources. For example, when a table
 * is defined in a resource bundle and a parent resource bundle, normally no fallback occurs
 * on the sub-resources because the table is defined in the current resource bundle, but this
 * function can perform fallback on the sub-resources of the table.
 * @param resB              a resource
 * @param inKey             a key associated with the requested resource
 * @param status: fills in the outgoing error code
 *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 *                could be a non-failing error 
 *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 * @return                  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
 * @internal ICU 3.4
 * @draft ICU 3.4
 */
U_INTERNAL const UChar* U_EXPORT2 
ures_getStringByKeyWithFallback(const UResourceBundle *resB, 
                          const char* inKey,  
                          int32_t* len,
                          UErrorCode *status);
#endif /*URESIMP_H*/
Commit	Line	Data
b75a7d8f A	1	/*
b75a7d8f A	2	**********************************************************************
73c04bcf	3	* Copyright (C) 2000-2006, International Business Machines
b75a7d8f A	4	* Corporation and others. All Rights Reserved.
	5	**********************************************************************
	6	*/
	7
	8	#ifndef URESIMP_H
	9	#define URESIMP_H
	10
	11	#include "unicode/ures.h"
	12
	13	#include "uresdata.h"
	14
	15	#define kRootLocaleName "root"
	16
	17	/*
	18	The default minor version and the version separator must be exactly one
	19	character long.
	20	*/
	21
	22	#define kDefaultMinorVersion "0"
	23	#define kVersionSeparator "."
	24	#define kVersionTag "Version"
	25
	26	#define MAGIC1 19700503
	27	#define MAGIC2 19641227
	28
	29	#define URES_MAX_ALIAS_LEVEL 256
73c04bcf	30	#define URES_MAX_BUFFER_SIZE 256
b75a7d8f A	31
	32	/*
	33	enum UResEntryType {
	34	ENTRY_OK = 0,
	35	ENTRY_GOTO_ROOT = 1,
	36	ENTRY_GOTO_DEFAULT = 2,
	37	ENTRY_INVALID = 3
	38	};
	39
	40	typedef enum UResEntryType UResEntryType;
	41	*/
	42
	43	struct UResourceDataEntry;
	44	typedef struct UResourceDataEntry UResourceDataEntry;
	45
	46	struct UResourceDataEntry {
	47	char fName; / name of the locale for bundle - still to decide whether it is original or fallback */
	48	char fPath; / path to bundle - used for distinguishing between resources with the same name */
	49	uint32_t fCountExisting; /* how much is this resource used */
	50	ResourceData fData; /* data for low level access */
	51	UResourceDataEntry fParent; /next resource in fallback chain*/
	52	/* UResEntryType fStatus;*/
	53	UErrorCode fBogus;
	54	int32_t fHashKey; /* for faster access in the hashtable */
	55	};
	56
374ca955	57	#define RES_BUFSIZE 64
b75a7d8f A	58	#define RES_PATH_SEPARATOR '/'
	59	#define RES_PATH_SEPARATOR_S "/"
	60
	61	struct UResourceBundle {
	62	const char fKey; /tag*/
	63	UResourceDataEntry fData; /for low-level access*/
	64	char *fVersion;
	65	char fResPath; / full path to the resource: "zh_TW/CollationElements/Sequence" */
	66	char fResBuf[RES_BUFSIZE];
	67	int32_t fResPathLen;
	68	UBool fHasFallback;
	69	UBool fIsTopLevel;
	70	uint32_t fMagic1; /* For determining if it's a stack object */
	71	uint32_t fMagic2; /* For determining if it's a stack object */
	72	int32_t fIndex;
	73	int32_t fSize;
	74	ResourceData fResData;
	75	Resource fRes;
	76
374ca955 A	77	UResourceDataEntry fTopLevelData; / for getting the valid locale */
	78	const UResourceBundle fParentRes; / needed to get the actual locale for a child resource */
	79
b75a7d8f A	80	};
b75a7d8f A	81
374ca955	82	U_CAPI void U_EXPORT2 ures_initStackObject(UResourceBundle* resB);
b75a7d8f A	83
	84	/* Some getters used by the copy constructor */
	85	U_CFUNC const char* ures_getName(const UResourceBundle* resB);
	86	U_CFUNC const char* ures_getPath(const UResourceBundle* resB);
73c04bcf	87	/U_CFUNC void ures_appendResPath(UResourceBundle resB, const char* toAdd, int32_t lenToAdd);*/
b75a7d8f	88	/U_CFUNC void ures_setResPath(UResourceBundle resB, const char* toAdd);*/
73c04bcf	89	/U_CFUNC void ures_freeResPath(UResourceBundle resB);*/
b75a7d8f A	90
	91	/* Candidates for export */
	92	U_CFUNC UResourceBundle ures_copyResb(UResourceBundle r, const UResourceBundle original, UErrorCode status);
	93
	94	/**
	95	* Returns a resource that can be located using the pathToResource argument. One needs optional package, locale
	96	* and path inside the locale, for example: "/myData/en/zoneStrings/3". Keys and indexes are supported. Keys
	97	* need to reference data in named structures, while indexes can reference both named and anonymous resources.
	98	* Features a fill-in parameter.
374ca955 A	99	*
	100	* Note, this function does NOT have a syntax for specifying items within a tree. May want to consider a
	101	* syntax that delineates between package/tree and resource.
b75a7d8f A	102	*
	103	* @param pathToResource a path that will lead to the requested resource
	104	* @param fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
	105	* Alternatively, you can supply a struct to be filled by this function.
	106	* @param status fills in the outgoing error code.
	107	* @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
	108	* @draft ICU 2.2
	109	*/
	110	U_CAPI UResourceBundle* U_EXPORT2
	111	ures_findResource(const char* pathToResource,
	112	UResourceBundle fillIn, UErrorCode status);
	113
	114	/**
	115	* Returns a sub resource that can be located using the pathToResource argument. One needs a path inside
	116	* the supplied resource, for example, if you have "en_US" resource bundle opened, you might ask for
	117	* "zoneStrings/3". Keys and indexes are supported. Keys
	118	* need to reference data in named structures, while indexes can reference both
	119	* named and anonymous resources.
	120	* Features a fill-in parameter.
	121	*
	122	* @param resourceBundle a resource
	123	* @param pathToResource a path that will lead to the requested resource
	124	* @param fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
	125	* Alternatively, you can supply a struct to be filled by this function.
	126	* @param status fills in the outgoing error code.
	127	* @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
	128	* @draft ICU 2.2
	129	*/
	130	U_CAPI UResourceBundle* U_EXPORT2
	131	ures_findSubResource(const UResourceBundle *resB,
374ca955	132	char* pathToResource,
b75a7d8f A	133	UResourceBundle fillIn, UErrorCode status);
b75a7d8f A	134
374ca955 A	135	/**
	136	* Returns a functionally equivalent locale (considering keywords) for the specified keyword.
	137	* @param result fillin for the equivalent locale
	138	* @param resultCapacity capacity of the fillin buffer
	139	* @param path path to the tree, or NULL for ICU data
	140	* @param resName top level resource. Example: "collations"
	141	* @param keyword locale keyword. Example: "collation"
	142	* @param locid The requested locale
	143	* @param isAvailable If non-null, pointer to fillin parameter that indicates whether the
	144	* requested locale was available. The locale is defined as 'available' if it physically
	145	* exists within the specified tree.
	146	* @param omitDefault if TRUE, omit keyword and value if default. 'de_DE\@collation=standard' -> 'de_DE'
	147	* @param status error code
	148	* @return the actual buffer size needed for the full locale. If it's greater
	149	* than resultCapacity, the returned full name will be truncated and an error code will be returned.
	150	* @internal ICU 3.0
	151	*/
	152	U_INTERNAL int32_t U_EXPORT2
	153	ures_getFunctionalEquivalent(char *result, int32_t resultCapacity,
	154	const char path, const char resName, const char keyword, const char locid,
	155	UBool isAvailable, UBool omitDefault, UErrorCode status);
	156
	157	/**
	158	* Given a tree path and keyword, return a string enumeration of all possible values for that keyword.
	159	* @param path path to the tree, or NULL for ICU data
	160	* @param keyword a particular keyword to consider, must match a top level resource name
	161	* within the tree.
	162	* @param status error code
	163	* @internal ICU 3.0
	164	*/
	165	U_INTERNAL UEnumeration* U_EXPORT2
	166	ures_getKeywordValues(const char path, const char keyword, UErrorCode *status);
	167
73c04bcf A	168	/**
	169	* Test if 2 resource bundles are equal
	170	* @param res1
	171	* @param res2
	172	* @param status error code
	173	* @internal ICU 3.6
	174	*/
	175	U_INTERNAL UBool U_EXPORT2
	176	ures_equal(const UResourceBundle* res1, const UResourceBundle* res2);
	177
	178	/**
	179	* Clones the given resource bundle
	180	* @param res
	181	* @param status error code
	182	* @internal ICU 3.6
	183	*/
	184	U_INTERNAL UResourceBundle* U_EXPORT2
	185	ures_clone(const UResourceBundle* res, UErrorCode* status);
	186
	187	/**
	188	* Returns the parent bundle. Internal. DONOT close the returned bundle!!!
	189	* @param res
	190	* @internal ICU 3.6
	191	*/
	192	U_INTERNAL const UResourceBundle* U_EXPORT2
	193	ures_getParentBundle(const UResourceBundle* res);
	194
	195
	196	/**
	197	* Get a resource with multi-level fallback. Normally only the top level resources will
	198	* fallback to its parent. This performs fallback on subresources. For example, when a table
	199	* is defined in a resource bundle and a parent resource bundle, normally no fallback occurs
	200	* on the sub-resources because the table is defined in the current resource bundle, but this
	201	* function can perform fallback on the sub-resources of the table.
	202	* @param resB a resource
	203	* @param inKey a key associated with the requested resource
	204	* @param fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
	205	* Alternatively, you can supply a struct to be filled by this function.
	206	* @param status: fills in the outgoing error code
	207	* could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
	208	* could be a non-failing error
	209	* e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
	210	* @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
	211	* @internal ICU 3.0
	212	*/
	213	U_INTERNAL UResourceBundle* U_EXPORT2
	214	ures_getByKeyWithFallback(const UResourceBundle *resB,
	215	const char* inKey,
	216	UResourceBundle *fillIn,
	217	UErrorCode *status);
	218
	219
	220	/**
	221	* Get a String with multi-level fallback. Normally only the top level resources will
	222	* fallback to its parent. This performs fallback on subresources. For example, when a table
	223	* is defined in a resource bundle and a parent resource bundle, normally no fallback occurs
	224	* on the sub-resources because the table is defined in the current resource bundle, but this
	225	* function can perform fallback on the sub-resources of the table.
	226	* @param resB a resource
	227	* @param inKey a key associated with the requested resource
	228	* @param status: 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_DEFAULT_WARNING </TT>
232	* @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
233	* @internal ICU 3.4
234	* @draft ICU 3.4
235	*/
236	U_INTERNAL const UChar* U_EXPORT2
237	ures_getStringByKeyWithFallback(const UResourceBundle *resB,
238	const char* inKey,
239	int32_t* len,
240	UErrorCode *status);
b75a7d8f	241	#endif /URESIMP_H/