X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=a5a73e3895883a7243b8beda78d61a36f1438aaa;hp=02f7473288c814b386fe2682f7c78d2125e4d2f7;hb=037dc6208a1e57910a46e05f5de2788d8adfa207;hpb=d55cda59032e0abe5f71cd6f16ade943d2713fee

diff --git a/include/wimlib.h b/include/wimlib.h
index 02f74732..a5a73e38 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -31,7 +31,7 @@
  *
  * \section intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.4.0, a C
+ * This is the documentation for the library interface of wimlib 1.4.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
@@ -164,7 +164,7 @@
 #define WIMLIB_MINOR_VERSION 4
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
 
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
@@ -191,6 +191,15 @@ typedef wchar_t wimlib_tchar;
 typedef char wimlib_tchar;
 #endif
 
+#ifdef __WIN32__
+/** Path separator for WIM paths passed back to progress callbacks. */
+#  define WIMLIB_WIM_PATH_SEPARATOR '\\'
+#  define WIMLIB_WIM_PATH_SEPARATOR_STRING L"\\"
+#else
+/** Path separator for WIM paths passed back to progress callbacks. */
+#  define WIMLIB_WIM_PATH_SEPARATOR '/'
+#  define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
+#endif
 /**
  * Specifies the compression type of a WIM file.
  */
@@ -214,7 +223,7 @@ enum wimlib_progress_msg {
 
 	/** A WIM image is about to be extracted.  @a info will point to
 	 * ::wimlib_progress_info.extract. */
-	WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
+	WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0,
 
 	/** A file or directory tree within a WIM image (not the full image) is
 	 * about to be extracted.  @a info will point to
@@ -314,6 +323,19 @@ enum wimlib_progress_msg {
 	/** A wimlib_split() operation is in progress, and a split part has been
 	 * finished. @a info will point to ::wimlib_progress_info.split. */
 	WIMLIB_PROGRESS_MSG_SPLIT_END_PART,
+
+	/**
+	 * A WIM update command is just about to be executed; @a info will point
+	 * to ::wimlib_progress_info.update.
+	 */
+	WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND,
+
+	/**
+	 * A WIM update command has just been executed; @a info will point to
+	 * ::wimlib_progress_info.update.
+	 */
+	WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND,
+
 };
 
 /** A pointer to this union is passed to the user-supplied
@@ -438,6 +460,22 @@ union wimlib_progress_info {
 		const wimlib_tchar *to;
 	} rename;
 
+	/** Valid on messages ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
+	 * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND. */
+	struct wimlib_progress_info_update {
+		/** Pointer to the update command that will be executed or has
+		 * just been executed. */
+		const struct wimlib_update_command *command;
+
+		/** Number of update commands that have been completed so far.
+		 */
+		size_t completed_commands;
+
+		/** Number of update commands that are being executed as part of
+		 * this call to wimlib_update_image(). */
+		size_t total_commands;
+	} update;
+
 	/** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY and
 	 * ::WIMLIB_PROGRESS_MSG_CALC_INTEGRITY. */
 	struct wimlib_progress_info_integrity {
@@ -729,9 +767,9 @@ struct wimlib_capture_config {
 #define WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES	0x00000800
 
 /** On Windows, when there exist two or more files with the same case
- * insensitive name (but different case sensitive names), try to extract them
- * all by appending junk to the end of them, rather than extracting an
- * arbitrarily only one.  */
+ * insensitive name but different case sensitive names, try to extract them all
+ * by appending junk to the end of them, rather than arbitrarily extracting only
+ * one. */
 #define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS		0x00001000
 
 /******************************
@@ -767,12 +805,24 @@ struct wimlib_capture_config {
  * WIMLIB_OPEN_FLAG_*
  ******************************/
 
-/** Verify the WIM contents against the WIM's integrity table, if present. */
+/** Verify the WIM contents against the WIM's integrity table, if present.  This
+ * causes the raw data of the WIM file, divided into 10 MB chunks, to be
+ * checksummed and checked against the SHA1 message digests specified in the
+ * integrity table.  WIMLIB_ERR_INTEGRITY is returned if there are any
+ * mismatches.  */
 #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY		0x00000001
 
-/** Do not issue an error if the WIM is part of a split WIM. */
+/** Do not issue an error if the WIM is part of a split WIM.  */
 #define WIMLIB_OPEN_FLAG_SPLIT_OK			0x00000002
 
+/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it
+ * is not.  A WIM is considered writable only if it is writable at the
+ * filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its
+ * header (note: wimlib currently never sets this flag), and is not part of a
+ * spanned set.  It is not required to provide this flag to make changes to the
+ * WIM, but with this flag you get the error sooner rather than later. */
+#define WIMLIB_OPEN_FLAG_WRITE_ACCESS			0x00000004
+
 /******************************
  * WIMLIB_UNMOUNT_FLAG_*
  ******************************/
@@ -794,6 +844,14 @@ struct wimlib_capture_config {
 /** Do a "lazy" unmount (detach filesystem immediately, even if busy) */
 #define WIMLIB_UNMOUNT_FLAG_LAZY			0x00000010
 
+/******************************
+ * WIMLIB_UPDATE_FLAG_*
+ ******************************/
+
+/** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
+ * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */
+#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS		0x00000001
+
 /******************************
  * WIMLIB_WRITE_FLAG_*
  ******************************/
@@ -976,6 +1034,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_VOLUME_LACKS_FEATURES,
 	WIMLIB_ERR_WRITE,
 	WIMLIB_ERR_XML,
+	WIMLIB_ERR_WIM_IS_READONLY,
 };
 
 
@@ -994,21 +1053,23 @@ enum wimlib_error_code {
  *	Pointer to the ::WIMStruct for the WIM file to which the image is to be
  *	added.
  * @param name
- *	Name to give the new image.
+ *	Name to give the new image.  If @c NULL or empty, the new image is given
+ *	no name.  If nonempty, it must specify a name that does not already
+ *	exist in @a wim.
  * @param new_idx_ret
  *	If non-<code>NULL</code>, the index of the newly added image is returned
  *	in this location.
  *
  * @return 0 on success; nonzero on failure.  The possible error codes are:
  *
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- *	@a name was @c NULL or an empty string.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- *	@a wim is part of a split WIM.
  * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
  *	There is already an image in @a wim named @a 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,
@@ -1037,8 +1098,9 @@ wimlib_add_empty_image(WIMStruct *wim,
  * 	A path to a directory or unmounted NTFS volume that will be captured as
  * 	a WIM image.
  * @param name
- * 	The name to give the image.  It must be nonempty and must specify a name
- * 	that does not yet exist in @a wim.
+ *	Name to give the new image.  If @c NULL or empty, the new image is given
+ *	no name.  If nonempty, it must specify a name that does not already
+ *	exist in @a wim.
  * @param config
  * 	Capture configuration that specifies files, directories, or path globs
  * 	to exclude from being captured.  If @c NULL, a dummy configuration where
@@ -1155,9 +1217,10 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
  * 	Failed to allocate needed memory.
  * @retval ::WIMLIB_ERR_READ
  * 	Could not read the metadata resource for @a image from the WIM.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * 	@a wim is part of a split WIM.  Deleting an image from a split WIM is
- * 	unsupported.
+ * @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_delete_image(WIMStruct *wim, int image);
@@ -1258,9 +1321,10 @@ wimlib_delete_image(WIMStruct *wim, int image);
  * 	complete split WIM because they do not include all the parts of the
  * 	original WIM, there are duplicate parts, or not all the parts have the
  * 	same GUID and compression type.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * 	@a dest_wim is part of a split WIM.  Exporting an image to a split WIM
- * 	is unsupported.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	@a dest_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_export_image(WIMStruct *src_wim, int src_image,
@@ -1710,7 +1774,7 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name);
  *
  * @return 0 on success; nonzero on error.  This function may return any value
  * returned by wimlib_open_wim() and wimlib_write() except
- * ::WIMLIB_ERR_SPLIT_UNSUPPORTED, as well as the following error code:
+ * ::WIMLIB_ERR_WIM_IS_READONLY, as well as the following error code:
  *
  * @retval ::WIMLIB_ERR_SPLIT_INVALID
  * 	The split WIMs do not form a valid WIM because they do not include all
@@ -1878,9 +1942,10 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len,
  * 	split WIM because they do not include all the parts of the original WIM,
  * 	there are duplicate parts, or not all the parts have the same GUID and
  * 	compression type.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * 	The WIM is a split WIM and a read-write mount was requested.  We only
- * 	support mounting a split WIM read-only.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	::WIMLIB_MOUNT_FLAG_READWRITE was specified in @a mount_flags, but @a
+ *	wim is considered read-only because of any of the reasons mentioned in
+ *	the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
  * @retval ::WIMLIB_ERR_UNSUPPORTED
  * 	Mounting is not supported, either because the platform is Windows, or
  * 	because the platform is UNIX and wimlib was compiled with @c
@@ -1902,18 +1967,7 @@ wimlib_mount_image(WIMStruct *wim,
  * 	The path to the WIM file to open.
  * @param open_flags
  * 	Bitwise OR of flags ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY and/or
- * 	::WIMLIB_OPEN_FLAG_SPLIT_OK.
- * 	<br/> <br/>
- * 	If ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is given, the integrity table of
- * 	the WIM, if it exists, is checked, and this function will fail with an
- * 	::WIMLIB_ERR_INTEGRITY status if any of the computed SHA1 message
- * 	digests of the WIM do not exactly match the corresponding message
- * 	digests given in the integrity table.
- * 	<br/> <br/>
- * 	If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the
- * 	WIM is part of a split WIM; otherwise ::WIMLIB_ERR_SPLIT_UNSUPPORTED is
- * 	returned.  (This flag may be removed in the future, in which case no
- * 	error will be issued when opening a split WIM.)
+ * 	::WIMLIB_OPEN_FLAG_SPLIT_OK and/or ::WIMLIB_OPEN_FLAG_WRITE_ACCESS.
  *
  * @param progress_func
  * 	If non-NULL, a function that will be called periodically with the
@@ -1970,6 +2024,10 @@ wimlib_mount_image(WIMStruct *wim,
  * @retval ::WIMLIB_ERR_UNKNOWN_VERSION
  * 	A number other than 0x10d00 is written in the version field of the WIM
  * 	header of @a wim_file.  (Probably a pre-Vista WIM).
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
+ *	considered read-only because of any of the reasons mentioned in the
+ *	documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
  * @retval ::WIMLIB_ERR_XML
  * 	The XML data for @a wim_file is invalid.
  */
@@ -2038,7 +2096,7 @@ wimlib_open_wim(const wimlib_tchar *wim_file,
  * @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 WIM was going to be modifien in-place (with no temporary file), but
+ * 	The WIM was going to be modified 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.
@@ -2048,6 +2106,10 @@ wimlib_open_wim(const wimlib_tchar *wim_file,
  * @retval ::WIMLIB_ERR_RENAME
  * 	The temporary file that the WIM was written to could not be renamed to
  * 	the original filename of @a wim.
+ * @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_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads,
@@ -2227,9 +2289,9 @@ wimlib_resolve_image(WIMStruct *wim,
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a boot_idx does not specify an existing image in @a wim, and it was not
  * 	0.
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
- * 	@a wim is part of a split WIM.  We do not support changing the boot
- * 	index of a split WIM.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	@a 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_boot_idx(WIMStruct *wim, int boot_idx);
@@ -2253,6 +2315,9 @@ wimlib_set_boot_idx(WIMStruct *wim, int boot_idx);
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @a description
  * 	string.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	@a 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,
@@ -2277,6 +2342,9 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
  * 	@a image does not specify a single existing image in @a wim.
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @a flags string.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	@a 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);
@@ -2291,17 +2359,20 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image,
  * @param image
  * 	The number of the image for which to change the name.
  * @param name
- * 	The new name to give the image.  It must be a nonempty string.
+ *	New name to give the new image.  If @c NULL or empty, the new image is
+ *	given no name.  If nonempty, it must specify a name that does not
+ *	already exist in @a wim.
  *
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
  * 	There is already an image named @a name in @a wim.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a name was @c NULL or the empty string.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a image does not specify a single existing image in @a wim.
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @a name string.
+ * @retval ::WIMLIB_ERR_WIM_IS_READONLY
+ *	@a 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);
@@ -2483,7 +2554,7 @@ wimlib_unmount_image(const wimlib_tchar *dir,
  * @param num_cmds
  *	Number of commands in @a cmds.
  * @param update_flags
- *	Reserved; must be 0.
+ *	::WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0.
  * @param progress_func
  *	If non-NULL, a function that will be called periodically with the
  *	progress of the current operation.
@@ -2570,6 +2641,10 @@ wimlib_unmount_image(const wimlib_tchar *dir,
  * 	or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA
  * 	or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @a
  * 	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.
  */
 extern int
 wimlib_update_image(WIMStruct *wim,