icuSources/common/unicode/udata.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 1999-2006, 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.sourceforge.net/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  * @draft 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  * @draft ICU 3.4
 383  */
 384 U_DRAFT void U_EXPORT2
 385 udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
 386
 387 U_CDECL_END
 388
 389 #endif