X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=c5d118064fc31f101465d7cef06fcd526f38ead0;hp=e9fb0b761ba55c3105be3caae29c3b3e03d323e0;hb=cf13fe6161a69db6cbf17637b60c978fd746078a;hpb=065b2b3513da8692efab0cd5344c054f246fa635

diff --git a/include/wimlib.h b/include/wimlib.h
index e9fb0b76..c5d11806 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -1942,28 +1942,25 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 #define WIMLIB_EXTRACT_FLAG_WIMBOOT			0x00400000
 
 /**
- * EXPERIMENTAL, Windows-only: compress the extracted files using System
- * Compression, when possible.  This only works on either Windows 10 or later,
- * or on an older Windows to which Microsoft's wofadk.sys driver has been added.
- * Several different compression formats may be used with System Compression;
- * this particular flag selects the XPRESS compression format with 4096 byte
- * chunks.  <b>This flag is currently experimental and may be changed or removed
- * in future releases of wimlib.</b>  */
+ * Since wimlib v1.8.2 and Windows-only: compress the extracted files using
+ * System Compression, when possible.  This only works on either Windows 10 or
+ * later, or on an older Windows to which Microsoft's wofadk.sys driver has been
+ * added.  Several different compression formats may be used with System
+ * Compression; this particular flag selects the XPRESS compression format with
+ * 4096 byte chunks.
+ */
 #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K		0x01000000
 
 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
- * 8192 byte chunks.  <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b>  */
+ * 8192 byte chunks.  */
 #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K		0x02000000
 
 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
- * 16384 byte chunks.  <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b>  */
+ * 16384 byte chunks.  */
 #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K		0x04000000
 
 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with
- * 32768 byte chunks.  <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b>  */
+ * 32768 byte chunks.  */
 #define WIMLIB_EXTRACT_FLAG_COMPACT_LZX			0x08000000
 
 /** @} */
@@ -2263,6 +2260,24 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_WRITE_FLAG_NO_SOLID_SORT			0x00004000
 
+/**
+ * Since wimlib v1.8.3 and for wimlib_overwrite() only: <b>unsafely</b> compact
+ * the WIM file in-place, without appending.  Existing resources are shifted
+ * down to fill holes and new resources are appended as needed.  The WIM file is
+ * truncated to its final size, which may shrink the on-disk file.  <b>This
+ * operation cannot be safely interrupted.  If the operation is interrupted,
+ * then the WIM file will be corrupted, and it may be impossible (or at least
+ * very difficult) to recover any data from it.  Users of this flag are expected
+ * to know what they are doing and assume responsibility for any data corruption
+ * that may result.</b>
+ *
+ * If the WIM file cannot be compacted in-place because of its structure, its
+ * layout, or other requested write parameters, then wimlib_overwrite() fails
+ * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry
+ * the operation without this flag.
+ */
+#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT		0x00008000
+
 /** @} */
 /** @addtogroup G_general
  * @{ */
@@ -2480,6 +2495,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_FVE_LOCKED_VOLUME		      = 82,
 	WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG      = 83,
 	WIMLIB_ERR_WIM_IS_INCOMPLETE		      = 84,
+	WIMLIB_ERR_COMPACTION_NOT_POSSIBLE            = 85,
 };
 
 
@@ -3137,9 +3153,10 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
 /**
  * @ingroup G_wim_information
  *
- * Get a per-image property from the WIM's XML document.  This is an alternative
- * to wimlib_get_image_name() and wimlib_get_image_descripton() which allows
- * getting any simple string property.
+ * Since wimlib v1.8.3: get a per-image property from the WIM's XML document.
+ * This is an alternative to wimlib_get_image_name() and
+ * wimlib_get_image_description() which allows getting any simple string
+ * property.
  *
  * @param wim
  *	Pointer to the ::WIMStruct for the WIM.
@@ -3153,8 +3170,8 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
  *	element.  The <tt>[</tt> character is reserved for future use.
  *
  * @return
- *	The property's value as a wimlib_tchar string, or @c NULL if there is no
- *	such property.  The string may not remain valid after later library
+ *	The property's value as a ::wimlib_tchar string, or @c NULL if there is
+ *	no such property.  The string may not remain valid after later library
  *	calls, so the caller should duplicate it if needed.
  */
 extern const wimlib_tchar *
@@ -3590,22 +3607,23 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
 /**
  * @ingroup G_writing_and_overwriting_wims
  *
- * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it
- * as needed.
+ * Commit a ::WIMStruct to disk, updating its backing file.
  *
- * There are two alternative ways in which changes may be committed:
+ * There are several alternative ways in which changes may be committed:
  *
  *   1. Full rebuild: write the updated WIM to a temporary file, then rename the
  *	temporary file to the original.
  *   2. Appending: append updates to the new original WIM file, then overwrite
  *	its header such that those changes become visible to new readers.
- *
- * Append mode is often much faster, but it wastes some amount of space due to
- * leaving "holes" in the WIM file.  Because of the greater efficiency,
- * wimlib_overwrite() normally defaults to append mode.  However,
- * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild.
- * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then
- * the default mode switches to rebuild mode, and
+ *   3. Compaction: normally should not be used; see
+ *	::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details.
+ *
+ * Append mode is often much faster than a full rebuild, but it wastes some
+ * amount of space due to leaving "holes" in the WIM file.  Because of the
+ * greater efficiency, wimlib_overwrite() normally defaults to append mode.
+ * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full
+ * rebuild.  In addition, if wimlib_delete_image() has been used on the
+ * ::WIMStruct, then the default mode switches to rebuild mode, and
  * ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append
  * mode.
  *
@@ -3994,8 +4012,8 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
 /**
  * @ingroup G_modifying_wims
  *
- * Add, modify, or remove a per-image property from the WIM's XML document.
- * This is an alternative to wimlib_set_image_name(),
+ * Since wimlib v1.8.3: add, modify, or remove a per-image property from the
+ * WIM's XML document.  This is an alternative to wimlib_set_image_name(),
  * wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows
  * manipulating any simple string property.
  *