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