Home | History | Annotate | Download | only in unicode
      1 /*
      2 ******************************************************************************
      3 *
      4 *   Copyright (C) 1999-2012, 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) @stable ICU 3.4 */
    387     UDATA_FILES_FIRST,
    388     /** An alias for the default access mode. @stable ICU 3.4 */
    389     UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
    390     /** ICU only loads data from packages, not from single files. @stable ICU 3.4 */
    391     UDATA_ONLY_PACKAGES,
    392     /** ICU loads data from packages first, and only from single files
    393         if the data cannot be found in a package. @stable ICU 3.4 */
    394     UDATA_PACKAGES_FIRST,
    395     /** ICU does not access the file system for data loading. @stable ICU 3.4 */
    396     UDATA_NO_FILES,
    397     /** Number of real UDataFileAccess values. @stable ICU 3.4 */
    398     UDATA_FILE_ACCESS_COUNT
    399 } UDataFileAccess;
    400 
    401 /**
    402  * This function may be called to control how ICU loads data. It must be called
    403  * before any ICU data is loaded, including application data loaded with
    404  * ures/ResourceBundle or udata APIs. This function is not multithread safe.
    405  * The results of calling it while other threads are loading data are undefined.
    406  * @param access The type of file access to be used
    407  * @param status Error code.
    408  * @see UDataFileAccess
    409  * @stable ICU 3.4
    410  */
    411 U_STABLE void U_EXPORT2
    412 udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
    413 
    414 U_CDECL_END
    415 
    416 #endif
    417