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