Implement advisory locking for WIM overwrites

[wimlib] / src / wimlib.h

diff --git a/src/wimlib.h b/src/wimlib.h
index 0dd705c7e038449e338ac4f136237b92f447ed0f..0b0f04bf6b045acea1a988f154cfbecf072ee144 100644 (file)
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -211,6 +211,10 @@
 #include <stdbool.h>
 #include <inttypes.h>
 
 #include <stdbool.h>
 #include <inttypes.h>
 

+#define WIMLIB_MAJOR_VERSION 1
+#define WIMLIB_MINOR_VERSION 2
+#define WIMLIB_PATCH_VERSION 0
+

 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
  * and need not correspond to a specific on-disk file.  However, a ::WIMStruct
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
  * and need not correspond to a specific on-disk file.  However, a ::WIMStruct


@@ -263,6 +267,11 @@ enum wimlib_progress_msg {
         * info will point to ::wimlib_progress_info.extract. */
        WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
 
         * info will point to ::wimlib_progress_info.extract. */
        WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
 

+       /** A file or directory is being extracted.  @a info will point to
+        * ::wimlib_progress_info.extract, and the @a cur_path member will be
+        * valid. */
+       WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY,
+

        /** All the WIM files and directories have been extracted, and
         * timestamps are about to be applied.  @a info will point to
         * ::wimlib_progress_info.extract. */
        /** All the WIM files and directories have been extracted, and
         * timestamps are about to be applied.  @a info will point to
         * ::wimlib_progress_info.extract. */


@@ -277,6 +286,12 @@ enum wimlib_progress_msg {
         * ::wimlib_progress_info.scan. */
        WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
 
         * ::wimlib_progress_info.scan. */
        WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
 

+       /** A directory or file is being scanned.  @a info will point to
+        * ::wimlib_progress_info.scan, and its @a cur_path member will be
+        * valid.  This message is only sent if ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE
+        * is passed to wimlib_add_image(). */
+       WIMLIB_PROGRESS_MSG_SCAN_DENTRY,
+

        /** The directory or NTFS volume has been successfully scanned, and a
         * tree of WIM dentries has been built in-memory. @a info will point to
         * ::wimlib_progress_info.scan. */
        /** The directory or NTFS volume has been successfully scanned, and a
         * tree of WIM dentries has been built in-memory. @a info will point to
         * ::wimlib_progress_info.scan. */


@@ -375,6 +390,15 @@ union wimlib_progress_info {
        struct wimlib_progress_info_scan {
                /** Directory or NTFS volume that is being scanned. */
                const char *source;
        struct wimlib_progress_info_scan {
                /** Directory or NTFS volume that is being scanned. */
                const char *source;

+
+               /** Path to the file or directory that is about to be scanned,
+                * relative to the root of the image capture or the NTFS volume.
+                * */
+               const char *cur_path;
+
+               /** True iff @a cur_path is being excluded from the image
+                * capture due to the capture configuration file. */
+               bool excluded;

        } scan;
 
        /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
        } scan;
 
        /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,


@@ -393,6 +417,10 @@ union wimlib_progress_info {
                 * extracted. */
                const char *target;
 
                 * extracted. */
                const char *target;
 

+               /** Current dentry being extracted.  (Valid only if message is
+                * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY.) */
+               const char *cur_path;
+

                /** Number of bytes of uncompressed data that will be extracted.
                 * Takes into account hard links (they are not counted for each
                 * link.)
                /** Number of bytes of uncompressed data that will be extracted.
                 * Takes into account hard links (they are not counted for each
                 * link.)


@@ -506,6 +534,7 @@ union wimlib_progress_info {
 typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
                                      const union wimlib_progress_info *info);
 
 typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
                                      const union wimlib_progress_info *info);
 

+

 /*****************************
  * WIMLIB_ADD_IMAGE_FLAG_*   *
  *****************************/
 /*****************************
  * WIMLIB_ADD_IMAGE_FLAG_*   *
  *****************************/


@@ -517,8 +546,9 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * with ::WIMLIB_ADD_IMAGE_FLAG_NTFS. */
 #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE              0x00000002
 
  * with ::WIMLIB_ADD_IMAGE_FLAG_NTFS. */
 #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE              0x00000002
 

-/** Print the name of each file or directory as it is scanned to be included in
- * the WIM image. */
+/** Call the progress function with the message
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to
+ * be scanned. */

 #define WIMLIB_ADD_IMAGE_FLAG_VERBOSE                  0x00000004
 
 /** Mark the image being added as the bootable image of the WIM. */
 #define WIMLIB_ADD_IMAGE_FLAG_VERBOSE                  0x00000004
 
 /** Mark the image being added as the bootable image of the WIM. */


@@ -547,8 +577,10 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * together.  Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
 #define WIMLIB_EXTRACT_FLAG_SYMLINK                    0x00000004
 
  * together.  Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
 #define WIMLIB_EXTRACT_FLAG_SYMLINK                    0x00000004
 

-/** Print the name of each file or directory as it is extracted from the WIM
- * image. */
+/** Call the progress function with the argument
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY each time a file or directory is
+ * extracted.  Note: these calls will be interspersed with calls for the message
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. */

 #define WIMLIB_EXTRACT_FLAG_VERBOSE                    0x00000008
 
 /** Read the WIM file sequentially while extracting the image. */
 #define WIMLIB_EXTRACT_FLAG_VERBOSE                    0x00000008
 
 /** Read the WIM file sequentially while extracting the image. */


@@ -635,6 +667,7 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  */
 enum wimlib_error_code {
        WIMLIB_ERR_SUCCESS = 0,
  */
 enum wimlib_error_code {
        WIMLIB_ERR_SUCCESS = 0,

+       WIMLIB_ERR_ALREADY_LOCKED,

        WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
        WIMLIB_ERR_DECOMPRESSION,
        WIMLIB_ERR_DELETE_STAGING_DIR,
        WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
        WIMLIB_ERR_DECOMPRESSION,
        WIMLIB_ERR_DELETE_STAGING_DIR,


@@ -1543,6 +1576,11 @@ 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:
  *
  * @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.

  * @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().
  * @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().


@@ -1712,8 +1750,8 @@ extern void wimlib_print_wim_information(const WIMStruct *wim);
  *     image, indexed starting at 1, is returned.  If the keyword "all" or "*"
  *     was specified, ::WIMLIB_ALL_IMAGES is returned.  Otherwise,
  *     ::WIMLIB_NO_IMAGE is returned.  If @a image_name_or_num was @c NULL or
  *     image, indexed starting at 1, is returned.  If the keyword "all" or "*"
  *     was specified, ::WIMLIB_ALL_IMAGES is returned.  Otherwise,
  *     ::WIMLIB_NO_IMAGE is returned.  If @a image_name_or_num was @c NULL or

- *     the empty string, ::WIM_NO_IMAGE is returned, even if one or more images
- *     in @a wim has no name.
+ *     the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more
+ *     images in @a wim has no name.

  */
 extern int wimlib_resolve_image(WIMStruct *wim, const char *image_name_or_num);
 
  */
 extern int wimlib_resolve_image(WIMStruct *wim, const char *image_name_or_num);