X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=6a1fbde6df13394577a98db27e56f78d5dc3119f;hb=e2fb429bf5041bcf5cde3f523bb7f2543586c0f9;hp=10f9bb7eb36dee1ebed7284849d715c7d3666c9b;hpb=f249ba1f7198e491c8e0b794a748095cdd1278a7;p=wimlib

diff --git a/include/wimlib.h b/include/wimlib.h
index 10f9bb7e..6a1fbde6 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -11,7 +11,7 @@
 /**
  * @mainpage
  *
- * This is the documentation for the library interface of wimlib 1.8.3, a C
+ * This is the documentation for the library interface of wimlib 1.9.0, 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
@@ -377,10 +377,10 @@
 #define WIMLIB_MAJOR_VERSION 1
 
 /** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 8
+#define WIMLIB_MINOR_VERSION 9
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 3
+#define WIMLIB_PATCH_VERSION 0
 
 #ifdef __cplusplus
 extern "C" {
@@ -856,13 +856,11 @@ union wimlib_progress_info {
 		uint64_t num_dirs_scanned;
 
 		/** The number of non-directories scanned so far, not counting
-		 * excluded/unsupported files.  If a file has multiple names
-		 * (hard links), it is only counted one time.  */
+		 * excluded/unsupported files.  */
 		uint64_t num_nondirs_scanned;
 
 		/** The number of bytes of file data detected so far, not
-		 * counting excluded/unsupported files.  If a file has multiple
-		 * names (hard links), its data is counted only one time.  */
+		 * counting excluded/unsupported files.  */
 		uint64_t num_bytes_scanned;
 	} scan;
 
@@ -1747,23 +1745,27 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #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
-#define WIMLIB_ADD_IMAGE_FLAG_BOOT		WIMLIB_ADD_FLAG_BOOT
-#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA		WIMLIB_ADD_FLAG_UNIX_DATA
-#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS		WIMLIB_ADD_FLAG_NO_ACLS
-#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS	WIMLIB_ADD_FLAG_STRICT_ACLS
-#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE	WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE
-#define WIMLIB_ADD_IMAGE_FLAG_RPFIX		WIMLIB_ADD_FLAG_RPFIX
-#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX		WIMLIB_ADD_FLAG_NORPFIX
-#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \
-						WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE
-#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG		WIMLIB_ADD_FLAG_WINCONFIG
-#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT		WIMLIB_ADD_FLAG_WIMBOOT
+/**
+ * Since wimlib v1.9.0: create a temporary filesystem snapshot of the source
+ * directory and add the files from it.  Currently, this option is only
+ * supported on Windows, where it uses the Volume Shadow Copy Service (VSS).
+ * Using this option, you can create a consistent backup of the system volume of
+ * a running Windows system without running into problems with locked files.
+ * For the VSS snapshot to be successfully created, your application must be run
+ * as an Administrator, and it cannot be run in WoW64 mode (i.e. if Windows is
+ * 64-bit, then your application must be 64-bit as well).
+ */
+#define WIMLIB_ADD_FLAG_SNAPSHOT		0x00008000
 
+/**
+ * Since wimlib v1.9.0: permit the library to discard file paths after the
+ * initial scan.  If the application won't use
+ * WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM archive,
+ * this flag can be used to allow the library to enable optimizations such as
+ * opening files by inode number rather than by path.  Currently this only makes
+ * a difference on Windows.
+ */
+#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED	0x00010000
 
 /** @} */
 /** @addtogroup G_modifying_wims
@@ -1904,9 +1906,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * only allows the Administrator to create symbolic links.  */
 #define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS             0x00008000
 
-/** Reserved for future use.  */
-#define WIMLIB_EXTRACT_FLAG_RESUME			0x00010000
-
 /** For wimlib_extract_paths() and wimlib_extract_pathlist() only:  Treat the
  * paths to extract as wildcard patterns ("globs") which may contain the
  * wildcard characters @c ? and @c *.  The @c ? character matches any
@@ -2245,12 +2244,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_WRITE_FLAG_SOLID				0x00001000
 
-/**
- * Deprecated: this is the old name for ::WIMLIB_WRITE_FLAG_SOLID, retained for
- * source compatibility.
- */
-#define WIMLIB_WRITE_FLAG_PACK_STREAMS			WIMLIB_WRITE_FLAG_SOLID
-
 /**
  * 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
@@ -2505,6 +2498,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES      = 86,
 	WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE           = 87,
 	WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED   = 88,
+	WIMLIB_ERR_SNAPSHOT_FAILURE                   = 89,
 };
 
 
@@ -3133,19 +3127,8 @@ wimlib_get_error_string(enum wimlib_error_code code);
 /**
  * @ingroup G_wim_information
  *
- * Get the description of the specified image.
- *
- * @param wim
- * 	Pointer to the ::WIMStruct to query.  This need not represent a
- * 	standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- * 	The 1-based index of the image for which to query the description.
- *
- * @return
- * 	The description of the image, or @c NULL if there is no such image, or
- * 	@c NULL if the specified image has no description.  The string may not
- * 	remain valid after later library calls, so the caller should duplicate
- * 	it if needed.
+ * Get the description of the specified image.  Equivalent to
+ * <tt>wimlib_get_image_property(wim, image, "DESCRIPTION")</tt>.
  */
 extern const wimlib_tchar *
 wimlib_get_image_description(const WIMStruct *wim, int image);
@@ -3153,18 +3136,10 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
 /**
  * @ingroup G_wim_information
  *
- * Get the name of the specified image.
- *
- * @param wim
- * 	Pointer to the ::WIMStruct to query.  This need not represent a
- * 	standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- * 	The 1-based index of the image for which to query the name.
- *
- * @return
- * 	The name of the image, or @c NULL if there is no such image, or an empty
- * 	string if the image is unnamed.  The string may not remain valid after
- * 	later library calls, so the caller should duplicate it if needed.
+ * Get the name of the specified image.  Equivalent to
+ * <tt>wimlib_get_image_property(wim, image, "NAME")</tt>, except that
+ * wimlib_get_image_name() will return an empty string if the image is unnamed
+ * whereas wimlib_get_image_property() may return @c NULL in that case.
  */
 extern const wimlib_tchar *
 wimlib_get_image_name(const WIMStruct *wim, int image);
@@ -3186,7 +3161,7 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
  *	"TOTALBYTES".  The name can contain forward slashes to indicate a nested
  *	XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD
  *	element nested within the VERSION element nested within the WINDOWS
- *	element.  Since wimlib v1.8.4, a bracketed number can be used to
+ *	element.  Since wimlib v1.9.0, a bracketed number can be used to
  *	indicate one of several identically-named elements; for example,
  *	"WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element
  *	nested within the "WINDOWS/LANGUAGES" element.  Note that element names
@@ -3967,20 +3942,8 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path);
 /**
  * @ingroup G_modifying_wims
  *
- * Change the description of a WIM image.
- *
- * @param wim
- * 	Pointer to the ::WIMStruct for the WIM.
- * @param image
- * 	The 1-based index of the image for which to change the description.
- * @param description
- * 	The new description to give the image.  It may be @c NULL, which
- * 	indicates that the image is to be given no description.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * 	@p image does not exist in @p wim.
+ * Change the description of a WIM image.  Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "DESCRIPTION", description)</tt>.
  */
 extern int
 wimlib_set_image_descripton(WIMStruct *wim, int image,
@@ -3990,20 +3953,8 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
  * @ingroup G_modifying_wims
  *
  * Change what is stored in the \<FLAGS\> element in the WIM XML document
- * (usually something like "Core" or "Ultimate")
- *
- * @param wim
- * 	Pointer to the ::WIMStruct for the WIM.
- * @param image
- * 	The 1-based index of the image for which to change the flags.
- * @param flags
- * 	The new \<FLAGS\> element to give the image.  It may be @c NULL, which
- * 	indicates that the image is to be given no \<FLAGS\> element.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * 	@p image does not exist in @p wim.
+ * (usually something like "Core" or "Ultimate").  Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "FLAGS", flags)</tt>.
  */
 extern int
 wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
@@ -4011,23 +3962,8 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
 /**
  * @ingroup G_modifying_wims
  *
- * Change the name of a WIM image.
- *
- * @param wim
- * 	Pointer to the ::WIMStruct for the WIM.
- * @param image
- * 	The 1-based index of the image for which to change the name.
- * @param name
- *	New name to give the new image.  If @c NULL or empty, the new image is
- *	given no name.  Otherwise, it must specify a name that does not already
- *	exist in @p wim.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
- *	The WIM already contains an image with the requested name.
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * 	@p image does not exist in @p wim.
+ * Change the name of a WIM image.  Equivalent to
+ * <tt>wimlib_set_image_property(wim, image, "NAME", name)</tt>.
  */
 extern int
 wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
@@ -4060,6 +3996,9 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
  *
  * @return 0 on success; a ::wimlib_error_code value on failure.
  *
+ * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
+ *	The user requested to set the image name (the <tt>NAME</tt> property),
+ *	but another image in the WIM already had the requested name.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  *	@p image does not exist in @p wim.
  * @retval ::WIMLIB_ERR_INVALID_PARAM