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
25U_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 */
113typedef 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 */
158typedef 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 */
173typedef UBool U_CALLCONV
174UDataMemoryIsAcceptable(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 */
200U_STABLE UDataMemory * U_EXPORT2
201udata_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 */
252U_STABLE UDataMemory * U_EXPORT2
253udata_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 */
264U_STABLE void U_EXPORT2
265udata_close(UDataMemory *pData);
266
267/**
268 * Get the pointer to the actual data inside the data memory.
269 * The data is read-only.
270 *
271 * ICU data must be at least 8-aligned, and should be 16-aligned.
272 *
273 * @param pData The pointer to data memory object
274 * @stable ICU 2.0
275 */
276U_STABLE const void * U_EXPORT2
277udata_getMemory(UDataMemory *pData);
278
279/**
280 * Get the information from the data memory header.
281 * This allows to get access to the header containing
282 * platform data properties etc. which is not part of
283 * the data itself and can therefore not be accessed
284 * via the pointer that <code>udata_getMemory()</code> returns.
285 *
286 * @param pData pointer to the data memory object
287 * @param pInfo pointer to a UDataInfo object;
288 * its <code>size</code> field must be set correctly,
289 * typically to <code>sizeof(UDataInfo)</code>.
290 *
291 * <code>*pInfo</code> will be filled with the UDataInfo structure
292 * in the data memory object. If this structure is smaller than
293 * <code>pInfo->size</code>, then the <code>size</code> will be
294 * adjusted and only part of the structure will be filled.
295 * @stable ICU 2.0
296 */
297U_STABLE void U_EXPORT2
298udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);
299
300/**
301 * This function bypasses the normal ICU data loading process and
302 * allows you to force ICU's system data to come out of a user-specified
303 * area in memory.
304 *
305 * ICU data must be at least 8-aligned, and should be 16-aligned.
306 * See http://userguide.icu-project.org/icudata
307 *
308 * The format of this data is that of the icu common data file, as is
309 * generated by the pkgdata tool with mode=common or mode=dll.
310 * You can read in a whole common mode file and pass the address to the start of the
311 * data, or (with the appropriate link options) pass in the pointer to
312 * the data that has been loaded from a dll by the operating system,
313 * as shown in this code:
314 *
315 * extern const char U_IMPORT U_ICUDATA_ENTRY_POINT [];
316 * // U_ICUDATA_ENTRY_POINT is same as entry point specified to pkgdata tool
317 * UErrorCode status = U_ZERO_ERROR;
318 *
319 * udata_setCommonData(&U_ICUDATA_ENTRY_POINT, &status);
320 *
321 * It is important that the declaration be as above. The entry point
322 * must not be declared as an extern void*.
323 *
324 * Starting with ICU 4.4, it is possible to set several data packages,
325 * one per call to this function.
326 * udata_open() will look for data in the multiple data packages in the order
327 * in which they were set.
328 * The position of the linked-in or default-name ICU .data package in the
329 * search list depends on when the first data item is loaded that is not contained
330 * in the already explicitly set packages.
331 * If data was loaded implicitly before the first call to this function
332 * (for example, via opening a converter, constructing a UnicodeString
333 * from default-codepage data, using formatting or collation APIs, etc.),
334 * then the default data will be first in the list.
335 *
336 * This function has no effect on application (non ICU) data. See udata_setAppData()
337 * for similar functionality for application data.
338 *
339 * @param data pointer to ICU common data
340 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
341 * @stable ICU 2.0
342 */
343U_STABLE void U_EXPORT2
344udata_setCommonData(const void *data, UErrorCode *err);
345
346
347/**
348 * This function bypasses the normal ICU data loading process for application-specific
349 * data and allows you to force the it to come out of a user-specified
350 * pointer.
351 *
352 * ICU data must be at least 8-aligned, and should be 16-aligned.
353 * See http://userguide.icu-project.org/icudata
354 *
355 * The format of this data is that of the icu common data file, like 'icudt26l.dat'
356 * or the corresponding shared library (DLL) file.
357 * The application must read in or otherwise construct an image of the data and then
358 * pass the address of it to this function.
359 *
360 *
361 * Warning: setAppData will set a U_USING_DEFAULT_WARNING code if
362 * data with the specifed path that has already been opened, or
363 * if setAppData with the same path has already been called.
364 * Any such calls to setAppData will have no effect.
365 *
366 *
367 * @param packageName the package name by which the application will refer
368 * to (open) this data
369 * @param data pointer to the data
370 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
371 * @see udata_setCommonData
372 * @stable ICU 2.0
373 */
374U_STABLE void U_EXPORT2
375udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
376
377/**
378 * Possible settings for udata_setFileAccess()
379 * @see udata_setFileAccess
380 * @stable ICU 3.4
381 */
382typedef enum UDataFileAccess {
383 /** ICU looks for data in single files first, then in packages. (default) @stable ICU 3.4 */
384 UDATA_FILES_FIRST,
385 /** An alias for the default access mode. @stable ICU 3.4 */
386 UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
387 /** ICU only loads data from packages, not from single files. @stable ICU 3.4 */
388 UDATA_ONLY_PACKAGES,
389 /** ICU loads data from packages first, and only from single files
390 if the data cannot be found in a package. @stable ICU 3.4 */
391 UDATA_PACKAGES_FIRST,
392 /** ICU does not access the file system for data loading. @stable ICU 3.4 */
393 UDATA_NO_FILES,
394#ifndef U_HIDE_DEPRECATED_API
395 /**
396 * Number of real UDataFileAccess values.
397 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
398 */
399 UDATA_FILE_ACCESS_COUNT
400#endif // U_HIDE_DEPRECATED_API
401} UDataFileAccess;
402
403/**
404 * This function may be called to control how ICU loads data. It must be called
405 * before any ICU data is loaded, including application data loaded with
406 * ures/ResourceBundle or udata APIs. This function is not multithread safe.
407 * The results of calling it while other threads are loading data are undefined.
408 * @param access The type of file access to be used
409 * @param status Error code.
410 * @see UDataFileAccess
411 * @stable ICU 3.4
412 */
413U_STABLE void U_EXPORT2
414udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
415
416U_CDECL_END
417
418#if U_SHOW_CPLUSPLUS_API
419
420U_NAMESPACE_BEGIN
421
422/**
423 * \class LocalUDataMemoryPointer
424 * "Smart pointer" class, closes a UDataMemory via udata_close().
425 * For most methods see the LocalPointerBase base class.
426 *
427 * @see LocalPointerBase
428 * @see LocalPointer
429 * @stable ICU 4.4
430 */
431U_DEFINE_LOCAL_OPEN_POINTER(LocalUDataMemoryPointer, UDataMemory, udata_close);
432
433U_NAMESPACE_END
434
435#endif // U_SHOW_CPLUSPLUS_API
436
437#endif
438