Use tchar for error file path

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index 23c53ad68bf2affac160ab0dcf995d774c798a32..ea85cd0cfcb74a266a8c2c2b234e8f3445d091da 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -31,7 +31,7 @@
 /**
  * @mainpage
  *
- * This is the documentation for the library interface of wimlib 1.7.0, a C
+ * This is the documentation for the library interface of wimlib 1.7.1, 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
@@ -383,7 +383,7 @@
 #define WIMLIB_MINOR_VERSION 7
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
 
 #ifdef __cplusplus
 extern "C" {
@@ -620,6 +620,12 @@ enum wimlib_progress_msg {
        /** Starting to unmount a WIM image.  @p info will point to
         * ::wimlib_progress_info.unmount.  */
        WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25,
+
+       /** wimlib has used a file's data for the last time (including all data
+        * streams, if it has multiple).  @p info will point to
+        * ::wimlib_progress_info.done_with_file.  This message is only received
+        * if ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided.  */
+       WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26,
 };
 
 /** Valid return values from user-provided progress functions
@@ -889,10 +895,11 @@ union wimlib_progress_info {
                 * potentially multiple streams per file (named data streams).
                 * A "stream" may be the default contents of a file, a named
                 * data stream, or a reparse data buffer.  */
-               uint64_t num_streams;
+               uint64_t total_streams;
 
-               /** Reserved.  */
-               const wimlib_tchar *reserved_2;
+               /** Number of (not necessarily unique) streams that have been
+                * extracted so far.  */
+               uint64_t completed_streams;
 
                /** Currently only used for
                 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN.  */
@@ -1024,6 +1031,28 @@ union wimlib_progress_info {
                /** Flags passed to wimlib_unmount_image().  */
                uint32_t unmount_flags;
        } unmount;
+
+       /** Valid on messages ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE.  */
+       struct wimlib_progress_info_done_with_file {
+               /* Path to the file whose data has been written to the WIM file,
+                * or is currently being asynchronously compressed in memory,
+                * and therefore is no longer needed by wimlib.
+                *
+                * WARNING: The file data will not actually be accessible in the
+                * WIM file until the WIM file has been completely written.
+                * Ordinarily you should <b>not</b> treat this message as a
+                * green light to go ahead and delete the specified file, since
+                * that would result in data loss if the WIM file cannot be
+                * successfully created for any reason.
+                *
+                * If a file has multiple names (hard links),
+                * ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE will only be received
+                * for one name.  Also, this message will not be received for
+                * empty files or reparse points (or symbolic links), unless
+                * they have nonempty named data streams.
+                */
+               const wimlib_tchar *path_to_file;
+       } done_with_file;
 };
 
 /**
@@ -1936,6 +1965,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_WRITE_FLAG_PACK_STREAMS                 0x00001000
 
+/**
+ * Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM
+ * file.  This is only needed in the unusual case that the library user needs to
+ * know exactly when wimlib has read each file for the last time.
+ */
+#define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000
+
 /** @} */
 /** @addtogroup G_general
  * @{ */
@@ -3625,6 +3661,39 @@ extern int
 wimlib_resolve_image(WIMStruct *wim,
                     const wimlib_tchar *image_name_or_num);
 
+/**
+ * Sets the file to which the library will print error and warning messages.
+ *
+ * This version of the function takes a C library <c>FILE *</c> opened for
+ * writing (or appending).  Use wimlib_set_error_file_by_name() to specify the
+ * file by name instead.
+ *
+ * This also enables error messages, as if by a call to
+ * wimlib_set_print_errors(true).
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
+ *     wimlib was compiled using the <c>--without-error-messages</c> option.
+ */
+extern int
+wimlib_set_error_file(FILE *fp);
+
+/**
+ * Sets the path to the file to which the library will print error and warning
+ * messages.  The library will open this file for appending.
+ *
+ * This also enables error messages, as if by a call to
+ * wimlib_set_print_errors(true).
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_OPEN
+ *     The file named by @p path could not be opened for appending.
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
+ *     wimlib was compiled using the <c>--without-error-messages</c> option.
+ */
+extern int
+wimlib_set_error_file_by_name(const wimlib_tchar *path);
+
 /**
  * @ingroup G_modifying_wims
  *