ICU-551.30.tar.gz

[apple/icu.git] / icuSources / common / unicode / udata.h

diff --git a/icuSources/common/unicode/udata.h b/icuSources/common/unicode/udata.h
index 84046d5f9cd0325f55c6287614d1d4aa846b4bf2..29e46630d5398d82738d1d61ffc4d2c914e8c68b 100644 (file)
--- a/icuSources/common/unicode/udata.h
+++ b/icuSources/common/unicode/udata.h
@@ -1,7 +1,7 @@
 /*
 ******************************************************************************
 *
 /*
 ******************************************************************************
 *

-*   Copyright (C) 1999-2008, International Business Machines
+*   Copyright (C) 1999-2014, International Business Machines

 *   Corporation and others.  All Rights Reserved.
 *
 ******************************************************************************
 *   Corporation and others.  All Rights Reserved.
 *
 ******************************************************************************


@@ -18,6 +18,7 @@
 #define __UDATA_H__
 
 #include "unicode/utypes.h"
 #define __UDATA_H__
 
 #include "unicode/utypes.h"

+#include "unicode/localpointer.h"

 
 U_CDECL_BEGIN
 
 
 U_CDECL_BEGIN
 


@@ -76,6 +77,10 @@ U_CDECL_BEGIN
  * <p>This structure may grow in the future, indicated by the
  * <code>size</code> field.</p>
  *
  * <p>This structure may grow in the future, indicated by the
  * <code>size</code> field.</p>
  *

+ * <p>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.
+ *

  * <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
  * <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


@@ -91,7 +96,7 @@ U_CDECL_BEGIN
  *
  * <p>The <code>formatVersion</code> field should be used to
  * make sure that the format can be interpreted.
  *
  * <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
+ * 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.</p>
  * 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>


@@ -100,6 +105,7 @@ U_CDECL_BEGIN
  * common place to store the source version of the data;
  * for data from the Unicode character database, this could
  * reflect the Unicode version.</p>
  * 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 {
  * @stable ICU 2.0
  */
 typedef struct {


@@ -256,9 +262,31 @@ udata_openChoice(const char *path, const char *type, const char *name,
 U_STABLE void U_EXPORT2
 udata_close(UDataMemory *pData);
 
 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.
 /**
  * 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
  */
  * @param pData The pointer to data memory object
  * @stable ICU 2.0
  */


@@ -291,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.
  *
  * 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
  * 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


@@ -298,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:
  *
  * 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);
  *
  *        // 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*.
  *
  * 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.
  *
  * This function has no effect on application (non ICU) data.  See udata_setAppData()
  * for similar functionality for application data.
  *


@@ -319,7 +357,6 @@ udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);
  * @param err outgoing error status <code>U_USING_DEFAULT_WARNING, U_UNSUPPORTED_ERROR</code>
  * @stable ICU 2.0
  */
  * @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);
 
 U_STABLE void U_EXPORT2
 udata_setCommonData(const void *data, UErrorCode *err);
 


@@ -329,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.
  *
  * 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
  * 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


@@ -357,24 +397,25 @@ udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
  * @stable ICU 3.4
  */
 typedef enum UDataFileAccess {
  * @stable ICU 3.4
  */
 typedef enum UDataFileAccess {

-    /** ICU looks for data in single files first, then in packages. (default) */
+    /** ICU looks for data in single files first, then in packages. (default) @stable ICU 3.4 */

     UDATA_FILES_FIRST,
     UDATA_FILES_FIRST,

-    /** ICU only loads data from packages, not from single files. */
+    /** 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
     UDATA_ONLY_PACKAGES,
     /** ICU loads data from packages first, and only from single files

-        if the data cannot be found in a package. */
+        if the data cannot be found in a package. @stable ICU 3.4 */

     UDATA_PACKAGES_FIRST,
     UDATA_PACKAGES_FIRST,

-    /** ICU does not access the file system for data loading. */
+    /** ICU does not access the file system for data loading. @stable ICU 3.4 */

     UDATA_NO_FILES,
     UDATA_NO_FILES,

-    /** An alias for the default access mode. */
-    UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
+    /** 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
     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.  
+ * 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.
  * 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.