icuSources/common/unicode/udata.h

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