X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=d9a80c1c6c5a350531dd00d047d48af9089a948d;hp=5265a3968094d4a7a2b8782ab7974f57c3513d06;hb=e0b8c0c5740abaeb24d39a58ffcc4235f26c4bbf;hpb=3fa7b7a033ce803accfd6758029114323f6a6865

diff --git a/src/wimlib.h b/src/wimlib.h
index 5265a396..d9a80c1c 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -31,7 +31,7 @@
  *
  * \section intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.2.0.  If you
+ * This is the documentation for the library interface of wimlib 1.2.3.  If you
  * have installed wimlib and want to know how to use the @c imagex program,
  * please see the man pages instead.
  *
@@ -217,7 +217,7 @@
 
 #define WIMLIB_MAJOR_VERSION 1
 #define WIMLIB_MINOR_VERSION 2
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 3
 
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
@@ -636,6 +636,12 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * discarded.  Ignored for read-only mounts. */
 #define WIMLIB_UNMOUNT_FLAG_COMMIT			0x00000002
 
+/** See ::WIMLIB_WRITE_FLAG_REBUILD */
+#define WIMLIB_UNMOUNT_FLAG_REBUILD			0x00000004
+
+/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */
+#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS			0x00000008
+
 /******************************
  * WIMLIB_WRITE_FLAG_*        *
  ******************************/
@@ -655,7 +661,7 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 /** Call fsync() when the WIM file is closed */
 #define WIMLIB_WRITE_FLAG_FSYNC				0x00000008
 
-/** Specifying this flag overrides the default behavior of wimlib_overwrite()
+/* Specifying this flag overrides the default behavior of wimlib_overwrite()
  * after one or more calls to wimlib_delete_image(), which is to rebuild the
  * entire WIM.
  *
@@ -675,13 +681,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 enum wimlib_error_code {
 	WIMLIB_ERR_SUCCESS = 0,
 	WIMLIB_ERR_ALREADY_LOCKED,
-	WIMLIB_ERR_CHAR_CONVERSION,
 	WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
 	WIMLIB_ERR_DECOMPRESSION,
 	WIMLIB_ERR_DELETE_STAGING_DIR,
+	WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED,
 	WIMLIB_ERR_FORK,
 	WIMLIB_ERR_FUSE,
 	WIMLIB_ERR_FUSERMOUNT,
+	WIMLIB_ERR_ICONV_NOT_AVAILABLE,
 	WIMLIB_ERR_IMAGE_COUNT,
 	WIMLIB_ERR_IMAGE_NAME_COLLISION,
 	WIMLIB_ERR_INTEGRITY,
@@ -698,6 +705,10 @@ enum wimlib_error_code {
 	WIMLIB_ERR_INVALID_RESOURCE_HASH,
 	WIMLIB_ERR_INVALID_RESOURCE_SIZE,
 	WIMLIB_ERR_INVALID_SECURITY_DATA,
+	WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
+	WIMLIB_ERR_INVALID_UTF8_STRING,
+	WIMLIB_ERR_INVALID_UTF16_STRING,
+	WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
 	WIMLIB_ERR_LINK,
 	WIMLIB_ERR_MKDIR,
 	WIMLIB_ERR_MQUEUE,
@@ -734,14 +745,19 @@ enum wimlib_error_code {
 /**
  * Adds an image to a WIM file from an on-disk directory tree or NTFS volume.
  *
- * The directory tree is read immediately for the purpose of constructing a
- * directory entry tree in-memory.  Also, all files are read to calculate their
- * SHA1 message digests.  However, because the directory tree may contain a very
- * large amount of data, the files themselves are not read into memory
- * permanently, and instead references to their paths saved.  The files are then
- * read on-demand if wimlib_write() or wimlib_overwrite() is called.
+ * The directory tree of NTFS volume is read immediately for the purpose of
+ * constructing a directory entry tree in-memory.  Also, all files are read to
+ * calculate their SHA1 message digests.  However, because the directory tree
+ * may contain a very large amount of data, the files themselves are not read
+ * into memory permanently, and instead references to their paths saved.  The
+ * files are then read on-demand if wimlib_write() or wimlib_overwrite() is
+ * called.
  *
- * Please note that @b no changes are committed to the underlying WIM file (if
+ * See the manual page for the @c imagex program for more information about the
+ * "normal" capture mode versus the NTFS capture mode (entered by providing the
+ * flag ::WIMLIB_ADD_IMAGE_FLAG_NTFS).
+ *
+ * Note that @b no changes are committed to the underlying WIM file (if
  * any) until wimlib_write() or wimlib_overwrite() is called.
  *
  * @param wim
@@ -759,17 +775,8 @@ enum wimlib_error_code {
  * @param config_len
  * 	Length of the string @a config in bytes.  Ignored if @a config is @c
  * 	NULL.
- *
  * @param add_image_flags
- * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_BOOT is specified, the image in @a wim that is
- * 	marked as bootable is changed to the one being added.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_VERBOSE is specified, the name of each file is
- * 	printed as it is scanned or captured.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE is specified, the files or
- * 	directories pointed to by symbolic links are archived rather than the
- * 	symbolic links themselves.
- *
+ * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
  * @param progress_func
  * 	If non-NULL, a function that will be called periodically with the
  * 	progress of the current operation.
@@ -814,7 +821,7 @@ enum wimlib_error_code {
  * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
  * 	@a wim is part of a split WIM.  Adding an image to a split WIM is
  * 	unsupported.
- * @retval ::WIMLIB_ERR_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
  * 	::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags, but
  * 	wimlib was configured with the @c --without-ntfs-3g flag.
  */
@@ -1349,7 +1356,7 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
 /**
  * Mounts an image in a WIM file on a directory read-only or read-write.
  *
- * The calling thread will be daemonized service the filesystem, and this
+ * The calling thread will be daemonized to service the filesystem, and this
  * function will not return until the image is unmounted, unless an error occurs
  * before the filesystem is successfully mounted.
  *
@@ -1403,6 +1410,7 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
  * 	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
@@ -1833,7 +1841,7 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const char *flags);
  * @param image
  * 	The number of the image for which to change the name.
  * @param name
- * 	The new name to give the image.  It must not a nonempty string.
+ * 	The new name to give the image.  It must be a nonempty string.
  *
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
@@ -1926,7 +1934,7 @@ extern int wimlib_set_print_errors(bool show_messages);
  * @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_SPLIT_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
  * 	@a wim is not part 1 of a stand-alone WIM.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
  * 	@a swm_name was @c NULL, or @a part_size was 0.
@@ -1948,29 +1956,29 @@ extern int wimlib_split(WIMStruct *wim, const char *swm_name,
  *
  * To unmount the image, the thread calling this function communicates with the
  * thread that is managing the mounted WIM image.  This function blocks until it
- * is known whether the unmount succeeded or failed.  (This means until the
- * entire WIM has been re-written, in the case of a read-write mounted WIM.)
- *
- * There is currently a design problem with this function because it is hard to
- * know whether the filesystem thread is still working or whether it has crashed
- * or has been killed.  Currently, a timeout of 600 seconds (so long because
- * WIMs can be very large) is implemented so that this function will not wait
- * forever before returning failure.
+ * is known whether the unmount succeeded or failed.  In the case of a
+ * read-write mounted WIM, the unmount is not considered to have succeeded until
+ * all changes have been saved to the underlying WIM file.
  *
  * @param dir
  * 	The directory that the WIM image was mounted on.
  * @param unmount_flags
- * 	Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY and/or
- * 	::WIMLIB_UNMOUNT_FLAG_COMMIT.  Neither of these flags affect read-only
+ * 	Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY,
+ * 	::WIMLIB_UNMOUNT_FLAG_COMMIT, ::WIMLIB_UNMOUNT_FLAG_REBUILD, and/or
+ * 	::WIMLIB_UNMOUNT_FLAG_RECOMPRESS.  None of these flags affect read-only
  * 	mounts.
  * @param progress_func
- * 	Currently ignored, but may be used for a progress callback in the
- * 	future.  Set to @c NULL.
+ * 	If non-NULL, a function that will be called periodically with the
+ * 	progress of the current operation.
  *
  * @return 0 on success; nonzero on error.
+ *
  * @retval ::WIMLIB_ERR_DELETE_STAGING_DIR
  * 	The filesystem daemon was unable to remove the staging directory and the
  * 	temporary files that it contains.
+ * @retval ::WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED
+ * 	The filesystem daemon appears to have terminated before sending an exit
+ * 	status.
  * @retval ::WIMLIB_ERR_FORK
  * 	Could not @c fork() the process.
  * @retval ::WIMLIB_ERR_FUSERMOUNT
@@ -1985,10 +1993,6 @@ extern int wimlib_split(WIMStruct *wim, const char *swm_name,
  * @retval ::WIMLIB_ERR_OPEN
  * 	The filesystem daemon could not open a temporary file for writing the
  * 	new WIM.
- * @retval ::WIMLIB_ERR_TIMEOUT
- * 	600 seconds elapsed while waiting for the filesystem daemon to notify
- * 	the process of its exit status, so the WIM file probably was not written
- * 	successfully.
  * @retval ::WIMLIB_ERR_READ
  * 	A read error occurred when the filesystem daemon tried to a file from
  * 	the staging directory