ICU 72.1 72.1
Data Structures | Namespaces | Macros | Typedefs | Enumerations | Functions
udata.h File Reference

C API: Data loading interface. More...

#include "unicode/utypes.h"
#include "unicode/localpointer.h"

Go to the source code of this file.

Data Structures

struct  UDataInfo
 UDataInfo contains the properties about the requested data. More...
 

Namespaces

namespace  icu
 File coll.h.
 

Macros

#define U_TREE_SEPARATOR   '-'
 Character used to separate package names from tree names. More...
 
#define U_TREE_SEPARATOR_STRING   "-"
 String used to separate package names from tree names. More...
 
#define U_TREE_ENTRY_SEP_CHAR   '/'
 Character used to separate parts of entry names. More...
 
#define U_TREE_ENTRY_SEP_STRING   "/"
 String used to separate parts of entry names. More...
 
#define U_ICUDATA_ALIAS   "ICUDATA"
 Alias for standard ICU data. More...
 

Typedefs

typedef struct 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...
 
typedef enum UDataFileAccess UDataFileAccess
 Possible settings for udata_setFileAccess() More...
 

Enumerations

enum  UDataFileAccess {
  UDATA_FILES_FIRST , UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST , UDATA_ONLY_PACKAGES , UDATA_PACKAGES_FIRST ,
  UDATA_NO_FILES , UDATA_FILE_ACCESS_COUNT
}
 Possible settings for udata_setFileAccess() More...
 

Functions

U_CAPI UDataMemoryudata_open (const char *path, const char *type, const char *name, UErrorCode *pErrorCode)
 Convenience function. More...
 
U_CAPI UDataMemoryudata_openChoice (const char *path, const char *type, const char *name, UDataMemoryIsAcceptable *isAcceptable, void *context, UErrorCode *pErrorCode)
 Data loading function. More...
 
U_CAPI void udata_close (UDataMemory *pData)
 Close the data memory. More...
 
U_CAPI const void * udata_getMemory (UDataMemory *pData)
 Get the pointer to the actual data inside the data memory. More...
 
U_CAPI void udata_getInfo (UDataMemory *pData, UDataInfo *pInfo)
 Get the information from the data memory header. More...
 
U_CAPI void 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 udata_setAppData (const char *packageName, 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...
 
U_CAPI void udata_setFileAccess (UDataFileAccess access, UErrorCode *status)
 This function may be called to control how ICU loads data. More...
 

Detailed Description

C API: Data loading interface.

Information about data loading interface

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.

Definition in file udata.h.

Macro Definition Documentation

◆ U_ICUDATA_ALIAS

#define U_ICUDATA_ALIAS   "ICUDATA"

Alias for standard ICU data.

Internal:
Do not use. This API is for internal use only. ICU 3.0

Definition at line 74 of file udata.h.

◆ U_TREE_ENTRY_SEP_CHAR

#define U_TREE_ENTRY_SEP_CHAR   '/'

Character used to separate parts of entry names.

Internal:
Do not use. This API is for internal use only. ICU 3.0

Definition at line 62 of file udata.h.

◆ U_TREE_ENTRY_SEP_STRING

#define U_TREE_ENTRY_SEP_STRING   "/"

String used to separate parts of entry names.

Internal:
Do not use. This API is for internal use only. ICU 3.0

Definition at line 68 of file udata.h.

◆ U_TREE_SEPARATOR

#define U_TREE_SEPARATOR   '-'

Character used to separate package names from tree names.

Internal:
Do not use. This API is for internal use only. ICU 3.0

Definition at line 50 of file udata.h.

◆ U_TREE_SEPARATOR_STRING

#define U_TREE_SEPARATOR_STRING   "-"

String used to separate package names from tree names.

Internal:
Do not use. This API is for internal use only. ICU 3.0

Definition at line 56 of file udata.h.

Typedef Documentation

◆ UDataFileAccess

Possible settings for udata_setFileAccess()

See also
udata_setFileAccess
Stable:
ICU 3.4

◆ UDataMemory

typedef struct UDataMemory UDataMemory

Forward declaration of the data memory type.

Stable:
ICU 2.0

Definition at line 161 of file udata.h.

◆ UDataMemoryIsAcceptable

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

Callback function for udata_openChoice().

Parameters
contextparameter passed into udata_openChoice().
typeThe type of the data as passed into udata_openChoice(). It may be NULL.
nameThe name of the data as passed into udata_openChoice().
pInfoA 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:
ICU 2.0

Definition at line 177 of file udata.h.

Enumeration Type Documentation

◆ UDataFileAccess

Possible settings for udata_setFileAccess()

See also
udata_setFileAccess
Stable:
ICU 3.4
Enumerator
UDATA_FILES_FIRST 

ICU looks for data in single files first, then in packages.

(default)

Stable:
ICU 3.4
UDATA_DEFAULT_ACCESS 

An alias for the default access mode.

Stable:
ICU 3.4
UDATA_ONLY_PACKAGES 

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

Stable:
ICU 3.4
UDATA_PACKAGES_FIRST 

ICU loads data from packages first, and only from single files if the data cannot be found in a package.

Stable:
ICU 3.4
UDATA_NO_FILES 

ICU does not access the file system for data loading.

Stable:
ICU 3.4
UDATA_FILE_ACCESS_COUNT 

Number of real UDataFileAccess values.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 385 of file udata.h.

Function Documentation

◆ udata_close()

U_CAPI void 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.

Parameters
pDataThe pointer to data memory object
Stable:
ICU 2.0

◆ udata_getInfo()

U_CAPI void 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
pDatapointer to the data memory object
pInfopointer 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:
ICU 2.0

◆ udata_getMemory()

U_CAPI const void * udata_getMemory ( UDataMemory pData)

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

The data is read-only.

ICU data must be at least 8-aligned, and should be 16-aligned.

Parameters
pDataThe pointer to data memory object
Stable:
ICU 2.0

◆ udata_open()

U_CAPI UDataMemory * 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.

Parameters
pathSpecifies an absolute path and/or a basename for the finding of the data in the file system. NULL for ICU data.
typeA 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.
nameA string that specifies the name of the data.
pErrorCodeAn 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.
See also
udata_openChoice
Stable:
ICU 2.0

◆ udata_openChoice()

U_CAPI UDataMemory * 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 directory string. The basename is used as the data package name, and the directory is logically prepended to the ICU data directory string.

For details about ICU data loading see the User Guide Data Management chapter. (https://unicode-org.github.io/icu/userguide/icu_data/)

Parameters
pathSpecifies an absolute path and/or a basename for the finding of the data in the file system. NULL for ICU data.
typeA 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.
nameA string that specifies the name of the data.
isAcceptableThis 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.
contextArbitrary parameter to be passed into isAcceptable.
pErrorCodeAn 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:
ICU 2.0

◆ udata_setAppData()

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

ICU data must be at least 8-aligned, and should be 16-aligned. See https://unicode-org.github.io/icu/userguide/icudata

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 specified 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
packageNamethe package name by which the application will refer to (open) this data
datapointer to the data
erroutgoing error status U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR
See also
udata_setCommonData
Stable:
ICU 2.0

◆ udata_setCommonData()

U_CAPI void 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.

ICU data must be at least 8-aligned, and should be 16-aligned. See https://unicode-org.github.io/icu/userguide/icudata

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

It is important that the declaration be as above. The entry point must not be declared as an extern void*.

Starting with ICU 4.4, it is possible to set several data packages, one per call to this function. udata_open() will look for data in the multiple data packages in the order in which they were set. The position of the linked-in or default-name ICU .data package in the search list depends on when the first data item is loaded that is not contained in the already explicitly set packages. If data was loaded implicitly before the first call to this function (for example, via opening a converter, constructing a UnicodeString from default-codepage data, using formatting or collation APIs, etc.), then the default data will be first in the list.

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

Parameters
datapointer to ICU common data
erroutgoing error status U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR
Stable:
ICU 2.0

◆ udata_setFileAccess()

U_CAPI void udata_setFileAccess ( UDataFileAccess  access,
UErrorCode status 
)

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. This function is not multithread safe.
The results of calling it while other threads are loading data are undefined.

Parameters
accessThe type of file access to be used
statusError code.
See also
UDataFileAccess
Stable:
ICU 3.4