Main Page   Class Hierarchy   Alphabetical List   Data Structures   File List   Data Fields   Globals  

udata.h File Reference

C API: Data memory. More...

#include "unicode/utypes.h"

Go to the source code of this file.

Data Structures

struct  UDataInfo

Typedefs

typedef UDataMemory UDataMemory
 Forward declaration of the data memory type. More...

typedef UBool UDataMemoryIsAcceptable (void *context, const char *type, const char *name, const UDataInfo *pInfo)
 Callback function for udata_openChoice(). More...


Functions

U_CAPI UDataMemory *U_EXPORT2 udata_open (const char *path, const char *type, const char *name, UErrorCode *pErrorCode)
 Convenience function. More...

U_CAPI UDataMemory *U_EXPORT2 udata_openChoice (const char *path, const char *type, const char *name, UDataMemoryIsAcceptable *isAcceptable, void *context, UErrorCode *pErrorCode)
 Data loading function. More...

U_CAPI void U_EXPORT2 udata_close (UDataMemory *pData)
 Close the data memory. More...

U_CAPI const void *U_EXPORT2 udata_getMemory (UDataMemory *pData)
 Get the pointer to the actual data inside the data memory. More...

U_CAPI void U_EXPORT2 udata_getInfo (UDataMemory *pData, UDataInfo *pInfo)
 Get the information from the data memory header. More...

U_CAPI void U_EXPORT2 udata_setCommonData (const void *data, UErrorCode *err)
 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. More...

U_CAPI void U_EXPORT2 udata_setAppData (const char *path, 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. More...


Detailed Description

C API: Data memory.

Information about data memory.

This structure may grow in the future, indicated by the size field.

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.

The implementation for the udata_open[Choice]() functions may reject data based on the value in isBigEndian. No other field is used by the udata API implementation.

The dataFormat may be used to identify the kind of data, e.g. a converter table.

The formatVersion 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.

The dataVersion 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. @stable


Typedef Documentation

typedef struct UDataMemory UDataMemory
 

Forward declaration of the data memory type.

@stable

typedef UBool UDataMemoryIsAcceptable(void *context, const char *type, const char *name, const UDataInfo *pInfo)
 

Callback function for udata_openChoice().

Parameters:
context  parameter passed into udata_openChoice().
type  The type of the data as passed into udata_openChoice(). It may be NULL.
name  The name of the data as passed into udata_openChoice().
pInfo  A pointer to the UDataInfo structure of data that has been loaded and will be returned by udata_openChoice() if this function returns TRUE.
Returns:
TRUE if the current data memory is acceptable @stable


Function Documentation

U_CAPI void U_EXPORT2 udata_close UDataMemory   pData
 

Close the data memory.

This function must be called to allow the system to release resources associated with this data memory. @stable

U_CAPI void U_EXPORT2 udata_getInfo UDataMemory   pData,
UDataInfo *    pInfo
 

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 udata_getMemory() returns.

Parameters:
pData  pointer to the data memory object
pInfo  pointer to a UDataInfo object; its size field must be set correctly, typically to sizeof(UDataInfo).
*pInfo will be filled with the UDataInfo structure in the data memory object. If this structure is smaller than pInfo->size, then the size will be adjusted and only part of the structure will be filled. @stable

U_CAPI const void* U_EXPORT2 udata_getMemory UDataMemory   pData
 

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

The data is read-only. @stable

U_CAPI UDataMemory* U_EXPORT2 udata_open const char *    path,
const char *    type,
const char *    name,
UErrorCode   pErrorCode
 

Convenience function.

This function works the same as udata_openChoice except that any data that matches the type and name is assumed to be acceptable. @stable

U_CAPI UDataMemory* U_EXPORT2 udata_openChoice const char *    path,
const char *    type,
const char *    name,
UDataMemoryIsAcceptable   isAcceptable,
void *    context,
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.

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).

The data is always preceded by a header that includes a UDataInfo structure. The caller's isAcceptable() 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.

If path==NULL, then ICU data is loaded. Otherwise, it is separated into a basename and a basename-less path string. If the path string is empty, then u_getDataDirectory() is set in its place. When data is loaded from files or DLLs (shared libraries) and may be stored in common files, then the data finding is roughly as follows:

  • common file at path/basename has entry name_type?
  • common file at basename has entry name_type?
  • separate file at path/basename_name_type?
  • separate file at basename_name_type?
  • separate file at path/name_type?
  • separate file at name_type?
If the basename is empty, then only the last two options are attempted. Otherwise, it serves as a name for a common data file or as a basename (collection name) prefix for individual files.
Parameters:
path  Specifies an absolute path and/or a basename for the finding of the data in the file system. NULL for ICU data.
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 NULL or empty.
name  A string that specifies the name of the data.
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 udata_openChoice() will return with an error.
context  Arbitrary parameter to be passed into isAcceptable.
pErrorCode  An ICU UErrorCode parameter. It must not be NULL.
Returns:
A pointer (handle) to a data memory object, or NULL if an error occurs. Call udata_getMemory() to get a pointer to the actual data. @stable

U_CAPI void U_EXPORT2 udata_setAppData const char *    path,
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 'icudata.dat' 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 fail with a U_USING_DEFAULT_ERROR error 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.

Parameters:
path  pointer to the path name by which the application will refer to (open) this data.
data  pointer to the data
err  outgoing error status U_USING_DEFAULT_ERROR, U_UNSUPPORTED_ERROR @draft ICU 2.0

U_CAPI void U_EXPORT2 udata_setCommonData const void *    data,
UErrorCode   err
 

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 void * U_IMPORT ENTRY_POINT_NAME; // ENTRY_POINT_NAME 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_ERROR [non-failing] will be returned. Be careful of UnicodeStrings in static initialization which may attempt to load a converter (use the UNICODE_STRING(x) macro instead).

This function has no effect on application (non ICU) data. See udata_setAppData() for similar functionality for application data.

Parameters:
data  pointer to ICU common data
err  outgoing error status U_USING_DEFAULT_ERROR, U_UNSUPPORTED_ERROR @stable


Generated on Sun Mar 3 16:06:56 2002 for ICU 2.0 by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002