|
1 /* |
|
2 ****************************************************************************** |
|
3 * * |
|
4 * Copyright (C) 1999-2003, International Business Machines * |
|
5 * Corporation and others. All Rights Reserved. * |
|
6 * * |
|
7 ****************************************************************************** |
|
8 * file name: uresdata.h |
|
9 * encoding: US-ASCII |
|
10 * tab size: 8 (not used) |
|
11 * indentation:4 |
|
12 * |
|
13 * created on: 1999dec08 |
|
14 * created by: Markus W. Scherer |
|
15 * 06/24/02 weiv Added support for resource sharing |
|
16 */ |
|
17 |
|
18 #ifndef __RESDATA_H__ |
|
19 #define __RESDATA_H__ |
|
20 |
|
21 #include "unicode/utypes.h" |
|
22 #include "unicode/udata.h" |
|
23 #include "udataswp.h" |
|
24 |
|
25 /* |
|
26 * A Resource is a 32-bit value that has 2 bit fields: |
|
27 * 31..28 4-bit type, see enum below |
|
28 * 27..0 28-bit four-byte-offset or value according to the type |
|
29 */ |
|
30 typedef uint32_t Resource; |
|
31 |
|
32 #define RES_BOGUS 0xffffffff |
|
33 |
|
34 #define RES_GET_TYPE(res) ((res)>>28UL) |
|
35 #define RES_GET_OFFSET(res) ((res)&0x0fffffff) |
|
36 #define RES_GET_POINTER(pRoot, res) ((pRoot)+RES_GET_OFFSET(res)) |
|
37 |
|
38 /* get signed and unsigned integer values directly from the Resource handle */ |
|
39 #define RES_GET_INT(res) (((int32_t)((res)<<4L))>>4L) |
|
40 #define RES_GET_UINT(res) ((res)&0x0fffffff) |
|
41 |
|
42 /* indexes[] value names; indexes are generally 32-bit (Resource) indexes */ |
|
43 enum { |
|
44 URES_INDEX_LENGTH, /* [0] contains URES_INDEX_TOP==the length of indexes[] */ |
|
45 URES_INDEX_STRINGS_TOP, /* [1] contains the top of the strings, */ |
|
46 /* same as the bottom of resources, rounded up */ |
|
47 URES_INDEX_RESOURCES_TOP, /* [2] contains the top of all resources */ |
|
48 URES_INDEX_BUNDLE_TOP, /* [3] contains the top of the bundle, */ |
|
49 /* in case it were ever different from [2] */ |
|
50 URES_INDEX_MAX_TABLE_LENGTH,/* [4] max. length of any table */ |
|
51 URES_INDEX_TOP |
|
52 }; |
|
53 |
|
54 /* number of bytes at the beginning of the bundle before the strings start */ |
|
55 enum { |
|
56 URES_STRINGS_BOTTOM=(1+URES_INDEX_TOP)*4 |
|
57 }; |
|
58 |
|
59 /* |
|
60 * File format for .res resource bundle files (formatVersion=1.1) |
|
61 * |
|
62 * An ICU4C resource bundle file (.res) is a binary, memory-mappable file |
|
63 * with nested, hierarchical data structures. |
|
64 * It physically contains the following: |
|
65 * |
|
66 * Resource root; -- 32-bit Resource item, root item for this bundle's tree; |
|
67 * currently, the root item must be a table or table32 resource item |
|
68 * int32_t indexes[indexes[0]]; -- array of indexes for friendly |
|
69 * reading and swapping; see URES_INDEX_* above |
|
70 * new in formatVersion 1.1 |
|
71 * char keys[]; -- characters for key strings |
|
72 * (formatVersion 1.0: up to 65k of characters; 1.1: <2G) |
|
73 * (minus the space for root and indexes[]), |
|
74 * which consist of invariant characters (ASCII/EBCDIC) and are NUL-terminated; |
|
75 * padded to multiple of 4 bytes for 4-alignment of the following data |
|
76 * data; -- data directly and indirectly indexed by the root item; |
|
77 * the structure is determined by walking the tree |
|
78 * |
|
79 * Each resource bundle item has a 32-bit Resource handle (see typedef above) |
|
80 * which contains the item type number in its upper 4 bits (31..28) and either |
|
81 * an offset or a direct value in its lower 28 bits (27..0). |
|
82 * The order of items is undefined and only determined by walking the tree. |
|
83 * Leaves of the tree may be stored first or last or anywhere in between, |
|
84 * and it is in theory possible to have unreferenced holes in the file. |
|
85 * |
|
86 * Direct values: |
|
87 * - Empty Unicode strings have an offset value of 0 in the Resource handle itself. |
|
88 * - Integer values are 28-bit values stored in the Resource handle itself; |
|
89 * the interpretation of unsigned vs. signed integers is up to the application. |
|
90 * |
|
91 * All other types and values use 28-bit offsets to point to the item's data. |
|
92 * The offset is an index to the first 32-bit word of the value, relative to the |
|
93 * start of the resource data (i.e., the root item handle is at offset 0). |
|
94 * To get byte offsets, the offset is multiplied by 4 (or shifted left by 2 bits). |
|
95 * All resource item values are 4-aligned. |
|
96 * |
|
97 * The structures (memory layouts) for the values for each item type are listed |
|
98 * in the table above. |
|
99 * |
|
100 * Nested, hierarchical structures: ------------- |
|
101 * |
|
102 * Table items contain key-value pairs where the keys are 16-bit offsets to char * key strings. |
|
103 * Key string offsets are also relative to the start of the resource data (of the root handle), |
|
104 * i.e., the first string has an offset of 4 (after the 4-byte root handle). |
|
105 * |
|
106 * The values of these pairs are Resource handles. |
|
107 * |
|
108 * Array items are simple vectors of Resource handles. |
|
109 * |
|
110 * An alias item is special (and new in ICU 2.4): -------------- |
|
111 * |
|
112 * Its memory layout is just like for a UnicodeString, but at runtime it resolves to |
|
113 * another resource bundle's item according to the path in the string. |
|
114 * This is used to share items across bundles that are in different lookup/fallback |
|
115 * chains (e.g., large collation data among zh_TW and zh_HK). |
|
116 * This saves space (for large items) and maintenance effort (less duplication of data). |
|
117 * |
|
118 * -------------------------------------------------------------------------- |
|
119 * |
|
120 * Resource types: |
|
121 * |
|
122 * Most resources have their values stored at four-byte offsets from the start |
|
123 * of the resource data. These values are at least 4-aligned. |
|
124 * Some resource values are stored directly in the offset field of the Resource itself. |
|
125 * See UResType in unicode/ures.h for enumeration constants for Resource types. |
|
126 * |
|
127 * Type Name Memory layout of values |
|
128 * (in parentheses: scalar, non-offset values) |
|
129 * |
|
130 * 0 Unicode String: int32_t length, UChar[length], (UChar)0, (padding) |
|
131 * or (empty string ("") if offset==0) |
|
132 * 1 Binary: int32_t length, uint8_t[length], (padding) |
|
133 * - this value should be 32-aligned - |
|
134 * 2 Table: uint16_t count, uint16_t keyStringOffsets[count], (uint16_t padding), Resource[count] |
|
135 * 3 Alias: (physically same value layout as string, new in ICU 2.4) |
|
136 * 4 Table32: int32_t count, int32_t keyStringOffsets[count], Resource[count] |
|
137 * (new in formatVersion 1.1/ICU 2.8) |
|
138 * |
|
139 * 7 Integer: (28-bit offset is integer value) |
|
140 * 8 Array: int32_t count, Resource[count] |
|
141 * |
|
142 * 14 Integer Vector: int32_t length, int32_t[length] |
|
143 * 15 Reserved: This value denotes special purpose resources and is for internal use. |
|
144 * |
|
145 * Note that there are 3 types with data vector values: |
|
146 * - Vectors of 8-bit bytes stored as type Binary. |
|
147 * - Vectors of 16-bit words stored as type Unicode String |
|
148 * (no value restrictions, all values 0..ffff allowed!). |
|
149 * - Vectors of 32-bit words stored as type Integer Vector. |
|
150 */ |
|
151 |
|
152 /* |
|
153 * Structure for a single, memory-mapped ResourceBundle. |
|
154 */ |
|
155 typedef struct { |
|
156 UDataMemory *data; |
|
157 Resource *pRoot; |
|
158 Resource rootRes; |
|
159 } ResourceData; |
|
160 |
|
161 /* |
|
162 * Load a resource bundle file. |
|
163 * The ResourceData structure must be allocated externally. |
|
164 */ |
|
165 U_CFUNC UBool |
|
166 res_load(ResourceData *pResData, |
|
167 const char *path, const char *name, UErrorCode *errorCode); |
|
168 |
|
169 /* |
|
170 * Release a resource bundle file. |
|
171 * This does not release the ResourceData structure itself. |
|
172 */ |
|
173 U_CFUNC void |
|
174 res_unload(ResourceData *pResData); |
|
175 |
|
176 /* |
|
177 * Return a pointer to a zero-terminated, const UChar* string |
|
178 * and set its length in *pLength. |
|
179 * Returns NULL if not found. |
|
180 */ |
|
181 U_CFUNC const UChar * |
|
182 res_getString(const ResourceData *pResData, const Resource res, int32_t *pLength); |
|
183 |
|
184 U_CFUNC const UChar * |
|
185 res_getAlias(const ResourceData *pResData, const Resource res, int32_t *pLength); |
|
186 |
|
187 U_CFUNC const uint8_t * |
|
188 res_getBinary(const ResourceData *pResData, const Resource res, int32_t *pLength); |
|
189 |
|
190 U_CFUNC const int32_t * |
|
191 res_getIntVector(const ResourceData *pResData, const Resource res, int32_t *pLength); |
|
192 |
|
193 U_CFUNC Resource |
|
194 res_getResource(const ResourceData *pResData, const char *key); |
|
195 |
|
196 U_CFUNC int32_t |
|
197 res_countArrayItems(const ResourceData *pResData, const Resource res); |
|
198 |
|
199 U_CFUNC Resource res_getArrayItem(const ResourceData *pResData, Resource array, const int32_t indexS); |
|
200 U_CFUNC Resource res_getTableItemByIndex(const ResourceData *pResData, Resource table, int32_t indexS, const char ** key); |
|
201 U_CFUNC Resource res_getTableItemByKey(const ResourceData *pResData, Resource table, int32_t *indexS, const char* * key); |
|
202 |
|
203 /* |
|
204 * Modifies the contents of *path (replacing separators with NULs), |
|
205 * and also moves *path forward while it finds items. |
|
206 */ |
|
207 U_CFUNC Resource res_findResource(const ResourceData *pResData, Resource r, char** path, const char** key); |
|
208 |
|
209 /** |
|
210 * Swap an ICU resource bundle. See udataswp.h. |
|
211 * @internal |
|
212 */ |
|
213 U_CAPI int32_t U_EXPORT2 |
|
214 ures_swap(const UDataSwapper *ds, |
|
215 const void *inData, int32_t length, void *outData, |
|
216 UErrorCode *pErrorCode); |
|
217 |
|
218 #endif |