This structure may grow in the future, indicated by the
* size field.
ICU data must be at least 8-aligned, and should be 16-aligned. + * The UDataInfo struct begins 4 bytes after the start of the data item, + * so it is 4-aligned. + * *
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 @@ -58,7 +96,7 @@ U_CDECL_BEGIN * *
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
+ * It 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.
For details about ICU data loading see the User Guide - * Data Management chapter. (http://oss.software.ibm.com/icu/userguide/icudata.html)
+ * Data Management chapter. (http://icu-project.org/userguide/icudata.html) * * @param path Specifies an absolute path and/or a basename for the * finding of the data in the file system. @@ -208,7 +247,7 @@ udata_open(const char *path, const char *type, const char *name, * to get a pointer to the actual data. * @stable ICU 2.0 */ -U_CAPI UDataMemory * U_EXPORT2 +U_STABLE UDataMemory * U_EXPORT2 udata_openChoice(const char *path, const char *type, const char *name, UDataMemoryIsAcceptable *isAcceptable, void *context, UErrorCode *pErrorCode); @@ -220,16 +259,38 @@ udata_openChoice(const char *path, const char *type, const char *name, * @param pData The pointer to data memory object * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 udata_close(UDataMemory *pData); +#if U_SHOW_CPLUSPLUS_API + +U_NAMESPACE_BEGIN + +/** + * \class LocalUDataMemoryPointer + * "Smart pointer" class, closes a UDataMemory via udata_close(). + * For most methods see the LocalPointerBase base class. + * + * @see LocalPointerBase + * @see LocalPointer + * @stable ICU 4.4 + */ +U_DEFINE_LOCAL_OPEN_POINTER(LocalUDataMemoryPointer, UDataMemory, udata_close); + +U_NAMESPACE_END + +#endif + /** * 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. + * * @param pData The pointer to data memory object * @stable ICU 2.0 */ -U_CAPI const void * U_EXPORT2 +U_STABLE const void * U_EXPORT2 udata_getMemory(UDataMemory *pData); /** @@ -250,7 +311,7 @@ udata_getMemory(UDataMemory *pData); * adjusted and only part of the structure will be filled. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 udata_getInfo(UDataMemory *pData, UDataInfo *pInfo); /** @@ -258,6 +319,9 @@ udata_getInfo(UDataMemory *pData, UDataInfo *pInfo); * 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 http://userguide.icu-project.org/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 @@ -265,20 +329,27 @@ udata_getInfo(UDataMemory *pData, UDataInfo *pInfo); * 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 []; + * 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 + * 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. * @@ -286,8 +357,7 @@ udata_getInfo(UDataMemory *pData, UDataInfo *pInfo); * @param err outgoing error statusU_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR
* @stable ICU 2.0
*/
-
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
udata_setCommonData(const void *data, UErrorCode *err);
@@ -296,6 +366,9 @@ udata_setCommonData(const void *data, UErrorCode *err);
* 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 http://userguide.icu-project.org/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
@@ -315,9 +388,43 @@ udata_setCommonData(const void *data, UErrorCode *err);
* @see udata_setCommonData
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
+/**
+ * Possible settings for udata_setFileAccess()
+ * @see udata_setFileAccess
+ * @stable ICU 3.4
+ */
+typedef enum UDataFileAccess {
+ /** ICU looks for data in single files first, then in packages. (default) @stable ICU 3.4 */
+ UDATA_FILES_FIRST,
+ /** An alias for the default access mode. @stable ICU 3.4 */
+ UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
+ /** ICU only loads data from packages, not from single files. @stable ICU 3.4 */
+ UDATA_ONLY_PACKAGES,
+ /** 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_PACKAGES_FIRST,
+ /** ICU does not access the file system for data loading. @stable ICU 3.4 */
+ UDATA_NO_FILES,
+ /** Number of real UDataFileAccess values. @stable ICU 3.4 */
+ 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. 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
+ * @stable ICU 3.4
+ */
+U_STABLE void U_EXPORT2
+udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
+
U_CDECL_END
#endif