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