1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/uresdata.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,399 @@
1.4 +/*
1.5 +******************************************************************************
1.6 +* *
1.7 +* Copyright (C) 1999-2012, International Business Machines *
1.8 +* Corporation and others. All Rights Reserved. *
1.9 +* *
1.10 +******************************************************************************
1.11 +* file name: uresdata.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 1999dec08
1.17 +* created by: Markus W. Scherer
1.18 +* 06/24/02 weiv Added support for resource sharing
1.19 +*/
1.20 +
1.21 +#ifndef __RESDATA_H__
1.22 +#define __RESDATA_H__
1.23 +
1.24 +#include "unicode/utypes.h"
1.25 +#include "unicode/udata.h"
1.26 +#include "unicode/ures.h"
1.27 +#include "putilimp.h"
1.28 +#include "udataswp.h"
1.29 +
1.30 +/**
1.31 + * Numeric constants for internal-only types of resource items.
1.32 + * These must use different numeric values than UResType constants
1.33 + * because they are used together.
1.34 + * Internal types are never returned by ures_getType().
1.35 + */
1.36 +typedef enum {
1.37 + /** Include a negative value so that the compiler uses the same int type as for UResType. */
1.38 + URES_INTERNAL_NONE=-1,
1.39 +
1.40 + /** Resource type constant for tables with 32-bit count, key offsets and values. */
1.41 + URES_TABLE32=4,
1.42 +
1.43 + /**
1.44 + * Resource type constant for tables with 16-bit count, key offsets and values.
1.45 + * All values are URES_STRING_V2 strings.
1.46 + */
1.47 + URES_TABLE16=5,
1.48 +
1.49 + /** Resource type constant for 16-bit Unicode strings in formatVersion 2. */
1.50 + URES_STRING_V2=6,
1.51 +
1.52 + /**
1.53 + * Resource type constant for arrays with 16-bit count and values.
1.54 + * All values are URES_STRING_V2 strings.
1.55 + */
1.56 + URES_ARRAY16=9
1.57 +} UResInternalType;
1.58 +
1.59 +/*
1.60 + * A Resource is a 32-bit value that has 2 bit fields:
1.61 + * 31..28 4-bit type, see enum below
1.62 + * 27..0 28-bit four-byte-offset or value according to the type
1.63 + */
1.64 +typedef uint32_t Resource;
1.65 +
1.66 +#define RES_BOGUS 0xffffffff
1.67 +
1.68 +#define RES_GET_TYPE(res) ((int32_t)((res)>>28UL))
1.69 +#define RES_GET_OFFSET(res) ((res)&0x0fffffff)
1.70 +#define RES_GET_POINTER(pRoot, res) ((pRoot)+RES_GET_OFFSET(res))
1.71 +
1.72 +/* get signed and unsigned integer values directly from the Resource handle */
1.73 +#if U_SIGNED_RIGHT_SHIFT_IS_ARITHMETIC
1.74 +# define RES_GET_INT(res) (((int32_t)((res)<<4L))>>4L)
1.75 +#else
1.76 +# define RES_GET_INT(res) (int32_t)(((res)&0x08000000) ? (res)|0xf0000000 : (res)&0x07ffffff)
1.77 +#endif
1.78 +
1.79 +#define RES_GET_UINT(res) ((res)&0x0fffffff)
1.80 +
1.81 +#define URES_IS_ARRAY(type) ((int32_t)(type)==URES_ARRAY || (int32_t)(type)==URES_ARRAY16)
1.82 +#define URES_IS_TABLE(type) ((int32_t)(type)==URES_TABLE || (int32_t)(type)==URES_TABLE16 || (int32_t)(type)==URES_TABLE32)
1.83 +#define URES_IS_CONTAINER(type) (URES_IS_TABLE(type) || URES_IS_ARRAY(type))
1.84 +
1.85 +#define URES_MAKE_RESOURCE(type, offset) (((Resource)(type)<<28)|(Resource)(offset))
1.86 +#define URES_MAKE_EMPTY_RESOURCE(type) ((Resource)(type)<<28)
1.87 +
1.88 +/* indexes[] value names; indexes are generally 32-bit (Resource) indexes */
1.89 +enum {
1.90 + URES_INDEX_LENGTH, /* [0] contains URES_INDEX_TOP==the length of indexes[];
1.91 + * formatVersion==1: all bits contain the length of indexes[]
1.92 + * but the length is much less than 0xff;
1.93 + * formatVersion>1:
1.94 + * only bits 7..0 contain the length of indexes[],
1.95 + * bits 31..8 are reserved and set to 0 */
1.96 + URES_INDEX_KEYS_TOP, /* [1] contains the top of the key strings, */
1.97 + /* same as the bottom of resources or UTF-16 strings, rounded up */
1.98 + URES_INDEX_RESOURCES_TOP, /* [2] contains the top of all resources */
1.99 + URES_INDEX_BUNDLE_TOP, /* [3] contains the top of the bundle, */
1.100 + /* in case it were ever different from [2] */
1.101 + URES_INDEX_MAX_TABLE_LENGTH,/* [4] max. length of any table */
1.102 + URES_INDEX_ATTRIBUTES, /* [5] attributes bit set, see URES_ATT_* (new in formatVersion 1.2) */
1.103 + URES_INDEX_16BIT_TOP, /* [6] top of the 16-bit units (UTF-16 string v2 UChars, URES_TABLE16, URES_ARRAY16),
1.104 + * rounded up (new in formatVersion 2.0, ICU 4.4) */
1.105 + URES_INDEX_POOL_CHECKSUM, /* [7] checksum of the pool bundle (new in formatVersion 2.0, ICU 4.4) */
1.106 + URES_INDEX_TOP
1.107 +};
1.108 +
1.109 +/*
1.110 + * Nofallback attribute, attribute bit 0 in indexes[URES_INDEX_ATTRIBUTES].
1.111 + * New in formatVersion 1.2 (ICU 3.6).
1.112 + *
1.113 + * If set, then this resource bundle is a standalone bundle.
1.114 + * If not set, then the bundle participates in locale fallback, eventually
1.115 + * all the way to the root bundle.
1.116 + * If indexes[] is missing or too short, then the attribute cannot be determined
1.117 + * reliably. Dependency checking should ignore such bundles, and loading should
1.118 + * use fallbacks.
1.119 + */
1.120 +#define URES_ATT_NO_FALLBACK 1
1.121 +
1.122 +/*
1.123 + * Attributes for bundles that are, or use, a pool bundle.
1.124 + * A pool bundle provides key strings that are shared among several other bundles
1.125 + * to reduce their total size.
1.126 + * New in formatVersion 2 (ICU 4.4).
1.127 + */
1.128 +#define URES_ATT_IS_POOL_BUNDLE 2
1.129 +#define URES_ATT_USES_POOL_BUNDLE 4
1.130 +
1.131 +/*
1.132 + * File format for .res resource bundle files (formatVersion=2, ICU 4.4)
1.133 + *
1.134 + * New in formatVersion 2 compared with 1.3: -------------
1.135 + *
1.136 + * Three new resource types -- String-v2, Table16 and Array16 -- have their
1.137 + * values stored in a new array of 16-bit units between the table key strings
1.138 + * and the start of the other resources.
1.139 + *
1.140 + * genrb eliminates duplicates among Unicode string-v2 values.
1.141 + * Multiple Unicode strings may use the same offset and string data,
1.142 + * or a short string may point to the suffix of a longer string. ("Suffix sharing")
1.143 + * For example, one string "abc" may be reused for another string "bc" by pointing
1.144 + * to the second character. (Short strings-v2 are NUL-terminated
1.145 + * and not preceded by an explicit length value.)
1.146 + *
1.147 + * It is allowed for all resource types to share values.
1.148 + * The swapper code (ures_swap()) has been modified so that it swaps each item
1.149 + * exactly once.
1.150 + *
1.151 + * A resource bundle may use a special pool bundle. Some or all of the table key strings
1.152 + * of the using-bundle are omitted, and the key string offsets for such key strings refer
1.153 + * to offsets in the pool bundle.
1.154 + * The using-bundle's and the pool-bundle's indexes[URES_INDEX_POOL_CHECKSUM] values
1.155 + * must match.
1.156 + * Two bits in indexes[URES_INDEX_ATTRIBUTES] indicate whether a resource bundle
1.157 + * is or uses a pool bundle.
1.158 + *
1.159 + * Table key strings must be compared in ASCII order, even if they are not
1.160 + * stored in ASCII.
1.161 + *
1.162 + * New in formatVersion 1.3 compared with 1.2: -------------
1.163 + *
1.164 + * genrb eliminates duplicates among key strings.
1.165 + * Multiple table items may share one key string, or one item may point
1.166 + * to the suffix of another's key string. ("Suffix sharing")
1.167 + * For example, one key "abc" may be reused for another key "bc" by pointing
1.168 + * to the second character. (Key strings are NUL-terminated.)
1.169 + *
1.170 + * -------------
1.171 + *
1.172 + * An ICU4C resource bundle file (.res) is a binary, memory-mappable file
1.173 + * with nested, hierarchical data structures.
1.174 + * It physically contains the following:
1.175 + *
1.176 + * Resource root; -- 32-bit Resource item, root item for this bundle's tree;
1.177 + * currently, the root item must be a table or table32 resource item
1.178 + * int32_t indexes[indexes[0]]; -- array of indexes for friendly
1.179 + * reading and swapping; see URES_INDEX_* above
1.180 + * new in formatVersion 1.1 (ICU 2.8)
1.181 + * char keys[]; -- characters for key strings
1.182 + * (formatVersion 1.0: up to 65k of characters; 1.1: <2G)
1.183 + * (minus the space for root and indexes[]),
1.184 + * which consist of invariant characters (ASCII/EBCDIC) and are NUL-terminated;
1.185 + * padded to multiple of 4 bytes for 4-alignment of the following data
1.186 + * uint16_t 16BitUnits[]; -- resources that are stored entirely as sequences of 16-bit units
1.187 + * (new in formatVersion 2/ICU 4.4)
1.188 + * data is indexed by the offset values in 16-bit resource types,
1.189 + * with offset 0 pointing to the beginning of this array;
1.190 + * there is a 0 at offset 0, for empty resources;
1.191 + * padded to multiple of 4 bytes for 4-alignment of the following data
1.192 + * data; -- data directly and indirectly indexed by the root item;
1.193 + * the structure is determined by walking the tree
1.194 + *
1.195 + * Each resource bundle item has a 32-bit Resource handle (see typedef above)
1.196 + * which contains the item type number in its upper 4 bits (31..28) and either
1.197 + * an offset or a direct value in its lower 28 bits (27..0).
1.198 + * The order of items is undefined and only determined by walking the tree.
1.199 + * Leaves of the tree may be stored first or last or anywhere in between,
1.200 + * and it is in theory possible to have unreferenced holes in the file.
1.201 + *
1.202 + * 16-bit-unit values:
1.203 + * Starting with formatVersion 2/ICU 4.4, some resources are stored in a special
1.204 + * array of 16-bit units. Each resource value is a sequence of 16-bit units,
1.205 + * with no per-resource padding to a 4-byte boundary.
1.206 + * 16-bit container types (Table16 and Array16) contain Resource16 values
1.207 + * which are offsets to String-v2 resources in the same 16-bit-units array.
1.208 + *
1.209 + * Direct values:
1.210 + * - Empty Unicode strings have an offset value of 0 in the Resource handle itself.
1.211 + * - Starting with formatVersion 2/ICU 4.4, an offset value of 0 for
1.212 + * _any_ resource type indicates an empty value.
1.213 + * - Integer values are 28-bit values stored in the Resource handle itself;
1.214 + * the interpretation of unsigned vs. signed integers is up to the application.
1.215 + *
1.216 + * All other types and values use 28-bit offsets to point to the item's data.
1.217 + * The offset is an index to the first 32-bit word of the value, relative to the
1.218 + * start of the resource data (i.e., the root item handle is at offset 0).
1.219 + * To get byte offsets, the offset is multiplied by 4 (or shifted left by 2 bits).
1.220 + * All resource item values are 4-aligned.
1.221 + *
1.222 + * New in formatVersion 2/ICU 4.4: Some types use offsets into the 16-bit-units array,
1.223 + * indexing 16-bit units in that array.
1.224 + *
1.225 + * The structures (memory layouts) for the values for each item type are listed
1.226 + * in the table below.
1.227 + *
1.228 + * Nested, hierarchical structures: -------------
1.229 + *
1.230 + * Table items contain key-value pairs where the keys are offsets to char * key strings.
1.231 + * The values of these pairs are either Resource handles or
1.232 + * offsets into the 16-bit-units array, depending on the table type.
1.233 + *
1.234 + * Array items are simple vectors of Resource handles,
1.235 + * or of offsets into the 16-bit-units array, depending on the array type.
1.236 + *
1.237 + * Table key string offsets: -------
1.238 + *
1.239 + * Key string offsets are relative to the start of the resource data (of the root handle),
1.240 + * i.e., the first string has an offset of 4+sizeof(indexes).
1.241 + * (After the 4-byte root handle and after the indexes array.)
1.242 + *
1.243 + * If the resource bundle uses a pool bundle, then some key strings are stored
1.244 + * in the pool bundle rather than in the local bundle itself.
1.245 + * - In a Table or Table16, the 16-bit key string offset is local if it is
1.246 + * less than indexes[URES_INDEX_KEYS_TOP]<<2.
1.247 + * Otherwise, subtract indexes[URES_INDEX_KEYS_TOP]<<2 to get the offset into
1.248 + * the pool bundle key strings.
1.249 + * - In a Table32, the 32-bit key string offset is local if it is non-negative.
1.250 + * Otherwise, reset bit 31 to get the pool key string offset.
1.251 + *
1.252 + * Unlike the local offset, the pool key offset is relative to
1.253 + * the start of the key strings, not to the start of the bundle.
1.254 + *
1.255 + * An alias item is special (and new in ICU 2.4): --------------
1.256 + *
1.257 + * Its memory layout is just like for a UnicodeString, but at runtime it resolves to
1.258 + * another resource bundle's item according to the path in the string.
1.259 + * This is used to share items across bundles that are in different lookup/fallback
1.260 + * chains (e.g., large collation data among zh_TW and zh_HK).
1.261 + * This saves space (for large items) and maintenance effort (less duplication of data).
1.262 + *
1.263 + * --------------------------------------------------------------------------
1.264 + *
1.265 + * Resource types:
1.266 + *
1.267 + * Most resources have their values stored at four-byte offsets from the start
1.268 + * of the resource data. These values are at least 4-aligned.
1.269 + * Some resource values are stored directly in the offset field of the Resource itself.
1.270 + * See UResType in unicode/ures.h for enumeration constants for Resource types.
1.271 + *
1.272 + * Some resources have their values stored as sequences of 16-bit units,
1.273 + * at 2-byte offsets from the start of a contiguous 16-bit-unit array between
1.274 + * the table key strings and the other resources. (new in formatVersion 2/ICU 4.4)
1.275 + * At offset 0 of that array is a 16-bit zero value for empty 16-bit resources.
1.276 + * Resource16 values in Table16 and Array16 are 16-bit offsets to String-v2
1.277 + * resources, with the offsets relative to the start of the 16-bit-units array.
1.278 + *
1.279 + * Type Name Memory layout of values
1.280 + * (in parentheses: scalar, non-offset values)
1.281 + *
1.282 + * 0 Unicode String: int32_t length, UChar[length], (UChar)0, (padding)
1.283 + * or (empty string ("") if offset==0)
1.284 + * 1 Binary: int32_t length, uint8_t[length], (padding)
1.285 + * - the start of the bytes is 16-aligned -
1.286 + * 2 Table: uint16_t count, uint16_t keyStringOffsets[count], (uint16_t padding), Resource[count]
1.287 + * 3 Alias: (physically same value layout as string, new in ICU 2.4)
1.288 + * 4 Table32: int32_t count, int32_t keyStringOffsets[count], Resource[count]
1.289 + * (new in formatVersion 1.1/ICU 2.8)
1.290 + * 5 Table16: uint16_t count, uint16_t keyStringOffsets[count], Resource16[count]
1.291 + * (stored in the 16-bit-units array; new in formatVersion 2/ICU 4.4)
1.292 + * 6 Unicode String-v2:UChar[length], (UChar)0; length determined by the first UChar:
1.293 + * - if first is not a trail surrogate, then the length is implicit
1.294 + * and u_strlen() needs to be called
1.295 + * - if first<0xdfef then length=first&0x3ff (and skip first)
1.296 + * - if first<0xdfff then length=((first-0xdfef)<<16) | second UChar
1.297 + * - if first==0xdfff then length=((second UChar)<<16) | third UChar
1.298 + * (stored in the 16-bit-units array; new in formatVersion 2/ICU 4.4)
1.299 + * 7 Integer: (28-bit offset is integer value)
1.300 + * 8 Array: int32_t count, Resource[count]
1.301 + * 9 Array16: uint16_t count, Resource16[count]
1.302 + * (stored in the 16-bit-units array; new in formatVersion 2/ICU 4.4)
1.303 + * 14 Integer Vector: int32_t length, int32_t[length]
1.304 + * 15 Reserved: This value denotes special purpose resources and is for internal use.
1.305 + *
1.306 + * Note that there are 3 types with data vector values:
1.307 + * - Vectors of 8-bit bytes stored as type Binary.
1.308 + * - Vectors of 16-bit words stored as type Unicode String or Unicode String-v2
1.309 + * (no value restrictions, all values 0..ffff allowed!).
1.310 + * - Vectors of 32-bit words stored as type Integer Vector.
1.311 + */
1.312 +
1.313 +/*
1.314 + * Structure for a single, memory-mapped ResourceBundle.
1.315 + */
1.316 +typedef struct {
1.317 + UDataMemory *data;
1.318 + const int32_t *pRoot;
1.319 + const uint16_t *p16BitUnits;
1.320 + const char *poolBundleKeys;
1.321 + Resource rootRes;
1.322 + int32_t localKeyLimit;
1.323 + UBool noFallback; /* see URES_ATT_NO_FALLBACK */
1.324 + UBool isPoolBundle;
1.325 + UBool usesPoolBundle;
1.326 + UBool useNativeStrcmp;
1.327 +} ResourceData;
1.328 +
1.329 +/*
1.330 + * Read a resource bundle from memory.
1.331 + */
1.332 +U_INTERNAL void U_EXPORT2
1.333 +res_read(ResourceData *pResData,
1.334 + const UDataInfo *pInfo, const void *inBytes, int32_t length,
1.335 + UErrorCode *errorCode);
1.336 +
1.337 +/*
1.338 + * Load a resource bundle file.
1.339 + * The ResourceData structure must be allocated externally.
1.340 + */
1.341 +U_CFUNC void
1.342 +res_load(ResourceData *pResData,
1.343 + const char *path, const char *name, UErrorCode *errorCode);
1.344 +
1.345 +/*
1.346 + * Release a resource bundle file.
1.347 + * This does not release the ResourceData structure itself.
1.348 + */
1.349 +U_CFUNC void
1.350 +res_unload(ResourceData *pResData);
1.351 +
1.352 +U_INTERNAL UResType U_EXPORT2
1.353 +res_getPublicType(Resource res);
1.354 +
1.355 +/*
1.356 + * Return a pointer to a zero-terminated, const UChar* string
1.357 + * and set its length in *pLength.
1.358 + * Returns NULL if not found.
1.359 + */
1.360 +U_INTERNAL const UChar * U_EXPORT2
1.361 +res_getString(const ResourceData *pResData, Resource res, int32_t *pLength);
1.362 +
1.363 +U_INTERNAL const UChar * U_EXPORT2
1.364 +res_getAlias(const ResourceData *pResData, Resource res, int32_t *pLength);
1.365 +
1.366 +U_INTERNAL const uint8_t * U_EXPORT2
1.367 +res_getBinary(const ResourceData *pResData, Resource res, int32_t *pLength);
1.368 +
1.369 +U_INTERNAL const int32_t * U_EXPORT2
1.370 +res_getIntVector(const ResourceData *pResData, Resource res, int32_t *pLength);
1.371 +
1.372 +U_INTERNAL Resource U_EXPORT2
1.373 +res_getResource(const ResourceData *pResData, const char *key);
1.374 +
1.375 +U_INTERNAL int32_t U_EXPORT2
1.376 +res_countArrayItems(const ResourceData *pResData, Resource res);
1.377 +
1.378 +U_INTERNAL Resource U_EXPORT2
1.379 +res_getArrayItem(const ResourceData *pResData, Resource array, int32_t indexS);
1.380 +
1.381 +U_INTERNAL Resource U_EXPORT2
1.382 +res_getTableItemByIndex(const ResourceData *pResData, Resource table, int32_t indexS, const char ** key);
1.383 +
1.384 +U_INTERNAL Resource U_EXPORT2
1.385 +res_getTableItemByKey(const ResourceData *pResData, Resource table, int32_t *indexS, const char* * key);
1.386 +
1.387 +/*
1.388 + * Modifies the contents of *path (replacing separators with NULs),
1.389 + * and also moves *path forward while it finds items.
1.390 + */
1.391 +U_CFUNC Resource res_findResource(const ResourceData *pResData, Resource r, char** path, const char** key);
1.392 +
1.393 +/**
1.394 + * Swap an ICU resource bundle. See udataswp.h.
1.395 + * @internal
1.396 + */
1.397 +U_CAPI int32_t U_EXPORT2
1.398 +ures_swap(const UDataSwapper *ds,
1.399 + const void *inData, int32_t length, void *outData,
1.400 + UErrorCode *pErrorCode);
1.401 +
1.402 +#endif
