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