Improve progress messages for NTFS apply

[wimlib] / src / wimlib.h

diff --git a/src/wimlib.h b/src/wimlib.h
index 0b0f04bf6b045acea1a988f154cfbecf072ee144..c81b42f49f576eaa9244765558e7dde8314cfeb0 100644 (file)
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -31,6 +31,10 @@
  *
  * \section intro Introduction
  *
+ * This is the documentation for the library interface of wimlib 1.2.0.  If you
+ * have installed wimlib and want to know how to use the @c imagex program,
+ * please see the man pages instead.
+ *
  * wimlib is a C library to read, write, and mount archive files in the Windows
  * Imaging Format (WIM files).  These files are normally created using the @c
  * imagex.exe utility on Windows, but this library provides a free
@@ -297,17 +301,17 @@ enum wimlib_progress_msg {
         * ::wimlib_progress_info.scan. */
        WIMLIB_PROGRESS_MSG_SCAN_END,
 
-       /** 
+       /**
         * File resources are currently being written to the WIM.
         * @a info will point to ::wimlib_progress_info.write_streams. */
        WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
 
-       /** 
+       /**
         * The metadata resource for each image is about to be written to the
         * WIM. @a info will not be valid. */
        WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
 
-       /** 
+       /**
         * The metadata resource for each image has successfully been writen to
         * the WIM.  @a info will not be valid. */
        WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
@@ -410,6 +414,12 @@ union wimlib_progress_info {
                /** Number of the image being extracted (1-based). */
                int image;
 
+               /** Flags passed to to wimlib_extract_image() */
+               int extract_flags;
+
+               /** Full path to the WIM file being extracted. */
+               const char *wimfile_name;
+
                /** Name of the image being extracted. */
                const char *image_name;
 
@@ -1395,10 +1405,17 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
  *     This number should be one less than the total number of parts in the
  *     split WIM.  Set to 0 if the WIM is a standalone WIM.
  * @param staging_dir
- *     Currently ignored, but may provide a way to specify the staging
- *     directory in the future.  Set to @c NULL.
+ *     If non-NULL, the name of a directory in which the staging directory will
+ *     be created.  Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified
+ *     in @a mount_flags.  If left @c NULL, the staging directory is created in
+ *     the same directory as the WIM file that @a wim was originally read from.
  *
  * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_ALREADY_LOCKED
+ *     A read-write mount was requested, but an an exclusive advisory lock on
+ *     the on-disk WIM file could not be acquired because another thread or
+ *     process has mounted an image from the WIM read-write or is currently
+ *     modifying the WIM in-place.
  * @retval ::WIMLIB_ERR_DECOMPRESSION
  *     Could not decompress the metadata resource for @a image in @a wim.
  * @retval ::WIMLIB_ERR_FUSE
@@ -1577,10 +1594,10 @@ extern int wimlib_open_wim(const char *wim_file, int open_flags,
  * @return 0 on success; nonzero on error.  This function may return any value
  * returned by wimlib_write() as well as the following error codes:
  * @retval ::WIMLIB_ERR_ALREADY_LOCKED
- *     The append-only overwrite mode was going to be used, but an exclusive
- *     advisory lock on the on-disk WIM file could not be acquired, probably
- *     because another thread or process was calling wimlib_overwrite() on the
- *     same underlying on-disk file at the same time.
+ *     The WIM was going to be modifien in-place (with no temporary file), but
+ *     an exclusive advisory lock on the on-disk WIM file could not be acquired
+ *     because another thread or process has mounted an image from the WIM
+ *     read-write or is currently modifying the WIM in-place.
  * @retval ::WIMLIB_ERR_NO_FILENAME
  *     @a wim corresponds to a WIM created with wimlib_create_new_wim() rather
  *     than a WIM read with wimlib_open_wim().