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

/*
**********************************************************************
*   Copyright (C) 2000-2004, 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

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

#endif /*URESIMP_H*/
Commit	Line	Data
b75a7d8f A	1	/*
b75a7d8f A	2	**********************************************************************
374ca955	3	* Copyright (C) 2000-2004, 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
	30
	31	/*
	32	enum UResEntryType {
	33	ENTRY_OK = 0,
	34	ENTRY_GOTO_ROOT = 1,
	35	ENTRY_GOTO_DEFAULT = 2,
	36	ENTRY_INVALID = 3
	37	};
	38
	39	typedef enum UResEntryType UResEntryType;
	40	*/
	41
	42	struct UResourceDataEntry;
	43	typedef struct UResourceDataEntry UResourceDataEntry;
	44
	45	struct UResourceDataEntry {
	46	char fName; / name of the locale for bundle - still to decide whether it is original or fallback */
	47	char fPath; / path to bundle - used for distinguishing between resources with the same name */
	48	uint32_t fCountExisting; /* how much is this resource used */
	49	ResourceData fData; /* data for low level access */
	50	UResourceDataEntry fParent; /next resource in fallback chain*/
	51	/* UResEntryType fStatus;*/
	52	UErrorCode fBogus;
	53	int32_t fHashKey; /* for faster access in the hashtable */
	54	};
	55
374ca955	56	#define RES_BUFSIZE 64
b75a7d8f A	57	#define RES_PATH_SEPARATOR '/'
	58	#define RES_PATH_SEPARATOR_S "/"
	59
	60	struct UResourceBundle {
	61	const char fKey; /tag*/
	62	UResourceDataEntry fData; /for low-level access*/
	63	char *fVersion;
	64	char fResPath; / full path to the resource: "zh_TW/CollationElements/Sequence" */
	65	char fResBuf[RES_BUFSIZE];
	66	int32_t fResPathLen;
	67	UBool fHasFallback;
	68	UBool fIsTopLevel;
	69	uint32_t fMagic1; /* For determining if it's a stack object */
	70	uint32_t fMagic2; /* For determining if it's a stack object */
	71	int32_t fIndex;
	72	int32_t fSize;
	73	ResourceData fResData;
	74	Resource fRes;
	75
374ca955 A	76	UResourceDataEntry fTopLevelData; / for getting the valid locale */
	77	const UResourceBundle fParentRes; / needed to get the actual locale for a child resource */
	78
b75a7d8f A	79	};
b75a7d8f A	80
374ca955	81	U_CAPI void U_EXPORT2 ures_initStackObject(UResourceBundle* resB);
b75a7d8f A	82
	83	/* Some getters used by the copy constructor */
	84	U_CFUNC const char* ures_getName(const UResourceBundle* resB);
	85	U_CFUNC const char* ures_getPath(const UResourceBundle* resB);
	86	U_CFUNC void ures_appendResPath(UResourceBundle resB, const char toAdd, int32_t lenToAdd);
	87	/U_CFUNC void ures_setResPath(UResourceBundle resB, const char* toAdd);*/
	88	U_CFUNC void ures_freeResPath(UResourceBundle *resB);
	89
	90	/* Candidates for export */
	91	U_CFUNC UResourceBundle ures_copyResb(UResourceBundle r, const UResourceBundle original, UErrorCode status);
	92
	93	/**
	94	* Returns a resource that can be located using the pathToResource argument. One needs optional package, locale
	95	* and path inside the locale, for example: "/myData/en/zoneStrings/3". Keys and indexes are supported. Keys
	96	* need to reference data in named structures, while indexes can reference both named and anonymous resources.
	97	* Features a fill-in parameter.
374ca955 A	98	*
	99	* Note, this function does NOT have a syntax for specifying items within a tree. May want to consider a
	100	* syntax that delineates between package/tree and resource.
b75a7d8f A	101	*
	102	* @param pathToResource a path that will lead to the requested resource
	103	* @param fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
	104	* Alternatively, you can supply a struct to be filled by this function.
	105	* @param status fills in the outgoing error code.
	106	* @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
	107	* @draft ICU 2.2
	108	*/
	109	U_CAPI UResourceBundle* U_EXPORT2
	110	ures_findResource(const char* pathToResource,
	111	UResourceBundle fillIn, UErrorCode status);
	112
	113	/**
	114	* Returns a sub resource that can be located using the pathToResource argument. One needs a path inside
	115	* the supplied resource, for example, if you have "en_US" resource bundle opened, you might ask for
	116	* "zoneStrings/3". Keys and indexes are supported. Keys
	117	* need to reference data in named structures, while indexes can reference both
	118	* named and anonymous resources.
	119	* Features a fill-in parameter.
	120	*
	121	* @param resourceBundle a resource
	122	* @param pathToResource a path that will lead to the requested resource
	123	* @param fillIn if NULL a new UResourceBundle struct is allocated and must be deleted by the caller.
	124	* Alternatively, you can supply a struct to be filled by this function.
	125	* @param status fills in the outgoing error code.
	126	* @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must delete it
	127	* @draft ICU 2.2
	128	*/
	129	U_CAPI UResourceBundle* U_EXPORT2
	130	ures_findSubResource(const UResourceBundle *resB,
374ca955	131	char* pathToResource,
b75a7d8f A	132	UResourceBundle fillIn, UErrorCode status);
b75a7d8f A	133
374ca955 A	134	/**
	135	* Returns a functionally equivalent locale (considering keywords) for the specified keyword.
	136	* @param result fillin for the equivalent locale
	137	* @param resultCapacity capacity of the fillin buffer
	138	* @param path path to the tree, or NULL for ICU data
	139	* @param resName top level resource. Example: "collations"
	140	* @param keyword locale keyword. Example: "collation"
	141	* @param locid The requested locale
	142	* @param isAvailable If non-null, pointer to fillin parameter that indicates whether the
	143	* requested locale was available. The locale is defined as 'available' if it physically
	144	* exists within the specified tree.
	145	* @param omitDefault if TRUE, omit keyword and value if default. 'de_DE\@collation=standard' -> 'de_DE'
	146	* @param status error code
	147	* @return the actual buffer size needed for the full locale. If it's greater
	148	* than resultCapacity, the returned full name will be truncated and an error code will be returned.
	149	* @internal ICU 3.0
	150	*/
	151	U_INTERNAL int32_t U_EXPORT2
	152	ures_getFunctionalEquivalent(char *result, int32_t resultCapacity,
	153	const char path, const char resName, const char keyword, const char locid,
	154	UBool isAvailable, UBool omitDefault, UErrorCode status);
	155
	156	/**
	157	* Given a tree path and keyword, return a string enumeration of all possible values for that keyword.
	158	* @param path path to the tree, or NULL for ICU data
	159	* @param keyword a particular keyword to consider, must match a top level resource name
	160	* within the tree.
	161	* @param status error code
	162	* @internal ICU 3.0
	163	*/
	164	U_INTERNAL UEnumeration* U_EXPORT2
	165	ures_getKeywordValues(const char path, const char keyword, UErrorCode *status);
	166
b75a7d8f	167	#endif /URESIMP_H/