wimlib_iterate_dir_tree(): iterate in default case order

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index 59e4fb6852487223b53287a272a8411e3710849f..393787d1a67f51b1bd5f652a04de8cbd7b0d6983 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -12,7 +12,7 @@
 /**
  * @mainpage
  *
- * This is the documentation for the library interface of wimlib 1.7.2, a C
+ * This is the documentation for the library interface of wimlib 1.7.4, a C
  * library for creating, modifying, extracting, and mounting files in the
  * Windows Imaging Format.  This documentation is intended for developers only.
  * If you have installed wimlib and want to know how to use the @b wimlib-imagex
@@ -379,7 +379,7 @@
 #define WIMLIB_MINOR_VERSION 7
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 4
 
 #ifdef __cplusplus
 extern "C" {
@@ -474,7 +474,7 @@ enum wimlib_compression_type {
         *
         * If using wimlib_create_compressor() to create an XPRESS compressor
         * directly, the @p max_block_size parameter may be any positive value
-        * up to <c>2^16</c>.
+        * up to and including <c>2^16</c>.
         */
        WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
 
@@ -496,7 +496,7 @@ enum wimlib_compression_type {
         *
         * If using wimlib_create_compressor() to create an LZX compressor
         * directly, the @p max_block_size parameter may be any positive value
-        * up to <c>2^21</c>.
+        * up to and including <c>2^21</c>.
         */
        WIMLIB_COMPRESSION_TYPE_LZX = 2,
 
@@ -517,7 +517,7 @@ enum wimlib_compression_type {
         *
         * If using wimlib_create_compressor() to create an LZMS compressor
         * directly, the @p max_block_size parameter may be any positive value
-        * up to <c>2^31 - 2</c>.
+        * up to and including <c>1180427429</c>.
         */
        WIMLIB_COMPRESSION_TYPE_LZMS = 3,
 };
@@ -708,6 +708,28 @@ enum wimlib_progress_msg {
         * mechanism.
         */
        WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION = 30,
+
+       /**
+        * An error has occurred and the progress function is being asked
+        * whether to ignore the error or not.  @p info will point to
+        * ::wimlib_progress_info.handle_error.  This is a bidirectional
+        * message.
+        *
+        * This message provides a limited capability for applications to
+        * recover from "unexpected" errors (i.e. those with no in-library
+        * handling policy) arising from the underlying operating system.
+        * Normally, any such error will cause the library to abort the current
+        * operation.  By implementing a handler for this message, the
+        * application can instead choose to ignore a given error.
+        *
+        * Currently, only the following types of errors will result in this
+        * progress message being sent:
+        *
+        *      - Directory tree scan errors, e.g. from wimlib_add_image()
+        *      - Most extraction errors; currently restricted to the Windows
+        *        build of the library only.
+        */
+       WIMLIB_PROGRESS_MSG_HANDLE_ERROR = 31,
 };
 
 /** Valid return values from user-provided progress functions
@@ -1204,6 +1226,24 @@ union wimlib_progress_info {
                 */
                bool will_exclude;
        } test_file_exclusion;
+
+       /** Valid on messages ::WIMLIB_PROGRESS_MSG_HANDLE_ERROR.  */
+       struct wimlib_progress_info_handle_error {
+
+               /** Path to the file for which the error occurred, or NULL if
+                * not relevant.  */
+               const wimlib_tchar *path;
+
+               /** The wimlib error code associated with the error.  */
+               int error_code;
+
+               /**
+                * Indicates whether the error will be ignored or not.  This
+                * will be <tt>false</tt> by default; the progress function may
+                * set it to <tt>true</tt>.
+                */
+               bool will_ignore;
+       } handle_error;
 };
 
 /**
@@ -1724,8 +1764,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * Note: This method for file exclusions is independent from the capture
  * configuration file mechanism.
  */
-#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
+#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION    0x00004000
 
+/* Note: the WIMLIB_ADD_IMAGE_FLAG names are retained for source compatibility.
+ * Use the WIMLIB_ADD_FLAG names in new code.  */
 #define WIMLIB_ADD_IMAGE_FLAG_NTFS             WIMLIB_ADD_FLAG_NTFS
 #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE      WIMLIB_ADD_FLAG_DEREFERENCE
 #define WIMLIB_ADD_IMAGE_FLAG_VERBOSE          WIMLIB_ADD_FLAG_VERBOSE
@@ -3141,7 +3183,7 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
  * bits contain the patch version.
  *
  * In other words, the returned value is equal to <code>((WIMLIB_MAJOR_VERSION
- * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
+ * << 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
  * corresponding header file.
  */
 extern uint32_t