X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=38ffc02460786f294a72a591cdf0dd6f5d5ed71b;hp=529de43765e4d079fa90a67300c1b29ed338fca5;hb=5fd0e697fdbcbc860b92a65061dac9c8a7809a68;hpb=5b6eaafbaab217fc69946685862a09afa28b30cb
diff --git a/include/wimlib.h b/include/wimlib.h
index 529de437..38ffc024 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -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 false by default; the progress function may
+ * set it to true.
+ */
+ bool will_ignore;
+ } handle_error;
};
/**
@@ -1248,14 +1288,15 @@ struct wimlib_capture_source {
long reserved;
};
-/** Set or unset the WIM header flag that marks it read-only
- * (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the
- * ::wimlib_wim_info.is_marked_readonly member of the @p info parameter. This
- * is distinct from basic file permissions; this flag can be set on a WIM file
- * that is physically writable. If this flag is set, all further operations to
- * modify the WIM will fail, except calling wimlib_overwrite() with
- * ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG specified, which is a loophole that
- * allows you to set this flag persistently on the underlying WIM file.
+/** Set or unset the "readonly" WIM header flag (WIM_HDR_FLAG_READONLY in
+ * Microsoft's documentation), based on the ::wimlib_wim_info.is_marked_readonly
+ * member of the @p info parameter. This is distinct from basic file
+ * permissions; this flag can be set on a WIM file that is physically writable.
+ *
+ * wimlib disallows modifying on-disk WIM files with the readonly flag set.
+ * However, wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG
+ * will override this --- and in fact, this is necessary to set the readonly
+ * flag persistently on an existing WIM file.
*/
#define WIMLIB_CHANGE_READONLY_FLAG 0x00000001
@@ -1723,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
@@ -1973,8 +2016,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* only if it is writable at the filesystem level, does not have the
* WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned
* set. It is not required to provide this flag before attempting to make
- * changes to the WIM, but with this flag you get an error sooner rather than
- * later. */
+ * changes to the WIM, but with this flag you get an error immediately rather
+ * than potentially much later, when wimlib_overwrite() is finally called. */
#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
/** @} */
@@ -2468,10 +2511,6 @@ enum wimlib_error_code {
* There is already an image in @p wim named @p name.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to add the new image.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*/
extern int
wimlib_add_empty_image(WIMStruct *wim,
@@ -2634,10 +2673,6 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
*
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not exist in the WIM and is not ::WIMLIB_ALL_IMAGES.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
@@ -2728,10 +2763,6 @@ wimlib_delete_path(WIMStruct *wim, int image,
* WIM parts were not referenced with wimlib_reference_resources() or
* wimlib_reference_resource_files() before the call to
* wimlib_export_image().
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p dest_wim is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
@@ -3962,9 +3993,6 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path);
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @p description
* string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p wim is considered read-only because of any of the reasons mentioned
- * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_descripton(WIMStruct *wim, int image,
@@ -4056,12 +4084,6 @@ wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
* ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG.
*
* @return 0 on success; nonzero on failure.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag. However, as a special case, if you are using
- * ::WIMLIB_CHANGE_READONLY_FLAG to unset the readonly flag, then this
- * function will not fail due to the readonly flag being previously set.
* @retval ::WIMLIB_ERR_IMAGE_COUNT
* ::WIMLIB_CHANGE_BOOT_INDEX was specified, but
* ::wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image
@@ -4090,9 +4112,6 @@ wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info,
* @p image does not specify a single existing image in @p wim.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @p flags string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p wim is considered read-only because of any of the reasons mentioned
- * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
@@ -4118,9 +4137,6 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
* @p image does not specify a single existing image in @p wim.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @p name string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p wim is considered read-only because of any of the reasons mentioned
- * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
@@ -4405,10 +4421,6 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
* a supported file type (e.g. a device file). Only if
* ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the add_flags
* for an update command.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,