1 // Copyright (C) 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: US-ASCII 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