X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=63cc3e200c2b0e486a24ec65606019f3d18f7d15;hb=8b709192cd2811b83c248fbe61ca4f11ee9de797;hp=9988d2549ca031ca59700f6b20074ad1fd75bbd3;hpb=2d1d94d0ba9ae7cce8c8cf21d617e7f289d1764b;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index 9988d254..63cc3e20 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -11,7 +11,7 @@
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.8.0, a C
+ * This is the documentation for the library interface of wimlib 1.8.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
@@ -383,7 +383,7 @@
#define WIMLIB_MINOR_VERSION 8
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
#ifdef __cplusplus
extern "C" {
@@ -1002,7 +1002,7 @@ union wimlib_progress_info {
* integrity checks. */
uint64_t total_bytes;
- /** The number of bytes that have been processed so far. This
+ /** The number of bytes that have been checksummed so far. This
* starts at 0 and ends at @p total_bytes. */
uint64_t completed_bytes;
@@ -1010,8 +1010,8 @@ union wimlib_progress_info {
* integrity-checked region is divided into. */
uint32_t total_chunks;
- /** The number of chunks that have been processed so far. This
- * starts at 0 and ends at @p total_chunks. */
+ /** The number of chunks that have been checksummed so far.
+ * This starts at 0 and ends at @p total_chunks. */
uint32_t completed_chunks;
/** The size of each individually checksummed "chunk" in the
@@ -1298,21 +1298,27 @@ struct wimlib_wim_info {
*/
uint32_t opened_from_file : 1;
- /** 1 iff this WIM file is considered readonly for any reason. */
+ /** 1 iff this WIM file is considered readonly for any reason (e.g. the
+ * "readonly" header flag is set, or this is part of a split WIM, or
+ * filesystem permissions deny writing) */
uint32_t is_readonly : 1;
- /** 1 iff reparse-point fixups are enabled for one or more images in
- * this WIM file. */
+ /** 1 iff the "reparse point fix" flag is set in this WIM's header */
uint32_t has_rpfix : 1;
- /** 1 iff this WIM file is marked read-only in its header. */
+ /** 1 iff the "readonly" flag is set in this WIM's header */
uint32_t is_marked_readonly : 1;
- /** 1 iff this WIM file is part of a spanned set. */
+ /** 1 iff the "spanned" flag is set in this WIM's header */
uint32_t spanned : 1;
+ /** 1 iff the "write in progress" flag is set in this WIM's header */
uint32_t write_in_progress : 1;
+
+ /** 1 iff the "metadata only" flag is set in this WIM's header */
uint32_t metadata_only : 1;
+
+ /** 1 iff the "resource only" flag is set in this WIM's header */
uint32_t resource_only : 1;
/** 1 iff this WIM file is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */
@@ -1938,6 +1944,30 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
+/** EXPERIMENTAL and only works on Windows 10 and later: compress the extracted
+ * files using the System Compression feature (when possible). System
+ * Compression is only supported by Windows 10 or later. Several different
+ * compression formats may be used with System Compression; this particular flag
+ * selects the XPRESS compression format with 4096 byte chunks. This flag is
+ * currently experimental and may be changed or removed in future releases of
+ * wimlib. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000
+
+/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
+ * 8192 byte chunks. This flag is currently experimental and may be changed
+ * or removed in future releases of wimlib. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000
+
+/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
+ * 16384 byte chunks. This flag is currently experimental and may be changed
+ * or removed in future releases of wimlib. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000
+
+/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with
+ * 32768 byte chunks. This flag is currently experimental and may be changed
+ * or removed in future releases of wimlib. */
+#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000
+
/** @} */
/** @addtogroup G_mounting_wim_images
* @{ */
@@ -2451,6 +2481,7 @@ enum wimlib_error_code {
WIMLIB_ERR_NOT_A_MOUNTPOINT = 80,
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
+ WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83,
};
@@ -2564,15 +2595,9 @@ wimlib_add_image(WIMStruct *wim,
* capture for full details on how this mode works.
*
* In addition to the error codes that wimlib_add_image() can return,
- * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY
- * when trying to overlay a non-directory on a directory or when otherwise
- * trying to overlay multiple conflicting files to the same location in the WIM
- * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if
- * ::WIMLIB_ADD_FLAG_NTFS was specified in @p add_flags but there
- * was not exactly one capture source with the target being the root directory.
- * (In this respect, there is no advantage to using
- * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting
- * NTFS mode.)
+ * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY when
+ * trying to overlay a non-directory on a directory or when otherwise trying to
+ * overlay multiple conflicting files to the same location in the WIM image.
*/
extern int
wimlib_add_image_multisource(WIMStruct *wim,
@@ -2603,10 +2628,9 @@ wimlib_add_tree(WIMStruct *wim, int image,
* an on-disk file.
*
* @param ctype
- * The "output compression type" to assign to the ::WIMStruct, given as one
- * of the ::wimlib_compression_type values. This is the compression type
- * that will be used if the ::WIMStruct is later persisted to an on-disk
- * file using wimlib_write().
+ * The "output compression type" to assign to the ::WIMStruct. This is the
+ * compression type that will be used if the ::WIMStruct is later persisted
+ * to an on-disk file using wimlib_write().
*
* This choice is not necessarily final. If desired, it can still be
* changed at any time before wimlib_write() is called, using
@@ -2626,7 +2650,7 @@ wimlib_add_tree(WIMStruct *wim, int image,
* Insufficient memory to allocate a new ::WIMStruct.
*/
extern int
-wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
+wimlib_create_new_wim(enum wimlib_compression_type ctype, WIMStruct **wim_ret);
/**
* @ingroup G_modifying_wims
@@ -2833,7 +2857,8 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
* ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags.
* @retval ::WIMLIB_ERR_WIMBOOT
* ::WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in @p extract_flags, but
- * there was a problem creating WIMBoot pointer files.
+ * there was a problem creating WIMBoot pointer files or registering a
+ * source WIM file with the Windows Overlay Filesystem (WOF) driver.
* @retval ::WIMLIB_ERR_WRITE
* Failed to write data to a file being extracted.
*
@@ -3046,7 +3071,7 @@ wimlib_free(WIMStruct *wim);
* Convert a ::wimlib_compression_type value into a string.
*
* @param ctype
- * The ::wimlib_compression_type value to convert.
+ * The compression type value to convert.
*
* @return
* A statically allocated string naming the compression type, such as
@@ -3054,7 +3079,7 @@ wimlib_free(WIMStruct *wim);
* the resulting string will be "Invalid".
*/
extern const wimlib_tchar *
-wimlib_get_compression_type_string(int ctype);
+wimlib_get_compression_type_string(enum wimlib_compression_type ctype);
/**
* @ingroup G_general
@@ -4018,11 +4043,9 @@ wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size);
* @param wim
* The ::WIMStruct for which to set the output compression type.
* @param ctype
- * The compression type to set (one of ::wimlib_compression_type). If this
- * compression type is incompatible with the current output chunk size
- * (either the default or as set with wimlib_set_output_chunk_size()), then
- * the output chunk size will be reset to the default for that compression
- * type.
+ * The compression type to set. If this compression type is incompatible
+ * with the current output chunk size, then the output chunk size will be
+ * reset to the default for the new compression type.
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
@@ -4030,16 +4053,18 @@ wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size);
* @p ctype did not specify a valid compression type.
*/
extern int
-wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
+wimlib_set_output_compression_type(WIMStruct *wim,
+ enum wimlib_compression_type ctype);
/**
* @ingroup G_writing_and_overwriting_wims
*
* Similar to wimlib_set_output_compression_type(), but set the compression type
- * for writing solid resources.
+ * for writing solid resources. This cannot be ::WIMLIB_COMPRESSION_TYPE_NONE.
*/
extern int
-wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
+wimlib_set_output_pack_compression_type(WIMStruct *wim,
+ enum wimlib_compression_type ctype);
/**
* @ingroup G_general
@@ -4074,9 +4099,9 @@ wimlib_set_print_errors(bool show_messages);
* @param wim
* Pointer to the ::WIMStruct for a WIM.
* @param info
- * A struct ::wimlib_wim_info that contains the information to set. Only
- * the information explicitly specified in the @p which flags need be
- * valid.
+ * Pointer to a ::wimlib_wim_info structure that contains the information
+ * to set. Only the information explicitly specified in the @p which flags
+ * need be valid.
* @param which
* Flags that specify which information to set. This is a bitwise OR of
* ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID,
@@ -4251,20 +4276,16 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
* 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.
+ * The contents of a capture configuration file were invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image did not exist in @p wim.
* @retval ::WIMLIB_ERR_INVALID_OVERLAY
* Attempted to perform an add command that conflicted with previously
* existing files in the WIM when an overlay was attempted.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * An unknown operation type was specified in the update commands; or,
- * attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set
- * in the @p add_flags, but the same image had previously already been
- * added from an NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and
- * ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add
- * command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were
+ * An unknown operation type was specified in the update commands; or, both
+ * ::WIMLIB_ADD_FLAG_RPFIX and ::WIMLIB_ADD_FLAG_NORPFIX were specified in
+ * the @p add_flags for one add command; or ::WIMLIB_ADD_FLAG_RPFIX were
* specified in the @p add_flags for an add command in which @p
* wim_target_path was not the root directory of the WIM image.
* @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA
@@ -4302,6 +4323,8 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
* @retval ::WIMLIB_ERR_STAT
* While executing an add command, failed to get attributes for a file or
* directory.
+ * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG
+ * A capture configuration file could not be read.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update
* command, but wimlib was configured with the @c --without-ntfs-3g flag;