1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/fontservices/textshaperplugin/IcuSource/common/unicode/udata.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,386 @@
1.4 +/*
1.5 +******************************************************************************
1.6 +*
1.7 +* Copyright (C) 1999-2005, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +******************************************************************************
1.11 +* file name: udata.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 1999oct25
1.17 +* created by: Markus W. Scherer
1.18 +*/
1.19 +
1.20 +#ifndef __UDATA_H__
1.21 +#define __UDATA_H__
1.22 +
1.23 +#include "unicode/utypes.h"
1.24 +
1.25 +U_CDECL_BEGIN
1.26 +
1.27 +/**
1.28 + * \file
1.29 + * \brief C API: Data loading interface
1.30 + *
1.31 + * <h2>Information about data loading interface</h2>
1.32 + *
1.33 + * This API is used to find and efficiently load data for ICU and applications
1.34 + * using ICU. It provides an abstract interface that specifies a data type and
1.35 + * name to find and load the data. Normally this API is used by other ICU APIs
1.36 + * to load required data out of the ICU data library, but it can be used to
1.37 + * load data out of other places.
1.38 + *
1.39 + * See the User Guide Data Management chapter.
1.40 + */
1.41 +
1.42 +/**
1.43 + * Character used to separate package names from tree names
1.44 + * @internal ICU 3.0
1.45 + */
1.46 +#define U_TREE_SEPARATOR '-'
1.47 +
1.48 +/**
1.49 + * String used to separate package names from tree names
1.50 + * @internal ICU 3.0
1.51 + */
1.52 +#define U_TREE_SEPARATOR_STRING "-"
1.53 +
1.54 +/**
1.55 + * Character used to separate parts of entry names
1.56 + * @internal ICU 3.0
1.57 + */
1.58 +#define U_TREE_ENTRY_SEP_CHAR '/'
1.59 +
1.60 +/**
1.61 + * String used to separate parts of entry names
1.62 + * @internal ICU 3.0
1.63 + */
1.64 +#define U_TREE_ENTRY_SEP_STRING "/"
1.65 +
1.66 +/**
1.67 + * Alias for standard ICU data
1.68 + * @internal ICU 3.0
1.69 + */
1.70 +#define U_ICUDATA_ALIAS "ICUDATA"
1.71 +
1.72 +/**
1.73 + * UDataInfo contains the properties about the requested data.
1.74 + * This is meta data.
1.75 + *
1.76 + * <p>This structure may grow in the future, indicated by the
1.77 + * <code>size</code> field.</p>
1.78 + *
1.79 + * <p>The platform data property fields help determine if a data
1.80 + * file can be efficiently used on a given machine.
1.81 + * The particular fields are of importance only if the data
1.82 + * is affected by the properties - if there is integer data
1.83 + * with word sizes > 1 byte, char* text, or UChar* text.</p>
1.84 + *
1.85 + * <p>The implementation for the <code>udata_open[Choice]()</code>
1.86 + * functions may reject data based on the value in <code>isBigEndian</code>.
1.87 + * No other field is used by the <code>udata</code> API implementation.</p>
1.88 + *
1.89 + * <p>The <code>dataFormat</code> may be used to identify
1.90 + * the kind of data, e.g. a converter table.</p>
1.91 + *
1.92 + * <p>The <code>formatVersion</code> field should be used to
1.93 + * make sure that the format can be interpreted.
1.94 + * I may be a good idea to check only for the one or two highest
1.95 + * of the version elements to allow the data memory to
1.96 + * get more or somewhat rearranged contents, for as long
1.97 + * as the using code can still interpret the older contents.</p>
1.98 + *
1.99 + * <p>The <code>dataVersion</code> field is intended to be a
1.100 + * common place to store the source version of the data;
1.101 + * for data from the Unicode character database, this could
1.102 + * reflect the Unicode version.</p>
1.103 + * @stable ICU 2.0
1.104 + */
1.105 +typedef struct {
1.106 + /** sizeof(UDataInfo)
1.107 + * @stable ICU 2.0 */
1.108 + uint16_t size;
1.109 +
1.110 + /** unused, set to 0
1.111 + * @stable ICU 2.0*/
1.112 + uint16_t reservedWord;
1.113 +
1.114 + /* platform data properties */
1.115 + /** 0 for little-endian machine, 1 for big-endian
1.116 + * @stable ICU 2.0 */
1.117 + uint8_t isBigEndian;
1.118 +
1.119 + /** see U_CHARSET_FAMILY values in utypes.h
1.120 + * @stable ICU 2.0*/
1.121 + uint8_t charsetFamily;
1.122 +
1.123 + /** sizeof(UChar), one of { 1, 2, 4 }
1.124 + * @stable ICU 2.0*/
1.125 + uint8_t sizeofUChar;
1.126 +
1.127 + /** unused, set to 0
1.128 + * @stable ICU 2.0*/
1.129 + uint8_t reservedByte;
1.130 +
1.131 + /** data format identifier
1.132 + * @stable ICU 2.0*/
1.133 + uint8_t dataFormat[4];
1.134 +
1.135 + /** versions: [0] major [1] minor [2] milli [3] micro
1.136 + * @stable ICU 2.0*/
1.137 + uint8_t formatVersion[4];
1.138 +
1.139 + /** versions: [0] major [1] minor [2] milli [3] micro
1.140 + * @stable ICU 2.0*/
1.141 + uint8_t dataVersion[4];
1.142 +} UDataInfo;
1.143 +
1.144 +/* API for reading data -----------------------------------------------------*/
1.145 +
1.146 +/**
1.147 + * Forward declaration of the data memory type.
1.148 + * @stable ICU 2.0
1.149 + */
1.150 +typedef struct UDataMemory UDataMemory;
1.151 +
1.152 +/**
1.153 + * Callback function for udata_openChoice().
1.154 + * @param context parameter passed into <code>udata_openChoice()</code>.
1.155 + * @param type The type of the data as passed into <code>udata_openChoice()</code>.
1.156 + * It may be <code>NULL</code>.
1.157 + * @param name The name of the data as passed into <code>udata_openChoice()</code>.
1.158 + * @param pInfo A pointer to the <code>UDataInfo</code> structure
1.159 + * of data that has been loaded and will be returned
1.160 + * by <code>udata_openChoice()</code> if this function
1.161 + * returns <code>TRUE</code>.
1.162 + * @return TRUE if the current data memory is acceptable
1.163 + * @stable ICU 2.0
1.164 + */
1.165 +typedef UBool U_CALLCONV
1.166 +UDataMemoryIsAcceptable(void *context,
1.167 + const char *type, const char *name,
1.168 + const UDataInfo *pInfo);
1.169 +
1.170 +
1.171 +/**
1.172 + * Convenience function.
1.173 + * This function works the same as <code>udata_openChoice</code>
1.174 + * except that any data that matches the type and name
1.175 + * is assumed to be acceptable.
1.176 + * @param path Specifies an absolute path and/or a basename for the
1.177 + * finding of the data in the file system.
1.178 + * <code>NULL</code> for ICU data.
1.179 + * @param type A string that specifies the type of data to be loaded.
1.180 + * For example, resource bundles are loaded with type "res",
1.181 + * conversion tables with type "cnv".
1.182 + * This may be <code>NULL</code> or empty.
1.183 + * @param name A string that specifies the name of the data.
1.184 + * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.
1.185 + * @return A pointer (handle) to a data memory object, or <code>NULL</code>
1.186 + * if an error occurs. Call <code>udata_getMemory()</code>
1.187 + * to get a pointer to the actual data.
1.188 + *
1.189 + * @see udata_openChoice
1.190 + * @stable ICU 2.0
1.191 + */
1.192 +U_STABLE UDataMemory * U_EXPORT2
1.193 +udata_open(const char *path, const char *type, const char *name,
1.194 + UErrorCode *pErrorCode);
1.195 +
1.196 +/**
1.197 + * Data loading function.
1.198 + * This function is used to find and load efficiently data for
1.199 + * ICU and applications using ICU.
1.200 + * It provides an abstract interface that allows to specify a data
1.201 + * type and name to find and load the data.
1.202 + *
1.203 + * <p>The implementation depends on platform properties and user preferences
1.204 + * and may involve loading shared libraries (DLLs), mapping
1.205 + * files into memory, or fopen()/fread() files.
1.206 + * It may also involve using static memory or database queries etc.
1.207 + * Several or all data items may be combined into one entity
1.208 + * (DLL, memory-mappable file).</p>
1.209 + *
1.210 + * <p>The data is always preceded by a header that includes
1.211 + * a <code>UDataInfo</code> structure.
1.212 + * The caller's <code>isAcceptable()</code> function is called to make
1.213 + * sure that the data is useful. It may be called several times if it
1.214 + * rejects the data and there is more than one location with data
1.215 + * matching the type and name.</p>
1.216 + *
1.217 + * <p>If <code>path==NULL</code>, then ICU data is loaded.
1.218 + * Otherwise, it is separated into a basename and a basename-less directory string.
1.219 + * The basename is used as the data package name, and the directory is
1.220 + * logically prepended to the ICU data directory string.</p>
1.221 + *
1.222 + * <p>For details about ICU data loading see the User Guide
1.223 + * Data Management chapter. (http://icu.sourceforge.net/userguide/icudata.html)</p>
1.224 + *
1.225 + * @param path Specifies an absolute path and/or a basename for the
1.226 + * finding of the data in the file system.
1.227 + * <code>NULL</code> for ICU data.
1.228 + * @param type A string that specifies the type of data to be loaded.
1.229 + * For example, resource bundles are loaded with type "res",
1.230 + * conversion tables with type "cnv".
1.231 + * This may be <code>NULL</code> or empty.
1.232 + * @param name A string that specifies the name of the data.
1.233 + * @param isAcceptable This function is called to verify that loaded data
1.234 + * is useful for the client code. If it returns FALSE
1.235 + * for all data items, then <code>udata_openChoice()</code>
1.236 + * will return with an error.
1.237 + * @param context Arbitrary parameter to be passed into isAcceptable.
1.238 + * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.
1.239 + * @return A pointer (handle) to a data memory object, or <code>NULL</code>
1.240 + * if an error occurs. Call <code>udata_getMemory()</code>
1.241 + * to get a pointer to the actual data.
1.242 + * @stable ICU 2.0
1.243 + */
1.244 +U_STABLE UDataMemory * U_EXPORT2
1.245 +udata_openChoice(const char *path, const char *type, const char *name,
1.246 + UDataMemoryIsAcceptable *isAcceptable, void *context,
1.247 + UErrorCode *pErrorCode);
1.248 +
1.249 +/**
1.250 + * Close the data memory.
1.251 + * This function must be called to allow the system to
1.252 + * release resources associated with this data memory.
1.253 + * @param pData The pointer to data memory object
1.254 + * @stable ICU 2.0
1.255 + */
1.256 +U_STABLE void U_EXPORT2
1.257 +udata_close(UDataMemory *pData);
1.258 +
1.259 +/**
1.260 + * Get the pointer to the actual data inside the data memory.
1.261 + * The data is read-only.
1.262 + * @param pData The pointer to data memory object
1.263 + * @stable ICU 2.0
1.264 + */
1.265 +U_STABLE const void * U_EXPORT2
1.266 +udata_getMemory(UDataMemory *pData);
1.267 +
1.268 +/**
1.269 + * Get the information from the data memory header.
1.270 + * This allows to get access to the header containing
1.271 + * platform data properties etc. which is not part of
1.272 + * the data itself and can therefore not be accessed
1.273 + * via the pointer that <code>udata_getMemory()</code> returns.
1.274 + *
1.275 + * @param pData pointer to the data memory object
1.276 + * @param pInfo pointer to a UDataInfo object;
1.277 + * its <code>size</code> field must be set correctly,
1.278 + * typically to <code>sizeof(UDataInfo)</code>.
1.279 + *
1.280 + * <code>*pInfo</code> will be filled with the UDataInfo structure
1.281 + * in the data memory object. If this structure is smaller than
1.282 + * <code>pInfo->size</code>, then the <code>size</code> will be
1.283 + * adjusted and only part of the structure will be filled.
1.284 + * @stable ICU 2.0
1.285 + */
1.286 +U_STABLE void U_EXPORT2
1.287 +udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);
1.288 +
1.289 +/**
1.290 + * This function bypasses the normal ICU data loading process and
1.291 + * allows you to force ICU's system data to come out of a user-specified
1.292 + * area in memory.
1.293 + *
1.294 + * The format of this data is that of the icu common data file, as is
1.295 + * generated by the pkgdata tool with mode=common or mode=dll.
1.296 + * You can read in a whole common mode file and pass the address to the start of the
1.297 + * data, or (with the appropriate link options) pass in the pointer to
1.298 + * the data that has been loaded from a dll by the operating system,
1.299 + * as shown in this code:
1.300 + *
1.301 + * extern const char U_IMPORT U_ICUDATA_ENTRY_POINT [];
1.302 + * // U_ICUDATA_ENTRY_POINT is same as entry point specified to pkgdata tool
1.303 + * UErrorCode status = U_ZERO_ERROR;
1.304 + *
1.305 + * udata_setCommonData(&U_ICUDATA_ENTRY_POINT, &status);
1.306 + *
1.307 + * Warning: ICU must NOT have even attempted to access its data yet
1.308 + * when this call is made, or U_USING_DEFAULT_WARNING code will
1.309 + * be returned. Be careful of UnicodeStrings in static initialization which
1.310 + * may attempt to load a converter (use the UNICODE_STRING(x) macro instead).
1.311 + *
1.312 + * Also note that it is important that the declaration be as above. The entry point
1.313 + * must not be declared as an extern void*.
1.314 + *
1.315 + * This function has no effect on application (non ICU) data. See udata_setAppData()
1.316 + * for similar functionality for application data.
1.317 + *
1.318 + * @param data pointer to ICU common data
1.319 + * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
1.320 + * @stable ICU 2.0
1.321 + */
1.322 +
1.323 +U_STABLE void U_EXPORT2
1.324 +udata_setCommonData(const void *data, UErrorCode *err);
1.325 +
1.326 +
1.327 +/**
1.328 + * This function bypasses the normal ICU data loading process for application-specific
1.329 + * data and allows you to force the it to come out of a user-specified
1.330 + * pointer.
1.331 + *
1.332 + * The format of this data is that of the icu common data file, like 'icudt26l.dat'
1.333 + * or the corresponding shared library (DLL) file.
1.334 + * The application must read in or otherwise construct an image of the data and then
1.335 + * pass the address of it to this function.
1.336 + *
1.337 + *
1.338 + * Warning: setAppData will set a U_USING_DEFAULT_WARNING code if
1.339 + * data with the specifed path that has already been opened, or
1.340 + * if setAppData with the same path has already been called.
1.341 + * Any such calls to setAppData will have no effect.
1.342 + *
1.343 + *
1.344 + * @param packageName the package name by which the application will refer
1.345 + * to (open) this data
1.346 + * @param data pointer to the data
1.347 + * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
1.348 + * @see udata_setCommonData
1.349 + * @stable ICU 2.0
1.350 + */
1.351 +U_STABLE void U_EXPORT2
1.352 +udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
1.353 +
1.354 +/**
1.355 + * Possible settings for udata_setFileAccess()
1.356 + * @see udata_setFileAccess
1.357 + * @draft ICU 3.4
1.358 + */
1.359 +typedef enum UDataFileAccess {
1.360 + /** ICU does not access the file system for data loading. */
1.361 + UDATA_NO_FILES,
1.362 + /** ICU only loads data from packages, not from single files. */
1.363 + UDATA_ONLY_PACKAGES,
1.364 + /** ICU loads data from packages first, and only from single files
1.365 + if the data cannot be found in a package. */
1.366 + UDATA_PACKAGES_FIRST,
1.367 + /** ICU looks for data in single files first, then in packages. (default) */
1.368 + UDATA_FILES_FIRST,
1.369 + /** An alias for the default access mode. */
1.370 + UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
1.371 + UDATA_FILE_ACCESS_COUNT
1.372 +} UDataFileAccess;
1.373 +
1.374 +/**
1.375 + * This function may be called to control how ICU loads data. It must be called
1.376 + * before any ICU data is loaded, including application data loaded with ures/ResourceBundle or
1.377 + * udata APIs. It should be called before u_init. This function is not multithread safe.
1.378 + * The results of calling it while other threads are loading data are undefined.
1.379 + * @param access The type of file access to be used
1.380 + * @param status Error code.
1.381 + * @see UDataFileAccess
1.382 + * @draft ICU 3.4
1.383 + */
1.384 +U_DRAFT void U_EXPORT2
1.385 +udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
1.386 +
1.387 +U_CDECL_END
1.388 +
1.389 +#endif