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