X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=9b629d66f40e8571df0fbe9fababd577cc3b915a;hp=76d63b26d19301a3b5a2f8231828de121f9eebc8;hb=de567a8c5dcd0910a8c762d75bf11b9c9683396c;hpb=c64549817d956075c0489661eac56128ee6fa630

diff --git a/include/wimlib.h b/include/wimlib.h
index 76d63b26..9b629d66 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -9,29 +9,10 @@
  * in this header.
  */
 
-/*
- * Copyright (C) 2012, 2013, 2014 Eric Biggers
- *
- * This file is part of wimlib, a library for working with WIM files.
- *
- * wimlib is free software; you can redistribute it and/or modify it under the
- * terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 3 of the License, or (at your option)
- * any later version.
- *
- * wimlib is distributed in the hope that it will be useful, but WITHOUT ANY
- * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- * A PARTICULAR PURPOSE. See the GNU General Public License for more
- * details.
- *
- * You should have received a copy of the GNU General Public License
- * along with wimlib; if not, see http://www.gnu.org/licenses/.
- */
-
 /**
  * @mainpage
  *
- * This is the documentation for the library interface of wimlib 1.7.1, a C
+ * This is the documentation for the library interface of wimlib 1.7.4, 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
@@ -71,6 +52,19 @@
  * source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
  * capabilities of wimlib.
  *
+ * @section backwards_compatibility Backwards Compatibility
+ *
+ * New releases of wimlib are intended to be API/ABI compatible with old
+ * releases, except when the libtool "age" is reset.  This most recently
+ * occurred for the v1.4.0 (libwim7), v1.5.0 (libwim9), and v1.7.0 (libwim15)
+ * releases.  However, the library is becoming increasingly stable, and the goal
+ * is to maintain the current API/ABI for as long as possible unless there is a
+ * strong reason not to.  Even for the v1.7.0 release (libwim15), the changes
+ * were fairly limited.
+ *
+ * As with any other library, applications should not rely on internal
+ * implementation details that may be subject to change.
+ *
  * @section sec_basic_wim_handling_concepts Basic WIM handling concepts
  *
  * wimlib wraps up a WIM file in an opaque ::WIMStruct structure.   There are
@@ -385,7 +379,7 @@
 #define WIMLIB_MINOR_VERSION 7
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 4
 
 #ifdef __cplusplus
 extern "C" {
@@ -480,7 +474,7 @@ enum wimlib_compression_type {
 	 *
 	 * If using wimlib_create_compressor() to create an XPRESS compressor
 	 * directly, the @p max_block_size parameter may be any positive value
-	 * up to <c>2^16</c>.
+	 * up to and including <c>2^16</c>.
 	 */
 	WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
 
@@ -502,7 +496,7 @@ enum wimlib_compression_type {
 	 *
 	 * If using wimlib_create_compressor() to create an LZX compressor
 	 * directly, the @p max_block_size parameter may be any positive value
-	 * up to <c>2^21</c>.
+	 * up to and including <c>2^21</c>.
 	 */
 	WIMLIB_COMPRESSION_TYPE_LZX = 2,
 
@@ -517,13 +511,15 @@ enum wimlib_compression_type {
 	 * later.  Also, chunk sizes larger than <c>2^26</c> are not compatible
 	 * with the Microsoft implementation.
 	 *
-	 * wimlib's LZMS compressor is currently faster but will usually not
-	 * compress as much as the implementation in Microsoft's WIMGAPI
-	 * (Windows 8.1).
+	 * wimlib's LZMS compressor will, with the default settings, usually
+	 * produce a better compression ratio, and work more quickly, than the
+	 * implementation in Microsoft's WIMGAPI (as of Windows 8.1).  There is
+	 * limited support for non-default compression levels, but compression
+	 * will be noticably faster if you choose a level < 35.
 	 *
 	 * If using wimlib_create_compressor() to create an LZMS compressor
 	 * directly, the @p max_block_size parameter may be any positive value
-	 * up to <c>2^31 - 2</c>.
+	 * up to and including <c>2^30</c>.
 	 */
 	WIMLIB_COMPRESSION_TYPE_LZMS = 3,
 };
@@ -714,6 +710,28 @@ enum wimlib_progress_msg {
 	 * mechanism.
 	 */
 	WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION = 30,
+
+	/**
+	 * An error has occurred and the progress function is being asked
+	 * whether to ignore the error or not.  @p info will point to
+	 * ::wimlib_progress_info.handle_error.  This is a bidirectional
+	 * message.
+	 *
+	 * This message provides a limited capability for applications to
+	 * recover from "unexpected" errors (i.e. those with no in-library
+	 * handling policy) arising from the underlying operating system.
+	 * Normally, any such error will cause the library to abort the current
+	 * operation.  By implementing a handler for this message, the
+	 * application can instead choose to ignore a given error.
+	 *
+	 * Currently, only the following types of errors will result in this
+	 * progress message being sent:
+	 *
+	 *	- Directory tree scan errors, e.g. from wimlib_add_image()
+	 *	- Most extraction errors; currently restricted to the Windows
+	 *	  build of the library only.
+	 */
+	WIMLIB_PROGRESS_MSG_HANDLE_ERROR = 31,
 };
 
 /** Valid return values from user-provided progress functions
@@ -1210,6 +1228,24 @@ union wimlib_progress_info {
 		 */
 		bool will_exclude;
 	} test_file_exclusion;
+
+	/** Valid on messages ::WIMLIB_PROGRESS_MSG_HANDLE_ERROR.  */
+	struct wimlib_progress_info_handle_error {
+
+		/** Path to the file for which the error occurred, or NULL if
+		 * not relevant.  */
+		const wimlib_tchar *path;
+
+		/** The wimlib error code associated with the error.  */
+		int error_code;
+
+		/**
+		 * Indicates whether the error will be ignored or not.  This
+		 * will be <tt>false</tt> by default; the progress function may
+		 * set it to <tt>true</tt>.
+		 */
+		bool will_ignore;
+	} handle_error;
 };
 
 /**
@@ -1254,14 +1290,15 @@ struct wimlib_capture_source {
 	long reserved;
 };
 
-/** Set or unset the WIM header flag that marks it read-only
- * (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the
- * ::wimlib_wim_info.is_marked_readonly member of the @p info parameter.  This
- * is distinct from basic file permissions; this flag can be set on a WIM file
- * that is physically writable.  If this flag is set, all further operations to
- * modify the WIM will fail, except calling wimlib_overwrite() with
- * ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG specified, which is a loophole that
- * allows you to set this flag persistently on the underlying WIM file.
+/** Set or unset the "readonly" WIM header flag (WIM_HDR_FLAG_READONLY in
+ * Microsoft's documentation), based on the ::wimlib_wim_info.is_marked_readonly
+ * member of the @p info parameter.  This is distinct from basic file
+ * permissions; this flag can be set on a WIM file that is physically writable.
+ *
+ * wimlib disallows modifying on-disk WIM files with the readonly flag set.
+ * However, wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG
+ * will override this --- and in fact, this is necessary to set the readonly
+ * flag persistently on an existing WIM file.
  */
 #define WIMLIB_CHANGE_READONLY_FLAG		0x00000001
 
@@ -1357,7 +1394,7 @@ struct wimlib_wim_info {
 };
 
 /** Information about a unique stream in the WIM file.  (A stream is the same
- * thing as a "resource", except in the case of packed resources.)  */
+ * thing as a "resource", except in the case of solid resources.)  */
 struct wimlib_resource_entry {
 	/** Uncompressed size of the stream in bytes. */
 	uint64_t uncompressed_size;
@@ -1369,7 +1406,7 @@ struct wimlib_resource_entry {
 
 	/** Offset, in bytes, of this stream from the start of the WIM file.  Or
 	 * if @p packed is 1, then this is actually the offset at which this
-	 * stream begins in the uncompressed contents of the packed resource.
+	 * stream begins in the uncompressed contents of the solid resource.
 	 */
 	uint64_t offset;
 
@@ -1398,18 +1435,18 @@ struct wimlib_resource_entry {
 	 * */
 	uint32_t is_missing : 1;
 
-	/** 1 if this stream is located in a packed resource which may contain
+	/** 1 if this stream is located in a solid resource which may contain
 	 * other streams (all compressed together) as well.  */
 	uint32_t packed : 1;
 
 	uint32_t reserved_flags : 26;
 
-	/** If @p packed is 1, then this will specify the offset of the packed
+	/** If @p packed is 1, then this will specify the offset of the solid
 	 * resource in the WIM.  */
 	uint64_t raw_resource_offset_in_wim;
 
 	/** If @p packed is 1, then this will specify the compressed size of the
-	 * packed resource in the WIM.  */
+	 * solid resource in the WIM.  */
 	uint64_t raw_resource_compressed_size;
 
 	uint64_t reserved[2];
@@ -1729,8 +1766,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * Note: This method for file exclusions is independent from the capture
  * configuration file mechanism.
  */
-#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
+#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
@@ -1979,8 +2018,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * only if it is writable at the filesystem level, does not have the
  * WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned
  * set.  It is not required to provide this flag before attempting to make
- * changes to the WIM, but with this flag you get an error sooner rather than
- * later.  */
+ * changes to the WIM, but with this flag you get an error immediately rather
+ * than potentially much later, when wimlib_overwrite() is finally called.  */
 #define WIMLIB_OPEN_FLAG_WRITE_ACCESS			0x00000004
 
 /** @} */
@@ -2082,10 +2121,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * wimlib_set_default_compression_level() can be called beforehand to set an
  * even higher compression level than the default.
  *
- * If the WIM contains solid blocks, then ::WIMLIB_WRITE_FLAG_RECOMPRESS can be
- * used in combination with ::WIMLIB_WRITE_FLAG_PACK_STREAMS to prevent any
- * solid blocks from being re-used.  Otherwise, solid blocks are re-used
- * somewhat more liberally than normal compressed blocks.
+ * If the WIM contains solid resources, then ::WIMLIB_WRITE_FLAG_RECOMPRESS can
+ * be used in combination with ::WIMLIB_WRITE_FLAG_SOLID to prevent any solid
+ * resources from being re-used.  Otherwise, solid resources are re-used
+ * somewhat more liberally than normal compressed resources.
  *
  * ::WIMLIB_WRITE_FLAG_RECOMPRESS does <b>not</b> cause recompression of streams
  * that would not otherwise be written.  For example, a call to
@@ -2179,8 +2218,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 #define WIMLIB_WRITE_FLAG_RETAIN_GUID			0x00000800
 
 /**
- * When writing streams in the resulting WIM file, pack multiple streams into a
- * single compressed resource instead of compressing them independently.  This
+ * When writing streams to the resulting WIM file, combine multiple streams into
+ * a single compressed resource instead of compressing them independently.  This
  * is also known as creating a "solid archive".  This tends to produce a better
  * compression ratio at the cost of much slower random access.
  *
@@ -2194,23 +2233,29 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * ::WIMLIB_WRITE_FLAG_RECOMPRESS to force the entire WIM file be rebuilt with
  * all streams recompressed in solid mode.
  *
- * Currently, new solid blocks will, by default, be written using LZMS
- * compression with 32 MiB (33554432 byte) chunks.  Use
+ * Currently, new solid resources will, by default, be written using LZMS
+ * compression with 64 MiB (67108864 byte) chunks.  Use
  * wimlib_set_output_pack_compression_type() and/or
  * wimlib_set_output_pack_chunk_size() to change this.  This is independent of
  * the WIM's main compression type and chunk size; you can have a WIM that
  * nominally uses LZX compression and 32768 byte chunks but actually contains
- * LZMS-compressed solid blocks, for example.  However, if including solid
- * blocks, I suggest that you set the WIM's main compression type to LZMS as
+ * LZMS-compressed solid resources, for example.  However, if including solid
+ * resources, I suggest that you set the WIM's main compression type to LZMS as
  * well, either by creating the WIM with
  * ::wimlib_create_new_wim(::WIMLIB_COMPRESSION_TYPE_LZMS, ...) or by calling
  * ::wimlib_set_output_compression_type(..., ::WIMLIB_COMPRESSION_TYPE_LZMS).
  *
  * This flag will be set by default when writing or overwriting a WIM file that
- * either already contains packed streams, or has had packed streams exported
+ * either already contains solid resources, or has had solid resources exported
  * into it and the WIM's main compression type is LZMS.
  */
-#define WIMLIB_WRITE_FLAG_PACK_STREAMS			0x00001000
+#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
@@ -2219,6 +2264,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES	0x00002000
 
+/**
+ * If using solid compression, do not sort the streams ("files") to compress by
+ * estimated content similarily.  This flag only has an effect if
+ * ::WIMLIB_WRITE_FLAG_SOLID is also specified.
+ */
+#define WIMLIB_WRITE_FLAG_NO_SOLID_SORT			0x00004000
+
 /** @} */
 /** @addtogroup G_general
  * @{ */
@@ -2434,6 +2486,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY              = 79,
 	WIMLIB_ERR_NOT_A_MOUNTPOINT                   = 80,
 	WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT           = 81,
+	WIMLIB_ERR_FVE_LOCKED_VOLUME		      = 82,
 };
 
 
@@ -2473,10 +2526,6 @@ enum wimlib_error_code {
  *	There is already an image in @p wim named @p 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,
@@ -2639,10 +2688,6 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
  *
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@p image does not exist in the WIM and is not ::WIMLIB_ALL_IMAGES.
- * @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.
  *
  * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
  * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
@@ -2733,10 +2778,6 @@ wimlib_delete_path(WIMStruct *wim, int image,
  *	WIM parts were not referenced with wimlib_reference_resources() or
  *	wimlib_reference_resource_files() before the call to
  *	wimlib_export_image().
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- *	@p dest_wim is considered read-only because of any of the reasons
- *	mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- *	flag.
  *
  * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
  * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
@@ -3157,7 +3198,7 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
  * bits contain the patch version.
  *
  * In other words, the returned value is equal to <code>((WIMLIB_MAJOR_VERSION
- * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
+ * << 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
  * corresponding header file.
  */
 extern uint32_t
@@ -3967,9 +4008,6 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path);
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @p description
  * 	string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- *	@p 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,
@@ -4008,7 +4046,7 @@ wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size);
  * @ingroup G_writing_and_overwriting_wims
  *
  * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing
- * packed streams (solid blocks).
+ * solid resources.
  */
 extern int
 wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size);
@@ -4039,7 +4077,7 @@ wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
  * @ingroup G_writing_and_overwriting_wims
  *
  * Similar to wimlib_set_output_compression_type(), but set the compression type
- * for writing packed streams (solid blocks).
+ * for writing solid resources.
  */
 extern int
 wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
@@ -4061,12 +4099,6 @@ wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
  *	::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG.
  *
  * @return 0 on success; nonzero on failure.
- * @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.  However, as a special case, if you are using
- *	::WIMLIB_CHANGE_READONLY_FLAG to unset the readonly flag, then this
- *	function will not fail due to the readonly flag being previously set.
  * @retval ::WIMLIB_ERR_IMAGE_COUNT
  *	::WIMLIB_CHANGE_BOOT_INDEX was specified, but
  *	::wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image
@@ -4095,9 +4127,6 @@ wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info,
  * 	@p image does not specify a single existing image in @p wim.
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @p flags string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- *	@p 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);
@@ -4123,9 +4152,6 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
  * 	@p image does not specify a single existing image in @p wim.
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @p name string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- *	@p 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);
@@ -4339,6 +4365,9 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
  * be rolled back, and no visible changes shall have been made to @p wim.
  * Possible error codes include:
  *
+ * @retval ::WIMLIB_ERR_FVE_LOCKED_VOLUME
+ *	Windows-only: One of the "add" commands attempted to add files from an
+ *	encrypted BitLocker volume that hasn't yet been unlocked.
  * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
  *	The capture configuration structure specified for an add command was
  *	invalid.
@@ -4407,10 +4436,6 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
  *	a supported file type (e.g. a device file).  Only if
  *	::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the 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.
  *
  * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
  * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
@@ -4601,6 +4626,8 @@ wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype,
 				    size_t max_block_size,
 				    unsigned int compression_level);
 
+#define WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE	0x80000000
+
 /**
  * Allocate a compressor for the specified compression type using the specified
  * parameters.  This function is part of wimlib's compression API; it is not
@@ -4645,6 +4672,15 @@ wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype,
  *	The compression level does not affect the format of the compressed data.
  *	Therefore, it is a compressor-only parameter and does not need to be
  *	passed to the decompressor.
+ *	<br/>
+ *	Since wimlib v1.8.0, this parameter can be OR-ed with the flag
+ *	::WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE.  This creates the compressor in a
+ *	mode where it is allowed to modify the input buffer.  Specifically, in
+ *	this mode, if compression succeeds, the input buffer may have been
+ *	modified, whereas if compression does not succeed the input buffer still
+ *	may have been written to but will have been restored exactly to its
+ *	original state.  This mode is designed to save some memory when using
+ *	large buffer sizes.
  * @param compressor_ret
  *	A location into which to return the pointer to the allocated compressor.
  *	The allocated compressor can be used for any number of calls to