|
1 /* |
|
2 ****************************************************************************** |
|
3 * |
|
4 * Copyright (C) 1999-2005, International Business Machines |
|
5 * Corporation and others. All Rights Reserved. |
|
6 * |
|
7 ****************************************************************************** |
|
8 * file name: udata.h |
|
9 * encoding: US-ASCII |
|
10 * tab size: 8 (not used) |
|
11 * indentation:4 |
|
12 * |
|
13 * created on: 1999oct25 |
|
14 * created by: Markus W. Scherer |
|
15 */ |
|
16 |
|
17 #ifndef __UDATA_H__ |
|
18 #define __UDATA_H__ |
|
19 |
|
20 #include "unicode/utypes.h" |
|
21 |
|
22 U_CDECL_BEGIN |
|
23 |
|
24 /** |
|
25 * \file |
|
26 * \brief C API: Data loading interface |
|
27 * |
|
28 * <h2>Information about data loading interface</h2> |
|
29 * |
|
30 * This API is used to find and efficiently load data for ICU and applications |
|
31 * using ICU. It provides an abstract interface that specifies a data type and |
|
32 * name to find and load the data. Normally this API is used by other ICU APIs |
|
33 * to load required data out of the ICU data library, but it can be used to |
|
34 * load data out of other places. |
|
35 * |
|
36 * See the User Guide Data Management chapter. |
|
37 */ |
|
38 |
|
39 /** |
|
40 * Character used to separate package names from tree names |
|
41 * @internal ICU 3.0 |
|
42 */ |
|
43 #define U_TREE_SEPARATOR '-' |
|
44 |
|
45 /** |
|
46 * String used to separate package names from tree names |
|
47 * @internal ICU 3.0 |
|
48 */ |
|
49 #define U_TREE_SEPARATOR_STRING "-" |
|
50 |
|
51 /** |
|
52 * Character used to separate parts of entry names |
|
53 * @internal ICU 3.0 |
|
54 */ |
|
55 #define U_TREE_ENTRY_SEP_CHAR '/' |
|
56 |
|
57 /** |
|
58 * String used to separate parts of entry names |
|
59 * @internal ICU 3.0 |
|
60 */ |
|
61 #define U_TREE_ENTRY_SEP_STRING "/" |
|
62 |
|
63 /** |
|
64 * Alias for standard ICU data |
|
65 * @internal ICU 3.0 |
|
66 */ |
|
67 #define U_ICUDATA_ALIAS "ICUDATA" |
|
68 |
|
69 /** |
|
70 * UDataInfo contains the properties about the requested data. |
|
71 * This is meta data. |
|
72 * |
|
73 * <p>This structure may grow in the future, indicated by the |
|
74 * <code>size</code> field.</p> |
|
75 * |
|
76 * <p>The platform data property fields help determine if a data |
|
77 * file can be efficiently used on a given machine. |
|
78 * The particular fields are of importance only if the data |
|
79 * is affected by the properties - if there is integer data |
|
80 * with word sizes > 1 byte, char* text, or UChar* text.</p> |
|
81 * |
|
82 * <p>The implementation for the <code>udata_open[Choice]()</code> |
|
83 * functions may reject data based on the value in <code>isBigEndian</code>. |
|
84 * No other field is used by the <code>udata</code> API implementation.</p> |
|
85 * |
|
86 * <p>The <code>dataFormat</code> may be used to identify |
|
87 * the kind of data, e.g. a converter table.</p> |
|
88 * |
|
89 * <p>The <code>formatVersion</code> field should be used to |
|
90 * make sure that the format can be interpreted. |
|
91 * I may be a good idea to check only for the one or two highest |
|
92 * of the version elements to allow the data memory to |
|
93 * get more or somewhat rearranged contents, for as long |
|
94 * as the using code can still interpret the older contents.</p> |
|
95 * |
|
96 * <p>The <code>dataVersion</code> field is intended to be a |
|
97 * common place to store the source version of the data; |
|
98 * for data from the Unicode character database, this could |
|
99 * reflect the Unicode version.</p> |
|
100 * @stable ICU 2.0 |
|
101 */ |
|
102 typedef struct { |
|
103 /** sizeof(UDataInfo) |
|
104 * @stable ICU 2.0 */ |
|
105 uint16_t size; |
|
106 |
|
107 /** unused, set to 0 |
|
108 * @stable ICU 2.0*/ |
|
109 uint16_t reservedWord; |
|
110 |
|
111 /* platform data properties */ |
|
112 /** 0 for little-endian machine, 1 for big-endian |
|
113 * @stable ICU 2.0 */ |
|
114 uint8_t isBigEndian; |
|
115 |
|
116 /** see U_CHARSET_FAMILY values in utypes.h |
|
117 * @stable ICU 2.0*/ |
|
118 uint8_t charsetFamily; |
|
119 |
|
120 /** sizeof(UChar), one of { 1, 2, 4 } |
|
121 * @stable ICU 2.0*/ |
|
122 uint8_t sizeofUChar; |
|
123 |
|
124 /** unused, set to 0 |
|
125 * @stable ICU 2.0*/ |
|
126 uint8_t reservedByte; |
|
127 |
|
128 /** data format identifier |
|
129 * @stable ICU 2.0*/ |
|
130 uint8_t dataFormat[4]; |
|
131 |
|
132 /** versions: [0] major [1] minor [2] milli [3] micro |
|
133 * @stable ICU 2.0*/ |
|
134 uint8_t formatVersion[4]; |
|
135 |
|
136 /** versions: [0] major [1] minor [2] milli [3] micro |
|
137 * @stable ICU 2.0*/ |
|
138 uint8_t dataVersion[4]; |
|
139 } UDataInfo; |
|
140 |
|
141 /* API for reading data -----------------------------------------------------*/ |
|
142 |
|
143 /** |
|
144 * Forward declaration of the data memory type. |
|
145 * @stable ICU 2.0 |
|
146 */ |
|
147 typedef struct UDataMemory UDataMemory; |
|
148 |
|
149 /** |
|
150 * Callback function for udata_openChoice(). |
|
151 * @param context parameter passed into <code>udata_openChoice()</code>. |
|
152 * @param type The type of the data as passed into <code>udata_openChoice()</code>. |
|
153 * It may be <code>NULL</code>. |
|
154 * @param name The name of the data as passed into <code>udata_openChoice()</code>. |
|
155 * @param pInfo A pointer to the <code>UDataInfo</code> structure |
|
156 * of data that has been loaded and will be returned |
|
157 * by <code>udata_openChoice()</code> if this function |
|
158 * returns <code>TRUE</code>. |
|
159 * @return TRUE if the current data memory is acceptable |
|
160 * @stable ICU 2.0 |
|
161 */ |
|
162 typedef UBool U_CALLCONV |
|
163 UDataMemoryIsAcceptable(void *context, |
|
164 const char *type, const char *name, |
|
165 const UDataInfo *pInfo); |
|
166 |
|
167 |
|
168 /** |
|
169 * Convenience function. |
|
170 * This function works the same as <code>udata_openChoice</code> |
|
171 * except that any data that matches the type and name |
|
172 * is assumed to be acceptable. |
|
173 * @param path Specifies an absolute path and/or a basename for the |
|
174 * finding of the data in the file system. |
|
175 * <code>NULL</code> for ICU data. |
|
176 * @param type A string that specifies the type of data to be loaded. |
|
177 * For example, resource bundles are loaded with type "res", |
|
178 * conversion tables with type "cnv". |
|
179 * This may be <code>NULL</code> or empty. |
|
180 * @param name A string that specifies the name of the data. |
|
181 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>. |
|
182 * @return A pointer (handle) to a data memory object, or <code>NULL</code> |
|
183 * if an error occurs. Call <code>udata_getMemory()</code> |
|
184 * to get a pointer to the actual data. |
|
185 * |
|
186 * @see udata_openChoice |
|
187 * @stable ICU 2.0 |
|
188 */ |
|
189 U_STABLE UDataMemory * U_EXPORT2 |
|
190 udata_open(const char *path, const char *type, const char *name, |
|
191 UErrorCode *pErrorCode); |
|
192 |
|
193 /** |
|
194 * Data loading function. |
|
195 * This function is used to find and load efficiently data for |
|
196 * ICU and applications using ICU. |
|
197 * It provides an abstract interface that allows to specify a data |
|
198 * type and name to find and load the data. |
|
199 * |
|
200 * <p>The implementation depends on platform properties and user preferences |
|
201 * and may involve loading shared libraries (DLLs), mapping |
|
202 * files into memory, or fopen()/fread() files. |
|
203 * It may also involve using static memory or database queries etc. |
|
204 * Several or all data items may be combined into one entity |
|
205 * (DLL, memory-mappable file).</p> |
|
206 * |
|
207 * <p>The data is always preceded by a header that includes |
|
208 * a <code>UDataInfo</code> structure. |
|
209 * The caller's <code>isAcceptable()</code> function is called to make |
|
210 * sure that the data is useful. It may be called several times if it |
|
211 * rejects the data and there is more than one location with data |
|
212 * matching the type and name.</p> |
|
213 * |
|
214 * <p>If <code>path==NULL</code>, then ICU data is loaded. |
|
215 * Otherwise, it is separated into a basename and a basename-less directory string. |
|
216 * The basename is used as the data package name, and the directory is |
|
217 * logically prepended to the ICU data directory string.</p> |
|
218 * |
|
219 * <p>For details about ICU data loading see the User Guide |
|
220 * Data Management chapter. (http://icu.sourceforge.net/userguide/icudata.html)</p> |
|
221 * |
|
222 * @param path Specifies an absolute path and/or a basename for the |
|
223 * finding of the data in the file system. |
|
224 * <code>NULL</code> for ICU data. |
|
225 * @param type A string that specifies the type of data to be loaded. |
|
226 * For example, resource bundles are loaded with type "res", |
|
227 * conversion tables with type "cnv". |
|
228 * This may be <code>NULL</code> or empty. |
|
229 * @param name A string that specifies the name of the data. |
|
230 * @param isAcceptable This function is called to verify that loaded data |
|
231 * is useful for the client code. If it returns FALSE |
|
232 * for all data items, then <code>udata_openChoice()</code> |
|
233 * will return with an error. |
|
234 * @param context Arbitrary parameter to be passed into isAcceptable. |
|
235 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>. |
|
236 * @return A pointer (handle) to a data memory object, or <code>NULL</code> |
|
237 * if an error occurs. Call <code>udata_getMemory()</code> |
|
238 * to get a pointer to the actual data. |
|
239 * @stable ICU 2.0 |
|
240 */ |
|
241 U_STABLE UDataMemory * U_EXPORT2 |
|
242 udata_openChoice(const char *path, const char *type, const char *name, |
|
243 UDataMemoryIsAcceptable *isAcceptable, void *context, |
|
244 UErrorCode *pErrorCode); |
|
245 |
|
246 /** |
|
247 * Close the data memory. |
|
248 * This function must be called to allow the system to |
|
249 * release resources associated with this data memory. |
|
250 * @param pData The pointer to data memory object |
|
251 * @stable ICU 2.0 |
|
252 */ |
|
253 U_STABLE void U_EXPORT2 |
|
254 udata_close(UDataMemory *pData); |
|
255 |
|
256 /** |
|
257 * Get the pointer to the actual data inside the data memory. |
|
258 * The data is read-only. |
|
259 * @param pData The pointer to data memory object |
|
260 * @stable ICU 2.0 |
|
261 */ |
|
262 U_STABLE const void * U_EXPORT2 |
|
263 udata_getMemory(UDataMemory *pData); |
|
264 |
|
265 /** |
|
266 * Get the information from the data memory header. |
|
267 * This allows to get access to the header containing |
|
268 * platform data properties etc. which is not part of |
|
269 * the data itself and can therefore not be accessed |
|
270 * via the pointer that <code>udata_getMemory()</code> returns. |
|
271 * |
|
272 * @param pData pointer to the data memory object |
|
273 * @param pInfo pointer to a UDataInfo object; |
|
274 * its <code>size</code> field must be set correctly, |
|
275 * typically to <code>sizeof(UDataInfo)</code>. |
|
276 * |
|
277 * <code>*pInfo</code> will be filled with the UDataInfo structure |
|
278 * in the data memory object. If this structure is smaller than |
|
279 * <code>pInfo->size</code>, then the <code>size</code> will be |
|
280 * adjusted and only part of the structure will be filled. |
|
281 * @stable ICU 2.0 |
|
282 */ |
|
283 U_STABLE void U_EXPORT2 |
|
284 udata_getInfo(UDataMemory *pData, UDataInfo *pInfo); |
|
285 |
|
286 /** |
|
287 * This function bypasses the normal ICU data loading process and |
|
288 * allows you to force ICU's system data to come out of a user-specified |
|
289 * area in memory. |
|
290 * |
|
291 * The format of this data is that of the icu common data file, as is |
|
292 * generated by the pkgdata tool with mode=common or mode=dll. |
|
293 * You can read in a whole common mode file and pass the address to the start of the |
|
294 * data, or (with the appropriate link options) pass in the pointer to |
|
295 * the data that has been loaded from a dll by the operating system, |
|
296 * as shown in this code: |
|
297 * |
|
298 * extern const char U_IMPORT U_ICUDATA_ENTRY_POINT []; |
|
299 * // U_ICUDATA_ENTRY_POINT is same as entry point specified to pkgdata tool |
|
300 * UErrorCode status = U_ZERO_ERROR; |
|
301 * |
|
302 * udata_setCommonData(&U_ICUDATA_ENTRY_POINT, &status); |
|
303 * |
|
304 * Warning: ICU must NOT have even attempted to access its data yet |
|
305 * when this call is made, or U_USING_DEFAULT_WARNING code will |
|
306 * be returned. Be careful of UnicodeStrings in static initialization which |
|
307 * may attempt to load a converter (use the UNICODE_STRING(x) macro instead). |
|
308 * |
|
309 * Also note that it is important that the declaration be as above. The entry point |
|
310 * must not be declared as an extern void*. |
|
311 * |
|
312 * This function has no effect on application (non ICU) data. See udata_setAppData() |
|
313 * for similar functionality for application data. |
|
314 * |
|
315 * @param data pointer to ICU common data |
|
316 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code> |
|
317 * @stable ICU 2.0 |
|
318 */ |
|
319 |
|
320 U_STABLE void U_EXPORT2 |
|
321 udata_setCommonData(const void *data, UErrorCode *err); |
|
322 |
|
323 |
|
324 /** |
|
325 * This function bypasses the normal ICU data loading process for application-specific |
|
326 * data and allows you to force the it to come out of a user-specified |
|
327 * pointer. |
|
328 * |
|
329 * The format of this data is that of the icu common data file, like 'icudt26l.dat' |
|
330 * or the corresponding shared library (DLL) file. |
|
331 * The application must read in or otherwise construct an image of the data and then |
|
332 * pass the address of it to this function. |
|
333 * |
|
334 * |
|
335 * Warning: setAppData will set a U_USING_DEFAULT_WARNING code if |
|
336 * data with the specifed path that has already been opened, or |
|
337 * if setAppData with the same path has already been called. |
|
338 * Any such calls to setAppData will have no effect. |
|
339 * |
|
340 * |
|
341 * @param packageName the package name by which the application will refer |
|
342 * to (open) this data |
|
343 * @param data pointer to the data |
|
344 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code> |
|
345 * @see udata_setCommonData |
|
346 * @stable ICU 2.0 |
|
347 */ |
|
348 U_STABLE void U_EXPORT2 |
|
349 udata_setAppData(const char *packageName, const void *data, UErrorCode *err); |
|
350 |
|
351 /** |
|
352 * Possible settings for udata_setFileAccess() |
|
353 * @see udata_setFileAccess |
|
354 * @draft ICU 3.4 |
|
355 */ |
|
356 typedef enum UDataFileAccess { |
|
357 /** ICU does not access the file system for data loading. */ |
|
358 UDATA_NO_FILES, |
|
359 /** ICU only loads data from packages, not from single files. */ |
|
360 UDATA_ONLY_PACKAGES, |
|
361 /** ICU loads data from packages first, and only from single files |
|
362 if the data cannot be found in a package. */ |
|
363 UDATA_PACKAGES_FIRST, |
|
364 /** ICU looks for data in single files first, then in packages. (default) */ |
|
365 UDATA_FILES_FIRST, |
|
366 /** An alias for the default access mode. */ |
|
367 UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST, |
|
368 UDATA_FILE_ACCESS_COUNT |
|
369 } UDataFileAccess; |
|
370 |
|
371 /** |
|
372 * This function may be called to control how ICU loads data. It must be called |
|
373 * before any ICU data is loaded, including application data loaded with ures/ResourceBundle or |
|
374 * udata APIs. It should be called before u_init. This function is not multithread safe. |
|
375 * The results of calling it while other threads are loading data are undefined. |
|
376 * @param access The type of file access to be used |
|
377 * @param status Error code. |
|
378 * @see UDataFileAccess |
|
379 * @draft ICU 3.4 |
|
380 */ |
|
381 U_DRAFT void U_EXPORT2 |
|
382 udata_setFileAccess(UDataFileAccess access, UErrorCode *status); |
|
383 |
|
384 U_CDECL_END |
|
385 |
|
386 #endif |