This structure may grow in the future, indicated by the
sl@0: * size field.
The platform data property fields help determine if a data sl@0: * file can be efficiently used on a given machine. sl@0: * The particular fields are of importance only if the data sl@0: * is affected by the properties - if there is integer data sl@0: * with word sizes > 1 byte, char* text, or UChar* text.
sl@0: * sl@0: *The implementation for the udata_open[Choice]()
sl@0: * functions may reject data based on the value in isBigEndian.
sl@0: * No other field is used by the udata API implementation.
The dataFormat may be used to identify
sl@0: * the kind of data, e.g. a converter table.
The formatVersion field should be used to
sl@0: * make sure that the format can be interpreted.
sl@0: * I may be a good idea to check only for the one or two highest
sl@0: * of the version elements to allow the data memory to
sl@0: * get more or somewhat rearranged contents, for as long
sl@0: * as the using code can still interpret the older contents.
The dataVersion field is intended to be a
sl@0: * common place to store the source version of the data;
sl@0: * for data from the Unicode character database, this could
sl@0: * reflect the Unicode version.
udata_openChoice().
sl@0: * @param type The type of the data as passed into udata_openChoice().
sl@0: * It may be NULL.
sl@0: * @param name The name of the data as passed into udata_openChoice().
sl@0: * @param pInfo A pointer to the UDataInfo structure
sl@0: * of data that has been loaded and will be returned
sl@0: * by udata_openChoice() if this function
sl@0: * returns TRUE.
sl@0: * @return TRUE if the current data memory is acceptable
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: typedef UBool U_CALLCONV
sl@0: UDataMemoryIsAcceptable(void *context,
sl@0: const char *type, const char *name,
sl@0: const UDataInfo *pInfo);
sl@0:
sl@0:
sl@0: /**
sl@0: * Convenience function.
sl@0: * This function works the same as udata_openChoice
sl@0: * except that any data that matches the type and name
sl@0: * is assumed to be acceptable.
sl@0: * @param path Specifies an absolute path and/or a basename for the
sl@0: * finding of the data in the file system.
sl@0: * NULL for ICU data.
sl@0: * @param type A string that specifies the type of data to be loaded.
sl@0: * For example, resource bundles are loaded with type "res",
sl@0: * conversion tables with type "cnv".
sl@0: * This may be NULL or empty.
sl@0: * @param name A string that specifies the name of the data.
sl@0: * @param pErrorCode An ICU UErrorCode parameter. It must not be NULL.
sl@0: * @return A pointer (handle) to a data memory object, or NULL
sl@0: * if an error occurs. Call udata_getMemory()
sl@0: * to get a pointer to the actual data.
sl@0: *
sl@0: * @see udata_openChoice
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE UDataMemory * U_EXPORT2
sl@0: udata_open(const char *path, const char *type, const char *name,
sl@0: UErrorCode *pErrorCode);
sl@0:
sl@0: /**
sl@0: * Data loading function.
sl@0: * This function is used to find and load efficiently data for
sl@0: * ICU and applications using ICU.
sl@0: * It provides an abstract interface that allows to specify a data
sl@0: * type and name to find and load the data.
sl@0: *
sl@0: * The implementation depends on platform properties and user preferences sl@0: * and may involve loading shared libraries (DLLs), mapping sl@0: * files into memory, or fopen()/fread() files. sl@0: * It may also involve using static memory or database queries etc. sl@0: * Several or all data items may be combined into one entity sl@0: * (DLL, memory-mappable file).
sl@0: * sl@0: *The data is always preceded by a header that includes
sl@0: * a UDataInfo structure.
sl@0: * The caller's isAcceptable() function is called to make
sl@0: * sure that the data is useful. It may be called several times if it
sl@0: * rejects the data and there is more than one location with data
sl@0: * matching the type and name.
If path==NULL, then ICU data is loaded.
sl@0: * Otherwise, it is separated into a basename and a basename-less directory string.
sl@0: * The basename is used as the data package name, and the directory is
sl@0: * logically prepended to the ICU data directory string.
For details about ICU data loading see the User Guide sl@0: * Data Management chapter. (http://icu.sourceforge.net/userguide/icudata.html)
sl@0: * sl@0: * @param path Specifies an absolute path and/or a basename for the sl@0: * finding of the data in the file system. sl@0: *NULL for ICU data.
sl@0: * @param type A string that specifies the type of data to be loaded.
sl@0: * For example, resource bundles are loaded with type "res",
sl@0: * conversion tables with type "cnv".
sl@0: * This may be NULL or empty.
sl@0: * @param name A string that specifies the name of the data.
sl@0: * @param isAcceptable This function is called to verify that loaded data
sl@0: * is useful for the client code. If it returns FALSE
sl@0: * for all data items, then udata_openChoice()
sl@0: * will return with an error.
sl@0: * @param context Arbitrary parameter to be passed into isAcceptable.
sl@0: * @param pErrorCode An ICU UErrorCode parameter. It must not be NULL.
sl@0: * @return A pointer (handle) to a data memory object, or NULL
sl@0: * if an error occurs. Call udata_getMemory()
sl@0: * to get a pointer to the actual data.
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE UDataMemory * U_EXPORT2
sl@0: udata_openChoice(const char *path, const char *type, const char *name,
sl@0: UDataMemoryIsAcceptable *isAcceptable, void *context,
sl@0: UErrorCode *pErrorCode);
sl@0:
sl@0: /**
sl@0: * Close the data memory.
sl@0: * This function must be called to allow the system to
sl@0: * release resources associated with this data memory.
sl@0: * @param pData The pointer to data memory object
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE void U_EXPORT2
sl@0: udata_close(UDataMemory *pData);
sl@0:
sl@0: /**
sl@0: * Get the pointer to the actual data inside the data memory.
sl@0: * The data is read-only.
sl@0: * @param pData The pointer to data memory object
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE const void * U_EXPORT2
sl@0: udata_getMemory(UDataMemory *pData);
sl@0:
sl@0: /**
sl@0: * Get the information from the data memory header.
sl@0: * This allows to get access to the header containing
sl@0: * platform data properties etc. which is not part of
sl@0: * the data itself and can therefore not be accessed
sl@0: * via the pointer that udata_getMemory() returns.
sl@0: *
sl@0: * @param pData pointer to the data memory object
sl@0: * @param pInfo pointer to a UDataInfo object;
sl@0: * its size field must be set correctly,
sl@0: * typically to sizeof(UDataInfo).
sl@0: *
sl@0: * *pInfo will be filled with the UDataInfo structure
sl@0: * in the data memory object. If this structure is smaller than
sl@0: * pInfo->size, then the size will be
sl@0: * adjusted and only part of the structure will be filled.
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE void U_EXPORT2
sl@0: udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);
sl@0:
sl@0: /**
sl@0: * This function bypasses the normal ICU data loading process and
sl@0: * allows you to force ICU's system data to come out of a user-specified
sl@0: * area in memory.
sl@0: *
sl@0: * The format of this data is that of the icu common data file, as is
sl@0: * generated by the pkgdata tool with mode=common or mode=dll.
sl@0: * You can read in a whole common mode file and pass the address to the start of the
sl@0: * data, or (with the appropriate link options) pass in the pointer to
sl@0: * the data that has been loaded from a dll by the operating system,
sl@0: * as shown in this code:
sl@0: *
sl@0: * extern const char U_IMPORT U_ICUDATA_ENTRY_POINT [];
sl@0: * // U_ICUDATA_ENTRY_POINT is same as entry point specified to pkgdata tool
sl@0: * UErrorCode status = U_ZERO_ERROR;
sl@0: *
sl@0: * udata_setCommonData(&U_ICUDATA_ENTRY_POINT, &status);
sl@0: *
sl@0: * Warning: ICU must NOT have even attempted to access its data yet
sl@0: * when this call is made, or U_USING_DEFAULT_WARNING code will
sl@0: * be returned. Be careful of UnicodeStrings in static initialization which
sl@0: * may attempt to load a converter (use the UNICODE_STRING(x) macro instead).
sl@0: *
sl@0: * Also note that it is important that the declaration be as above. The entry point
sl@0: * must not be declared as an extern void*.
sl@0: *
sl@0: * This function has no effect on application (non ICU) data. See udata_setAppData()
sl@0: * for similar functionality for application data.
sl@0: *
sl@0: * @param data pointer to ICU common data
sl@0: * @param err outgoing error status U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR
sl@0: * @stable ICU 2.0
sl@0: */
sl@0:
sl@0: U_STABLE void U_EXPORT2
sl@0: udata_setCommonData(const void *data, UErrorCode *err);
sl@0:
sl@0:
sl@0: /**
sl@0: * This function bypasses the normal ICU data loading process for application-specific
sl@0: * data and allows you to force the it to come out of a user-specified
sl@0: * pointer.
sl@0: *
sl@0: * The format of this data is that of the icu common data file, like 'icudt26l.dat'
sl@0: * or the corresponding shared library (DLL) file.
sl@0: * The application must read in or otherwise construct an image of the data and then
sl@0: * pass the address of it to this function.
sl@0: *
sl@0: *
sl@0: * Warning: setAppData will set a U_USING_DEFAULT_WARNING code if
sl@0: * data with the specifed path that has already been opened, or
sl@0: * if setAppData with the same path has already been called.
sl@0: * Any such calls to setAppData will have no effect.
sl@0: *
sl@0: *
sl@0: * @param packageName the package name by which the application will refer
sl@0: * to (open) this data
sl@0: * @param data pointer to the data
sl@0: * @param err outgoing error status U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR
sl@0: * @see udata_setCommonData
sl@0: * @stable ICU 2.0
sl@0: */
sl@0: U_STABLE void U_EXPORT2
sl@0: udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
sl@0:
sl@0: /**
sl@0: * Possible settings for udata_setFileAccess()
sl@0: * @see udata_setFileAccess
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef enum UDataFileAccess {
sl@0: /** ICU does not access the file system for data loading. */
sl@0: UDATA_NO_FILES,
sl@0: /** ICU only loads data from packages, not from single files. */
sl@0: UDATA_ONLY_PACKAGES,
sl@0: /** ICU loads data from packages first, and only from single files
sl@0: if the data cannot be found in a package. */
sl@0: UDATA_PACKAGES_FIRST,
sl@0: /** ICU looks for data in single files first, then in packages. (default) */
sl@0: UDATA_FILES_FIRST,
sl@0: /** An alias for the default access mode. */
sl@0: UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
sl@0: UDATA_FILE_ACCESS_COUNT
sl@0: } UDataFileAccess;
sl@0:
sl@0: /**
sl@0: * This function may be called to control how ICU loads data. It must be called
sl@0: * before any ICU data is loaded, including application data loaded with ures/ResourceBundle or
sl@0: * udata APIs. It should be called before u_init. This function is not multithread safe.
sl@0: * The results of calling it while other threads are loading data are undefined.
sl@0: * @param access The type of file access to be used
sl@0: * @param status Error code.
sl@0: * @see UDataFileAccess
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT void U_EXPORT2
sl@0: udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
sl@0:
sl@0: U_CDECL_END
sl@0:
sl@0: #endif