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 28 U_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 */ 116 typedef 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 */ 161 typedef 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 */ 176 typedef UBool U_CALLCONV 177 UDataMemoryIsAcceptable(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 */ 203 U_CAPI UDataMemory * U_EXPORT2 204 udata_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. (http://icu-project.org/userguide/icudata.html)</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 */ 255 U_CAPI UDataMemory * U_EXPORT2 256 udata_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 */ 267 U_CAPI void U_EXPORT2 268 udata_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 */ 279 U_CAPI const void * U_EXPORT2 280 udata_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 */ 300 U_CAPI void U_EXPORT2 301 udata_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/icudata 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 */ 346 U_CAPI void U_EXPORT2 347 udata_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/icudata 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 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_CAPI 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) @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 */ 416 U_CAPI void U_EXPORT2 417 udata_setFileAccess(UDataFileAccess access, UErrorCode *status); 418 419 U_CDECL_END 420 421 #if U_SHOW_CPLUSPLUS_API 422 423 U_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 */ 434 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDataMemoryPointer, UDataMemory, udata_close); 435 436 U_NAMESPACE_END 437 438 #endif // U_SHOW_CPLUSPLUS_API 439 440 #endif 441