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