/*

******************************************************************************

*

*   Copyright (C) 1999-2005, International Business Machines

*   Corporation and others.  All Rights Reserved.

*

******************************************************************************

*   file name:  udata.h

*   encoding:   US-ASCII

*   tab size:   8 (not used)

*   indentation:4

*

*   created on: 1999oct25

*   created by: Markus W. Scherer

*/

#ifndef __UDATA_H__

#define __UDATA_H__

#include "unicode/utypes.h"

U_CDECL_BEGIN

/**

 * \file

 * \brief C API: Data loading interface

 *

 * <h2>Information about data loading interface</h2>

 *

 * This API is used to find and efficiently load data for ICU and applications

 * using ICU. It provides an abstract interface that specifies a data type and

 * name to find and load the data. Normally this API is used by other ICU APIs

 * to load required data out of the ICU data library, but it can be used to

 * load data out of other places.

 *

 * See the User Guide Data Management chapter.

 */

/**

 * Character used to separate package names from tree names 

 * @internal ICU 3.0

 */

#define U_TREE_SEPARATOR '-'

/**

 * String used to separate package names from tree names 

 * @internal ICU 3.0

 */

#define U_TREE_SEPARATOR_STRING "-"

/**

 * Character used to separate parts of entry names

 * @internal ICU 3.0

 */

#define U_TREE_ENTRY_SEP_CHAR '/'

/**

 * String used to separate parts of entry names

 * @internal ICU 3.0

 */

#define U_TREE_ENTRY_SEP_STRING "/"

/**

 * Alias for standard ICU data 

 * @internal ICU 3.0

 */

#define U_ICUDATA_ALIAS "ICUDATA"

/**

 * UDataInfo contains the properties about the requested data.

 * This is meta data.

 *

 * <p>This structure may grow in the future, indicated by the

 * <code>size</code> field.</p>

 *

 * <p>The platform data property fields help determine if a data

 * file can be efficiently used on a given machine.

 * The particular fields are of importance only if the data

 * is affected by the properties - if there is integer data

 * with word sizes > 1 byte, char* text, or UChar* text.</p>

 *

 * <p>The implementation for the <code>udata_open[Choice]()</code>

 * functions may reject data based on the value in <code>isBigEndian</code>.

 * No other field is used by the <code>udata</code> API implementation.</p>

 *

 * <p>The <code>dataFormat</code> may be used to identify

 * the kind of data, e.g. a converter table.</p>

 *

 * <p>The <code>formatVersion</code> field should be used to

 * make sure that the format can be interpreted.

 * I may be a good idea to check only for the one or two highest

 * of the version elements to allow the data memory to

 * get more or somewhat rearranged contents, for as long

 * as the using code can still interpret the older contents.</p>

 *

 * <p>The <code>dataVersion</code> field is intended to be a

 * common place to store the source version of the data;

 * for data from the Unicode character database, this could

 * reflect the Unicode version.</p>

 * @stable ICU 2.0

 */

typedef struct {

    /** sizeof(UDataInfo)

     *  @stable ICU 2.0 */

    uint16_t size;

    /** unused, set to 0 

     *  @stable ICU 2.0*/

    uint16_t reservedWord;

    /* platform data properties */

    /** 0 for little-endian machine, 1 for big-endian

     *  @stable ICU 2.0 */

    uint8_t isBigEndian;

    /** see U_CHARSET_FAMILY values in utypes.h 

     *  @stable ICU 2.0*/

    uint8_t charsetFamily;

    /** sizeof(UChar), one of { 1, 2, 4 } 

     *  @stable ICU 2.0*/

    uint8_t sizeofUChar;

    /** unused, set to 0 

     *  @stable ICU 2.0*/

    uint8_t reservedByte;

    /** data format identifier 

     *  @stable ICU 2.0*/

    uint8_t dataFormat[4];

    /** versions: [0] major [1] minor [2] milli [3] micro 

     *  @stable ICU 2.0*/

    uint8_t formatVersion[4];

    /** versions: [0] major [1] minor [2] milli [3] micro 

     *  @stable ICU 2.0*/

    uint8_t dataVersion[4];

} UDataInfo;

/* API for reading data -----------------------------------------------------*/

/**

 * Forward declaration of the data memory type.

 * @stable ICU 2.0

 */

typedef struct UDataMemory UDataMemory;

/**

 * Callback function for udata_openChoice().

 * @param context parameter passed into <code>udata_openChoice()</code>.

 * @param type The type of the data as passed into <code>udata_openChoice()</code>.

 *             It may be <code>NULL</code>.

 * @param name The name of the data as passed into <code>udata_openChoice()</code>.

 * @param pInfo A pointer to the <code>UDataInfo</code> structure

 *              of data that has been loaded and will be returned

 *              by <code>udata_openChoice()</code> if this function

 *              returns <code>TRUE</code>.

 * @return TRUE if the current data memory is acceptable

 * @stable ICU 2.0

 */

typedef UBool U_CALLCONV

UDataMemoryIsAcceptable(void *context,

                        const char *type, const char *name,

                        const UDataInfo *pInfo);

/**

 * Convenience function.

 * This function works the same as <code>udata_openChoice</code>

 * except that any data that matches the type and name

 * is assumed to be acceptable.

 * @param path Specifies an absolute path and/or a basename for the

 *             finding of the data in the file system.

 *             <code>NULL</code> for ICU data.

 * @param type A string that specifies the type of data to be loaded.

 *             For example, resource bundles are loaded with type "res",

 *             conversion tables with type "cnv".

 *             This may be <code>NULL</code> or empty.

 * @param name A string that specifies the name of the data.

 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.

 * @return A pointer (handle) to a data memory object, or <code>NULL</code>

 *         if an error occurs. Call <code>udata_getMemory()</code>

 *         to get a pointer to the actual data.

 *

 * @see udata_openChoice

 * @stable ICU 2.0

 */

U_STABLE UDataMemory * U_EXPORT2

udata_open(const char *path, const char *type, const char *name,

           UErrorCode *pErrorCode);

/**

 * Data loading function.

 * This function is used to find and load efficiently data for

 * ICU and applications using ICU.

 * It provides an abstract interface that allows to specify a data

 * type and name to find and load the data.

 *

 * <p>The implementation depends on platform properties and user preferences

 * and may involve loading shared libraries (DLLs), mapping

 * files into memory, or fopen()/fread() files.

 * It may also involve using static memory or database queries etc.

 * Several or all data items may be combined into one entity

 * (DLL, memory-mappable file).</p>

 *

 * <p>The data is always preceded by a header that includes

 * a <code>UDataInfo</code> structure.

 * The caller's <code>isAcceptable()</code> function is called to make

 * sure that the data is useful. It may be called several times if it

 * rejects the data and there is more than one location with data

 * matching the type and name.</p>

 *

 * <p>If <code>path==NULL</code>, then ICU data is loaded.

 * Otherwise, it is separated into a basename and a basename-less directory string.

 * The basename is used as the data package name, and the directory is

 * logically prepended to the ICU data directory string.</p>

 *

 * <p>For details about ICU data loading see the User Guide

 * Data Management chapter. (http://icu.sourceforge.net/userguide/icudata.html)</p>

 *

 * @param path Specifies an absolute path and/or a basename for the

 *             finding of the data in the file system.

 *             <code>NULL</code> for ICU data.

 * @param type A string that specifies the type of data to be loaded.

 *             For example, resource bundles are loaded with type "res",

 *             conversion tables with type "cnv".

 *             This may be <code>NULL</code> or empty.

 * @param name A string that specifies the name of the data.

 * @param isAcceptable This function is called to verify that loaded data

 *                     is useful for the client code. If it returns FALSE

 *                     for all data items, then <code>udata_openChoice()</code>

 *                     will return with an error.

 * @param context Arbitrary parameter to be passed into isAcceptable.

 * @param pErrorCode An ICU UErrorCode parameter. It must not be <code>NULL</code>.

 * @return A pointer (handle) to a data memory object, or <code>NULL</code>

 *         if an error occurs. Call <code>udata_getMemory()</code>

 *         to get a pointer to the actual data.

 * @stable ICU 2.0

 */

U_STABLE UDataMemory * U_EXPORT2

udata_openChoice(const char *path, const char *type, const char *name,

                 UDataMemoryIsAcceptable *isAcceptable, void *context,

                 UErrorCode *pErrorCode);

/**

 * Close the data memory.

 * This function must be called to allow the system to

 * release resources associated with this data memory.

 * @param pData The pointer to data memory object

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2

udata_close(UDataMemory *pData);

/**

 * Get the pointer to the actual data inside the data memory.

 * The data is read-only.

 * @param pData The pointer to data memory object

 * @stable ICU 2.0

 */

U_STABLE const void * U_EXPORT2

udata_getMemory(UDataMemory *pData);

/**

 * Get the information from the data memory header.

 * This allows to get access to the header containing

 * platform data properties etc. which is not part of

 * the data itself and can therefore not be accessed

 * via the pointer that <code>udata_getMemory()</code> returns.

 *

 * @param pData pointer to the data memory object

 * @param pInfo pointer to a UDataInfo object;

 *              its <code>size</code> field must be set correctly,

 *              typically to <code>sizeof(UDataInfo)</code>.

 *

 * <code>*pInfo</code> will be filled with the UDataInfo structure

 * in the data memory object. If this structure is smaller than

 * <code>pInfo->size</code>, then the <code>size</code> will be

 * adjusted and only part of the structure will be filled.

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2

udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);

/**

 * This function bypasses the normal ICU data loading process and

 * allows you to force ICU's system data to come out of a user-specified

 * area in memory.

 *

 * The format of this data is that of the icu common data file, as is

 * generated by the pkgdata tool with mode=common or mode=dll.

 * You can read in a whole common mode file and pass the address to the start of the

 * data, or (with the appropriate link options) pass in the pointer to

 * the data that has been loaded from a dll by the operating system,

 * as shown in this code:

 *

 *       extern const  char U_IMPORT U_ICUDATA_ENTRY_POINT []; 

 *        // U_ICUDATA_ENTRY_POINT is same as entry point specified to pkgdata tool

 *       UErrorCode  status = U_ZERO_ERROR;

 *

 *       udata_setCommonData(&U_ICUDATA_ENTRY_POINT, &status);

 *

 * Warning: ICU must NOT have even attempted to access its data yet

 * when this call is made, or U_USING_DEFAULT_WARNING code will

 * be returned. Be careful of UnicodeStrings in static initialization which

 * may attempt to load a converter (use the UNICODE_STRING(x) macro instead).

 *

 * Also note that it is important that the declaration be as above. The entry point

 * must not be declared as an extern void*.

 *

 * This function has no effect on application (non ICU) data.  See udata_setAppData()

 * for similar functionality for application data.

 *

 * @param data pointer to ICU common data

 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2

udata_setCommonData(const void *data, UErrorCode *err);

/**

 * This function bypasses the normal ICU data loading process for application-specific

 * data and allows you to force the it to come out of a user-specified

 * pointer.

 *

 * The format of this data is that of the icu common data file, like 'icudt26l.dat'

 * or the corresponding shared library (DLL) file.

 * The application must read in or otherwise construct an image of the data and then

 * pass the address of it to this function.

 *

 *

 * Warning:  setAppData will set a U_USING_DEFAULT_WARNING code if

 *           data with the specifed path that has already been opened, or

 *           if setAppData with the same path has already been called.

 *           Any such calls to setAppData will have no effect.

 *

 *

 * @param packageName the package name by which the application will refer

 *             to (open) this data

 * @param data pointer to the data

 * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>

 * @see udata_setCommonData

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2

udata_setAppData(const char *packageName, const void *data, UErrorCode *err);

/**

 * Possible settings for udata_setFileAccess()

 * @see udata_setFileAccess

 * @draft ICU 3.4

 */

typedef enum UDataFileAccess {

    /** ICU does not access the file system for data loading. */

    UDATA_NO_FILES,

    /** ICU only loads data from packages, not from single files. */

    UDATA_ONLY_PACKAGES,

    /** ICU loads data from packages first, and only from single files

        if the data cannot be found in a package. */

    UDATA_PACKAGES_FIRST,

    /** ICU looks for data in single files first, then in packages. (default) */

    UDATA_FILES_FIRST,

    /** An alias for the default access mode. */

    UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,

    UDATA_FILE_ACCESS_COUNT

} UDataFileAccess;

/**

 * This function may be called to control how ICU loads data. It must be called

 * before any ICU data is loaded, including application data loaded with ures/ResourceBundle or

 * udata APIs. It should be called before u_init.  This function is not multithread safe.  

 * The results of calling it while other threads are loading data are undefined.

 * @param access The type of file access to be used

 * @param status Error code.

 * @see UDataFileAccess

 * @draft ICU 3.4 

 */

U_DRAFT void U_EXPORT2

udata_setFileAccess(UDataFileAccess access, UErrorCode *status);

U_CDECL_END

#endif