Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/udata.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 ******************************************************************************
jpayne@69 5 *
jpayne@69 6 * Copyright (C) 1999-2014, International Business Machines
jpayne@69 7 * Corporation and others. All Rights Reserved.
jpayne@69 8 *
jpayne@69 9 ******************************************************************************
jpayne@69 10 * file name: udata.h
jpayne@69 11 * encoding: UTF-8
jpayne@69 12 * tab size: 8 (not used)
jpayne@69 13 * indentation:4
jpayne@69 14 *
jpayne@69 15 * created on: 1999oct25
jpayne@69 16 * created by: Markus W. Scherer
jpayne@69 17 */
jpayne@69 18
jpayne@69 19 #ifndef __UDATA_H__
jpayne@69 20 #define __UDATA_H__
jpayne@69 21
jpayne@69 22 #include "unicode/utypes.h"
jpayne@69 23 #include "unicode/localpointer.h"
jpayne@69 24
jpayne@69 25 U_CDECL_BEGIN
jpayne@69 26
jpayne@69 27 /**
jpayne@69 28 * \file
jpayne@69 29 * \brief C API: Data loading interface
jpayne@69 30 *
jpayne@69 31 * <h2>Information about data loading interface</h2>
jpayne@69 32 *
jpayne@69 33 * This API is used to find and efficiently load data for ICU and applications
jpayne@69 34 * using ICU. It provides an abstract interface that specifies a data type and
jpayne@69 35 * name to find and load the data. Normally this API is used by other ICU APIs
jpayne@69 36 * to load required data out of the ICU data library, but it can be used to
jpayne@69 37 * load data out of other places.
jpayne@69 38 *
jpayne@69 39 * See the User Guide Data Management chapter.
jpayne@69 40 */
jpayne@69 41
jpayne@69 42 #ifndef U_HIDE_INTERNAL_API
jpayne@69 43 /**
jpayne@69 44 * Character used to separate package names from tree names
jpayne@69 45 * @internal ICU 3.0
jpayne@69 46 */
jpayne@69 47 #define U_TREE_SEPARATOR '-'
jpayne@69 48
jpayne@69 49 /**
jpayne@69 50 * String used to separate package names from tree names
jpayne@69 51 * @internal ICU 3.0
jpayne@69 52 */
jpayne@69 53 #define U_TREE_SEPARATOR_STRING "-"
jpayne@69 54
jpayne@69 55 /**
jpayne@69 56 * Character used to separate parts of entry names
jpayne@69 57 * @internal ICU 3.0
jpayne@69 58 */
jpayne@69 59 #define U_TREE_ENTRY_SEP_CHAR '/'
jpayne@69 60
jpayne@69 61 /**
jpayne@69 62 * String used to separate parts of entry names
jpayne@69 63 * @internal ICU 3.0
jpayne@69 64 */
jpayne@69 65 #define U_TREE_ENTRY_SEP_STRING "/"
jpayne@69 66
jpayne@69 67 /**
jpayne@69 68 * Alias for standard ICU data
jpayne@69 69 * @internal ICU 3.0
jpayne@69 70 */
jpayne@69 71 #define U_ICUDATA_ALIAS "ICUDATA"
jpayne@69 72
jpayne@69 73 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 74
jpayne@69 75 /**
jpayne@69 76 * UDataInfo contains the properties about the requested data.
jpayne@69 77 * This is meta data.
jpayne@69 78 *
jpayne@69 79 * <p>This structure may grow in the future, indicated by the
jpayne@69 80 * <code>size</code> field.</p>
jpayne@69 81 *
jpayne@69 82 * <p>ICU data must be at least 8-aligned, and should be 16-aligned.
jpayne@69 83 * The UDataInfo struct begins 4 bytes after the start of the data item,
jpayne@69 84 * so it is 4-aligned.
jpayne@69 85 *
jpayne@69 86 * <p>The platform data property fields help determine if a data
jpayne@69 87 * file can be efficiently used on a given machine.
jpayne@69 88 * The particular fields are of importance only if the data
jpayne@69 89 * is affected by the properties - if there is integer data
jpayne@69 90 * with word sizes > 1 byte, char* text, or UChar* text.</p>
jpayne@69 91 *
jpayne@69 92 * <p>The implementation for the <code>udata_open[Choice]()</code>
jpayne@69 93 * functions may reject data based on the value in <code>isBigEndian</code>.
jpayne@69 94 * No other field is used by the <code>udata</code> API implementation.</p>
jpayne@69 95 *
jpayne@69 96 * <p>The <code>dataFormat</code> may be used to identify
jpayne@69 97 * the kind of data, e.g. a converter table.</p>
jpayne@69 98 *
jpayne@69 99 * <p>The <code>formatVersion</code> field should be used to
jpayne@69 100 * make sure that the format can be interpreted.
jpayne@69 101 * It may be a good idea to check only for the one or two highest
jpayne@69 102 * of the version elements to allow the data memory to
jpayne@69 103 * get more or somewhat rearranged contents, for as long
jpayne@69 104 * as the using code can still interpret the older contents.</p>
jpayne@69 105 *
jpayne@69 106 * <p>The <code>dataVersion</code> field is intended to be a
jpayne@69 107 * common place to store the source version of the data;
jpayne@69 108 * for data from the Unicode character database, this could
jpayne@69 109 * reflect the Unicode version.</p>
jpayne@69 110 *
jpayne@69 111 * @stable ICU 2.0
jpayne@69 112 */
jpayne@69 113 typedef struct {
jpayne@69 114 /** sizeof(UDataInfo)
jpayne@69 115 * @stable ICU 2.0 */
jpayne@69 116 uint16_t size;
jpayne@69 117
jpayne@69 118 /** unused, set to 0
jpayne@69 119 * @stable ICU 2.0*/
jpayne@69 120 uint16_t reservedWord;
jpayne@69 121
jpayne@69 122 /* platform data properties */
jpayne@69 123 /** 0 for little-endian machine, 1 for big-endian
jpayne@69 124 * @stable ICU 2.0 */
jpayne@69 125 uint8_t isBigEndian;
jpayne@69 126
jpayne@69 127 /** see U_CHARSET_FAMILY values in utypes.h
jpayne@69 128 * @stable ICU 2.0*/
jpayne@69 129 uint8_t charsetFamily;
jpayne@69 130
jpayne@69 131 /** sizeof(UChar), one of { 1, 2, 4 }
jpayne@69 132 * @stable ICU 2.0*/
jpayne@69 133 uint8_t sizeofUChar;
jpayne@69 134
jpayne@69 135 /** unused, set to 0
jpayne@69 136 * @stable ICU 2.0*/
jpayne@69 137 uint8_t reservedByte;
jpayne@69 138
jpayne@69 139 /** data format identifier
jpayne@69 140 * @stable ICU 2.0*/
jpayne@69 141 uint8_t dataFormat[4];
jpayne@69 142
jpayne@69 143 /** versions: [0] major [1] minor [2] milli [3] micro
jpayne@69 144 * @stable ICU 2.0*/
jpayne@69 145 uint8_t formatVersion[4];
jpayne@69 146
jpayne@69 147 /** versions: [0] major [1] minor [2] milli [3] micro
jpayne@69 148 * @stable ICU 2.0*/
jpayne@69 149 uint8_t dataVersion[4];
jpayne@69 150 } UDataInfo;
jpayne@69 151
jpayne@69 152 /* API for reading data -----------------------------------------------------*/
jpayne@69 153
jpayne@69 154 /**
jpayne@69 155 * Forward declaration of the data memory type.
jpayne@69 156 * @stable ICU 2.0
jpayne@69 157 */
jpayne@69 158 typedef struct UDataMemory UDataMemory;
jpayne@69 159
jpayne@69 160 /**
jpayne@69 161 * Callback function for udata_openChoice().
jpayne@69 162 * @param context parameter passed into <code>udata_openChoice()</code>.
jpayne@69 163 * @param type The type of the data as passed into <code>udata_openChoice()</code>.
jpayne@69 164 * It may be <code>NULL</code>.
jpayne@69 165 * @param name The name of the data as passed into <code>udata_openChoice()</code>.
jpayne@69 166 * @param pInfo A pointer to the <code>UDataInfo</code> structure
jpayne@69 167 * of data that has been loaded and will be returned
jpayne@69 168 * by <code>udata_openChoice()</code> if this function
jpayne@69 169 * returns <code>TRUE</code>.
jpayne@69 170 * @return TRUE if the current data memory is acceptable
jpayne@69 171 * @stable ICU 2.0
jpayne@69 172 */
jpayne@69 173 typedef UBool U_CALLCONV
jpayne@69 174 UDataMemoryIsAcceptable(void *context,
jpayne@69 175 const char *type, const char *name,
jpayne@69 176 const UDataInfo *pInfo);
jpayne@69 177
jpayne@69 178
jpayne@69 179 /**
jpayne@69 180 * Convenience function.
jpayne@69 181 * This function works the same as <code>udata_openChoice</code>
jpayne@69 182 * except that any data that matches the type and name
jpayne@69 183 * is assumed to be acceptable.
jpayne@69 184 * @param path Specifies an absolute path and/or a basename for the
jpayne@69 185 * finding of the data in the file system.
jpayne@69 186 * <code>NULL</code> for ICU data.
jpayne@69 187 * @param type A string that specifies the type of data to be loaded.
jpayne@69 188 * For example, resource bundles are loaded with type "res",
jpayne@69 189 * conversion tables with type "cnv".
jpayne@69 190 * This may be <code>NULL</code> or empty.
jpayne@69 191 * @param name A string that specifies the name of the data.
jpayne@69 192 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.
jpayne@69 193 * @return A pointer (handle) to a data memory object, or <code>NULL</code>
jpayne@69 194 * if an error occurs. Call <code>udata_getMemory()</code>
jpayne@69 195 * to get a pointer to the actual data.
jpayne@69 196 *
jpayne@69 197 * @see udata_openChoice
jpayne@69 198 * @stable ICU 2.0
jpayne@69 199 */
jpayne@69 200 U_STABLE UDataMemory * U_EXPORT2
jpayne@69 201 udata_open(const char *path, const char *type, const char *name,
jpayne@69 202 UErrorCode *pErrorCode);
jpayne@69 203
jpayne@69 204 /**
jpayne@69 205 * Data loading function.
jpayne@69 206 * This function is used to find and load efficiently data for
jpayne@69 207 * ICU and applications using ICU.
jpayne@69 208 * It provides an abstract interface that allows to specify a data
jpayne@69 209 * type and name to find and load the data.
jpayne@69 210 *
jpayne@69 211 * <p>The implementation depends on platform properties and user preferences
jpayne@69 212 * and may involve loading shared libraries (DLLs), mapping
jpayne@69 213 * files into memory, or fopen()/fread() files.
jpayne@69 214 * It may also involve using static memory or database queries etc.
jpayne@69 215 * Several or all data items may be combined into one entity
jpayne@69 216 * (DLL, memory-mappable file).</p>
jpayne@69 217 *
jpayne@69 218 * <p>The data is always preceded by a header that includes
jpayne@69 219 * a <code>UDataInfo</code> structure.
jpayne@69 220 * The caller's <code>isAcceptable()</code> function is called to make
jpayne@69 221 * sure that the data is useful. It may be called several times if it
jpayne@69 222 * rejects the data and there is more than one location with data
jpayne@69 223 * matching the type and name.</p>
jpayne@69 224 *
jpayne@69 225 * <p>If <code>path==NULL</code>, then ICU data is loaded.
jpayne@69 226 * Otherwise, it is separated into a basename and a basename-less directory string.
jpayne@69 227 * The basename is used as the data package name, and the directory is
jpayne@69 228 * logically prepended to the ICU data directory string.</p>
jpayne@69 229 *
jpayne@69 230 * <p>For details about ICU data loading see the User Guide
jpayne@69 231 * Data Management chapter. (http://icu-project.org/userguide/icudata.html)</p>
jpayne@69 232 *
jpayne@69 233 * @param path Specifies an absolute path and/or a basename for the
jpayne@69 234 * finding of the data in the file system.
jpayne@69 235 * <code>NULL</code> for ICU data.
jpayne@69 236 * @param type A string that specifies the type of data to be loaded.
jpayne@69 237 * For example, resource bundles are loaded with type "res",
jpayne@69 238 * conversion tables with type "cnv".
jpayne@69 239 * This may be <code>NULL</code> or empty.
jpayne@69 240 * @param name A string that specifies the name of the data.
jpayne@69 241 * @param isAcceptable This function is called to verify that loaded data
jpayne@69 242 * is useful for the client code. If it returns FALSE
jpayne@69 243 * for all data items, then <code>udata_openChoice()</code>
jpayne@69 244 * will return with an error.
jpayne@69 245 * @param context Arbitrary parameter to be passed into isAcceptable.
jpayne@69 246 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.
jpayne@69 247 * @return A pointer (handle) to a data memory object, or <code>NULL</code>
jpayne@69 248 * if an error occurs. Call <code>udata_getMemory()</code>
jpayne@69 249 * to get a pointer to the actual data.
jpayne@69 250 * @stable ICU 2.0
jpayne@69 251 */
jpayne@69 252 U_STABLE UDataMemory * U_EXPORT2
jpayne@69 253 udata_openChoice(const char *path, const char *type, const char *name,
jpayne@69 254 UDataMemoryIsAcceptable *isAcceptable, void *context,
jpayne@69 255 UErrorCode *pErrorCode);
jpayne@69 256
jpayne@69 257 /**
jpayne@69 258 * Close the data memory.
jpayne@69 259 * This function must be called to allow the system to
jpayne@69 260 * release resources associated with this data memory.
jpayne@69 261 * @param pData The pointer to data memory object
jpayne@69 262 * @stable ICU 2.0
jpayne@69 263 */
jpayne@69 264 U_STABLE void U_EXPORT2
jpayne@69 265 udata_close(UDataMemory *pData);
jpayne@69 266
jpayne@69 267 /**
jpayne@69 268 * Get the pointer to the actual data inside the data memory.
jpayne@69 269 * The data is read-only.
jpayne@69 270 *
jpayne@69 271 * ICU data must be at least 8-aligned, and should be 16-aligned.
jpayne@69 272 *
jpayne@69 273 * @param pData The pointer to data memory object
jpayne@69 274 * @stable ICU 2.0
jpayne@69 275 */
jpayne@69 276 U_STABLE const void * U_EXPORT2
jpayne@69 277 udata_getMemory(UDataMemory *pData);
jpayne@69 278
jpayne@69 279 /**
jpayne@69 280 * Get the information from the data memory header.
jpayne@69 281 * This allows to get access to the header containing
jpayne@69 282 * platform data properties etc. which is not part of
jpayne@69 283 * the data itself and can therefore not be accessed
jpayne@69 284 * via the pointer that <code>udata_getMemory()</code> returns.
jpayne@69 285 *
jpayne@69 286 * @param pData pointer to the data memory object
jpayne@69 287 * @param pInfo pointer to a UDataInfo object;
jpayne@69 288 * its <code>size</code> field must be set correctly,
jpayne@69 289 * typically to <code>sizeof(UDataInfo)</code>.
jpayne@69 290 *
jpayne@69 291 * <code>*pInfo</code> will be filled with the UDataInfo structure
jpayne@69 292 * in the data memory object. If this structure is smaller than
jpayne@69 293 * <code>pInfo->size</code>, then the <code>size</code> will be
jpayne@69 294 * adjusted and only part of the structure will be filled.
jpayne@69 295 * @stable ICU 2.0
jpayne@69 296 */
jpayne@69 297 U_STABLE void U_EXPORT2
jpayne@69 298 udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);
jpayne@69 299
jpayne@69 300 /**
jpayne@69 301 * This function bypasses the normal ICU data loading process and
jpayne@69 302 * allows you to force ICU's system data to come out of a user-specified
jpayne@69 303 * area in memory.
jpayne@69 304 *
jpayne@69 305 * ICU data must be at least 8-aligned, and should be 16-aligned.
jpayne@69 306 * See http://userguide.icu-project.org/icudata
jpayne@69 307 *
jpayne@69 308 * The format of this data is that of the icu common data file, as is
jpayne@69 309 * generated by the pkgdata tool with mode=common or mode=dll.
jpayne@69 310 * You can read in a whole common mode file and pass the address to the start of the
jpayne@69 311 * data, or (with the appropriate link options) pass in the pointer to
jpayne@69 312 * the data that has been loaded from a dll by the operating system,
jpayne@69 313 * as shown in this code:
jpayne@69 314 *
jpayne@69 315 * extern const char U_IMPORT U_ICUDATA_ENTRY_POINT [];
jpayne@69 316 * // U_ICUDATA_ENTRY_POINT is same as entry point specified to pkgdata tool
jpayne@69 317 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 318 *
jpayne@69 319 * udata_setCommonData(&U_ICUDATA_ENTRY_POINT, &status);
jpayne@69 320 *
jpayne@69 321 * It is important that the declaration be as above. The entry point
jpayne@69 322 * must not be declared as an extern void*.
jpayne@69 323 *
jpayne@69 324 * Starting with ICU 4.4, it is possible to set several data packages,
jpayne@69 325 * one per call to this function.
jpayne@69 326 * udata_open() will look for data in the multiple data packages in the order
jpayne@69 327 * in which they were set.
jpayne@69 328 * The position of the linked-in or default-name ICU .data package in the
jpayne@69 329 * search list depends on when the first data item is loaded that is not contained
jpayne@69 330 * in the already explicitly set packages.
jpayne@69 331 * If data was loaded implicitly before the first call to this function
jpayne@69 332 * (for example, via opening a converter, constructing a UnicodeString
jpayne@69 333 * from default-codepage data, using formatting or collation APIs, etc.),
jpayne@69 334 * then the default data will be first in the list.
jpayne@69 335 *
jpayne@69 336 * This function has no effect on application (non ICU) data. See udata_setAppData()
jpayne@69 337 * for similar functionality for application data.
jpayne@69 338 *
jpayne@69 339 * @param data pointer to ICU common data
jpayne@69 340 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
jpayne@69 341 * @stable ICU 2.0
jpayne@69 342 */
jpayne@69 343 U_STABLE void U_EXPORT2
jpayne@69 344 udata_setCommonData(const void *data, UErrorCode *err);
jpayne@69 345
jpayne@69 346
jpayne@69 347 /**
jpayne@69 348 * This function bypasses the normal ICU data loading process for application-specific
jpayne@69 349 * data and allows you to force the it to come out of a user-specified
jpayne@69 350 * pointer.
jpayne@69 351 *
jpayne@69 352 * ICU data must be at least 8-aligned, and should be 16-aligned.
jpayne@69 353 * See http://userguide.icu-project.org/icudata
jpayne@69 354 *
jpayne@69 355 * The format of this data is that of the icu common data file, like 'icudt26l.dat'
jpayne@69 356 * or the corresponding shared library (DLL) file.
jpayne@69 357 * The application must read in or otherwise construct an image of the data and then
jpayne@69 358 * pass the address of it to this function.
jpayne@69 359 *
jpayne@69 360 *
jpayne@69 361 * Warning: setAppData will set a U_USING_DEFAULT_WARNING code if
jpayne@69 362 * data with the specifed path that has already been opened, or
jpayne@69 363 * if setAppData with the same path has already been called.
jpayne@69 364 * Any such calls to setAppData will have no effect.
jpayne@69 365 *
jpayne@69 366 *
jpayne@69 367 * @param packageName the package name by which the application will refer
jpayne@69 368 * to (open) this data
jpayne@69 369 * @param data pointer to the data
jpayne@69 370 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
jpayne@69 371 * @see udata_setCommonData
jpayne@69 372 * @stable ICU 2.0
jpayne@69 373 */
jpayne@69 374 U_STABLE void U_EXPORT2
jpayne@69 375 udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
jpayne@69 376
jpayne@69 377 /**
jpayne@69 378 * Possible settings for udata_setFileAccess()
jpayne@69 379 * @see udata_setFileAccess
jpayne@69 380 * @stable ICU 3.4
jpayne@69 381 */
jpayne@69 382 typedef enum UDataFileAccess {
jpayne@69 383 /** ICU looks for data in single files first, then in packages. (default) @stable ICU 3.4 */
jpayne@69 384 UDATA_FILES_FIRST,
jpayne@69 385 /** An alias for the default access mode. @stable ICU 3.4 */
jpayne@69 386 UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
jpayne@69 387 /** ICU only loads data from packages, not from single files. @stable ICU 3.4 */
jpayne@69 388 UDATA_ONLY_PACKAGES,
jpayne@69 389 /** ICU loads data from packages first, and only from single files
jpayne@69 390 if the data cannot be found in a package. @stable ICU 3.4 */
jpayne@69 391 UDATA_PACKAGES_FIRST,
jpayne@69 392 /** ICU does not access the file system for data loading. @stable ICU 3.4 */
jpayne@69 393 UDATA_NO_FILES,
jpayne@69 394 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 395 /**
jpayne@69 396 * Number of real UDataFileAccess values.
jpayne@69 397 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69 398 */
jpayne@69 399 UDATA_FILE_ACCESS_COUNT
jpayne@69 400 #endif // U_HIDE_DEPRECATED_API
jpayne@69 401 } UDataFileAccess;
jpayne@69 402
jpayne@69 403 /**
jpayne@69 404 * This function may be called to control how ICU loads data. It must be called
jpayne@69 405 * before any ICU data is loaded, including application data loaded with
jpayne@69 406 * ures/ResourceBundle or udata APIs. This function is not multithread safe.
jpayne@69 407 * The results of calling it while other threads are loading data are undefined.
jpayne@69 408 * @param access The type of file access to be used
jpayne@69 409 * @param status Error code.
jpayne@69 410 * @see UDataFileAccess
jpayne@69 411 * @stable ICU 3.4
jpayne@69 412 */
jpayne@69 413 U_STABLE void U_EXPORT2
jpayne@69 414 udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
jpayne@69 415
jpayne@69 416 U_CDECL_END
jpayne@69 417
jpayne@69 418 #if U_SHOW_CPLUSPLUS_API
jpayne@69 419
jpayne@69 420 U_NAMESPACE_BEGIN
jpayne@69 421
jpayne@69 422 /**
jpayne@69 423 * \class LocalUDataMemoryPointer
jpayne@69 424 * "Smart pointer" class, closes a UDataMemory via udata_close().
jpayne@69 425 * For most methods see the LocalPointerBase base class.
jpayne@69 426 *
jpayne@69 427 * @see LocalPointerBase
jpayne@69 428 * @see LocalPointer
jpayne@69 429 * @stable ICU 4.4
jpayne@69 430 */
jpayne@69 431 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDataMemoryPointer, UDataMemory, udata_close);
jpayne@69 432
jpayne@69 433 U_NAMESPACE_END
jpayne@69 434
jpayne@69 435 #endif // U_SHOW_CPLUSPLUS_API
jpayne@69 436
jpayne@69 437 #endif