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