/**
* @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
#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" {
*
* 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,
*
* 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,
*
* 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>1180427429</c>.
*/
WIMLIB_COMPRESSION_TYPE_LZMS = 3,
};
* 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
*/
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;
};
/**
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
};
/** 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;
/** 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;
* */
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];
* 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
* 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
/** @} */
* 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
#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 in 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.
*
* ::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
+ * Currently, new solid resources will, by default, be written using LZMS
* compression with 32 MiB (33554432 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
+ * LZMS-compressed solid resources, for example. However, if including solid
* blocks, 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
*/
#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
* @{ */
* 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,
*
* @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,
* 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,
* 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
* @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,
* @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);
* @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);
* ::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
* @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);
* @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);
* 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,
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
* 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.7.5, 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