icuSources/common/unicode/udata.h

   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