X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=df0ec28fa9ea9982af40d6588612aa5eaae00029;hb=3de1ec66f778edda19865482d685bc6f4e17faf7;hp=3cc833505072eaffb9590fb0a16a95b09dec4706;hpb=b4f0ab9002559b774407fb692bcc7e83a6c82ab7;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index 3cc83350..df0ec28f 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -9,50 +9,61 @@
* 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
*
- * @section sec_intro Introduction
- *
- * This is the documentation for the library interface of wimlib 1.7.0, a C
+ * This is the documentation for the library interface of wimlib 1.8.0, 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
- * program, please see the README file or manual pages.
+ * program, please see the manual pages and also the README
+ * file.
*
- * @section sec_installing_and_compiling Installing and Compiling
+ * @section sec_installing Installing
*
- * wimlib uses the GNU autotools, so, on UNIX-like systems, it should be easy to
- * install with configure && make && sudo make install
; however,
- * please see the README for more information about installing it.
+ * @subsection UNIX
*
- * To use wimlib in your program after installing it, include wimlib.h and link
- * your program with @c -lwim.
+ * Download the source code from http://sourceforge.net/projects/wimlib/files.
+ * Install the library by running configure && make && sudo make install.
+ * See the README for information about configuration options. To use wimlib in
+ * your program after installing it, include wimlib.h and link your program with
+ * -lwim.
*
- * As of wimlib 1.5.0, wimlib.h is also compatible with C++.
+ * @subsection Windows
*
- * Note: before calling any other function declared in wimlib.h,
- * wimlib_global_init() can (and in some cases, must) be called. See its
- * documentation for more details.
+ * Download the Windows binary distribution with the appropriate architecture
+ * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from http://sourceforge.net/projects/wimlib/files.
+ * Link your program with the libwim-15.dll file. Make sure to also download
+ * the source code so you can get wimlib.h, as it is not included in the binary
+ * distribution. If you need to access the DLL from other programming
+ * languages, note that the calling convention is "cdecl".
+ *
+ * @section sec_examples Examples
+ *
+ * Several examples are located in the examples
+ * directory of the source distribution.
+ *
+ * There is also the
+ * source code of wimlib-imagex, 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
*
@@ -88,6 +99,10 @@
* you can make multiple changes to a WIM and commit them all to the underlying
* file in only one overwrite operation, which is more efficient.
*
+ * Note: before calling any other function declared in wimlib.h,
+ * wimlib_global_init() can (and in some cases, must) be called. See its
+ * documentation for more details.
+ *
* @section sec_cleaning_up Cleaning up
*
* After you are done with any ::WIMStruct, you can call wimlib_free() to free
@@ -273,14 +288,16 @@
*
* @brief Mount and unmount WIM images.
*
- * On UNIX-like systems supporting FUSE (such as Linux), wimlib supports
- * mounting images from WIM files either read-only or read-write. To mount an
- * image, call wimlib_mount_image(). To unmount an image, call
- * wimlib_unmount_image(). Mounting can be done without root privileges because
- * it is implemented using FUSE (Filesystem in Userspace). If wimlib is
- * compiled with the --without-fuse
flag, these functions will be
- * available but will fail with ::WIMLIB_ERR_UNSUPPORTED. Note that mounting an
- * image read-write is an alternative to calling wimlib_update_image().
+ * On Linux, wimlib supports mounting images from WIM files either read-only or
+ * read-write. To mount an image, call wimlib_mount_image(). To unmount an
+ * image, call wimlib_unmount_image(). Mounting can be done without root
+ * privileges because it is implemented using FUSE (Filesystem in Userspace).
+ *
+ * If wimlib is compiled using the --without-fuse
flag, these
+ * functions will be available but will fail with ::WIMLIB_ERR_UNSUPPORTED.
+ *
+ * Note: if mounting is unsupported, wimlib still provides another way to modify
+ * a WIM image (wimlib_update_image()).
*/
/**
@@ -312,17 +329,17 @@
* @brief Write and overwrite on-disk WIM files.
*
* As described in @ref sec_basic_wim_handling_concepts, these functions are
- * critical to the design of the library as they allow new or modified WIMs to
- * actually be written to on-disk files. Generally, wimlib_write() is the
- * function you need to call to write a new WIM file, and wimlib_overwrite() is
- * the function you need to call to persistently update an existing WIM file.
+ * fundamental to the design of the library as they allow new or modified
+ * ::WIMStruct's to actually be written to on-disk files. Call wimlib_write()
+ * to write a new WIM file, or wimlib_overwrite() to persistently update an
+ * existing WIM file.
*/
/** @defgroup G_nonstandalone_wims Creating and handling non-standalone WIMs
*
* @brief Create and handle non-standalone WIMs, such as split and delta WIMs.
*
- * Normally, ::WIMStruct represents a WIM file, but there's a bit more to it
+ * Normally, a ::WIMStruct represents a WIM file, but there's a bit more to it
* than that. Normally, WIM files are "standalone". However, WIM files can
* also be arranged in non-standalone ways, such as a set of on-disk files that
* together form a single "split WIM" or "delta WIM". Such arrangements are
@@ -346,14 +363,20 @@
#include
#include
-/** @ingroup G_general
+#ifdef __GNUC__
+# define _wimlib_deprecated __attribute__((deprecated))
+#else
+# define _wimlib_deprecated
+#endif
+
+/** @addtogroup G_general
* @{ */
/** Major version of the library (for example, the 1 in 1.2.5). */
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 7
+#define WIMLIB_MINOR_VERSION 8
/** Patch version of the library (for example, the 5 in 1.2.5). */
#define WIMLIB_PATCH_VERSION 0
@@ -362,10 +385,6 @@
extern "C" {
#endif
-/** @} */
-/** @ingroup G_general
- * @{ */
-
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
* and need not correspond to a specific on-disk file. However, a ::WIMStruct
@@ -394,11 +413,13 @@ typedef char wimlib_tchar;
#endif
#ifdef __WIN32__
-/** Path separator for WIM paths passed back to progress callbacks. */
+/** Path separator for WIM paths passed back to progress callbacks.
+ * This is forward slash on UNIX and backslash on Windows. */
# define WIMLIB_WIM_PATH_SEPARATOR '\\'
# define WIMLIB_WIM_PATH_SEPARATOR_STRING L"\\"
#else
-/** Path separator for WIM paths passed back to progress callbacks. */
+/** Path separator for WIM paths passed back to progress callbacks.
+ * This is forward slash on UNIX and backslash on Windows. */
# define WIMLIB_WIM_PATH_SEPARATOR '/'
# define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
#endif
@@ -412,36 +433,99 @@ typedef char wimlib_tchar;
((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \
(path)[1] == 0)
-#ifdef __GNUC__
-# define _wimlib_deprecated __attribute__((deprecated))
-#else
-# define _wimlib_deprecated
-#endif
-
+/** Length of a Globally Unique Identifier (GUID) */
#define WIMLIB_GUID_LEN 16
/**
- * Specifies the compression type of a WIM file.
+ * Specifies a compression format. Pass one of these values to
+ * wimlib_create_new_wim(), wimlib_set_output_compression_type(),
+ * wimlib_create_compressor(), or wimlib_create_decompressor().
+ *
+ * A WIM file has one default compression type and chunk size. Normally, each
+ * resource in the WIM file is compressed with this compression type. However,
+ * resources may be stored as uncompressed; for example, wimlib will do so if a
+ * resource does not compress to less than its original size. In addition, a
+ * WIM with the new version number of 3584, or "ESD file", might contain solid
+ * blocks with different compression types.
*/
enum wimlib_compression_type {
- /** The WIM does not include any compressed resources. */
+ /**
+ * No compression.
+ *
+ * This is a valid argument to wimlib_create_new_wim() and
+ * wimlib_set_output_compression_type(), but not to the functions in the
+ * compression API such as wimlib_create_compressor().
+ */
WIMLIB_COMPRESSION_TYPE_NONE = 0,
- /** Compressed resources in the WIM use XPRESS compression. */
+ /**
+ * The XPRESS compression format. This format combines Lempel-Ziv
+ * factorization with Huffman encoding. Compression and decompression
+ * are both fast. This format supports chunk sizes that are powers of 2
+ * between 2^12 and 2^16, inclusively.
+ *
+ * wimlib's XPRESS 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).
+ * Non-default compression levels are also supported. For example,
+ * level 80 will enable two-pass optimal parsing, which is significantly
+ * slower but usually improves compression by several percent over the
+ * default level of 50.
+ *
+ * If using wimlib_create_compressor() to create an XPRESS compressor
+ * directly, the @p max_block_size parameter may be any positive value
+ * up to and including 2^16.
+ */
WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
- /** Compressed resources in the WIM use LZX compression. */
+ /**
+ * The LZX compression format. This format combines Lempel-Ziv
+ * factorization with Huffman encoding, but with more features and
+ * complexity than XPRESS. Compression is slow to somewhat fast,
+ * depending on the settings. Decompression is fast but slower than
+ * XPRESS. This format supports chunk sizes that are powers of 2
+ * between 2^15 and 2^21, inclusively. Note: chunk sizes
+ * other than 2^15 are not compatible with the Microsoft
+ * implementation.
+ *
+ * wimlib's LZX 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).
+ * Non-default compression levels are also supported. For example,
+ * level 20 will provide fast compression, almost as fast as XPRESS.
+ *
+ * If using wimlib_create_compressor() to create an LZX compressor
+ * directly, the @p max_block_size parameter may be any positive value
+ * up to and including 2^21.
+ */
WIMLIB_COMPRESSION_TYPE_LZX = 2,
- /** Compressed resources in the WIM use LZMS compression. Note: LZMS
- * compression is only compatible with wimlib v1.6.0 and later and with
- * WIMGAPI Windows 8 and later (and some restrictions apply on the
- * latter). */
+ /**
+ * The LZMS compression format. This format combines Lempel-Ziv
+ * factorization with adaptive Huffman encoding and range coding.
+ * Compression and decompression are both fairly slow. This format
+ * supports chunk sizes that are powers of 2 between 2^15 and
+ * 2^30, inclusively. This format is best used for large chunk
+ * sizes. Note: LZMS compression is only compatible with wimlib v1.6.0
+ * and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and
+ * later. Also, chunk sizes larger than 2^26 are not compatible
+ * with the Microsoft implementation.
+ *
+ * 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 and including 2^30.
+ */
WIMLIB_COMPRESSION_TYPE_LZMS = 3,
};
/** @} */
-/** @ingroup G_progress
+/** @addtogroup G_progress
* @{ */
/** Possible values of the first parameter to the user-supplied
@@ -461,6 +545,14 @@ enum wimlib_progress_msg {
* single extraction operation for optimization purposes. */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1,
+ /** This message may be sent periodically (not for every file) while
+ * files or directories are being created, prior to data stream
+ * extraction. @p info will point to ::wimlib_progress_info.extract.
+ * In particular, the @p current_file_count and @p end_file_count
+ * members may be used to track the progress of this phase of
+ * extraction. */
+ WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE = 3,
+
/** File data is currently being extracted. @p info will point to
* ::wimlib_progress_info.extract. This is the main message to track
* the progress of an extraction operation. */
@@ -470,6 +562,14 @@ enum wimlib_progress_msg {
* @p info will point to ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5,
+ /** This message may be sent periodically (not for every file) while
+ * file and directory metadata is being applied, following data stream
+ * extraction. @p info will point to ::wimlib_progress_info.extract.
+ * In particular, the @p current_file_count and @p end_file_count
+ * members may be used to track the progress of this phase of
+ * extraction. */
+ WIMLIB_PROGRESS_MSG_EXTRACT_METADATA = 6,
+
/** Confirms that the image has been successfully extracted. @p info
* will point to ::wimlib_progress_info.extract. This is paired with
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN. */
@@ -568,14 +668,70 @@ enum wimlib_progress_msg {
/** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and
* a file is being extracted normally (not as a WIMBoot "pointer file")
* due to it matching a pattern in the [PrepopulateList] section of the
- * configuration file \Windows\System32\WimBootCompress.ini in the WIM
- * image. @p info will point to ::wimlib_progress_info.wimboot_exclude.
+ * configuration file @c \\Windows\\System32\\WimBootCompress.ini in the
+ * WIM image. @p info will point to
+ * ::wimlib_progress_info.wimboot_exclude.
*/
WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24,
/** Starting to unmount a WIM image. @p info will point to
* ::wimlib_progress_info.unmount. */
WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25,
+
+ /** wimlib has used a file's data for the last time (including all data
+ * streams, if it has multiple). @p info will point to
+ * ::wimlib_progress_info.done_with_file. This message is only received
+ * if ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided. */
+ WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26,
+
+ /** wimlib_verify_wim() is starting to verify the metadata for an image.
+ * @p info will point to ::wimlib_progress_info.verify_image. */
+ WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE = 27,
+
+ /** wimlib_verify_wim() has finished verifying the metadata for an
+ * image. @p info will point to ::wimlib_progress_info.verify_image.
+ */
+ WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE = 28,
+
+ /** wimlib_verify_wim() is verifying stream integrity. @p info will
+ * point to ::wimlib_progress_info.verify_streams. */
+ WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29,
+
+ /**
+ * The progress function is being asked whether a file should be
+ * excluded from capture or not. @p info will point to
+ * ::wimlib_progress_info.test_file_exclusion. This is a bidirectional
+ * message that allows the progress function to set a flag if the file
+ * should be excluded.
+ *
+ * This message is only received if the flag
+ * ::WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION is used. This method for file
+ * exclusions is independent of the "capture configuration file"
+ * 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
@@ -595,7 +751,8 @@ enum wimlib_progress_status {
WIMLIB_PROGRESS_STATUS_ABORT = 1,
};
-/** A pointer to this union is passed to the user-supplied
+/**
+ * A pointer to this union is passed to the user-supplied
* ::wimlib_progress_func_t progress function. One (or none) of the structures
* contained in this union will be applicable for the operation
* (::wimlib_progress_msg) indicated in the first argument to the progress
@@ -786,7 +943,9 @@ union wimlib_progress_info {
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, and
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END.
*
@@ -844,10 +1003,11 @@ union wimlib_progress_info {
* potentially multiple streams per file (named data streams).
* A "stream" may be the default contents of a file, a named
* data stream, or a reparse data buffer. */
- uint64_t num_streams;
+ uint64_t total_streams;
- /** Reserved. */
- const wimlib_tchar *reserved_2;
+ /** Number of (not necessarily unique) streams that have been
+ * extracted so far. */
+ uint64_t completed_streams;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
@@ -860,6 +1020,30 @@ union wimlib_progress_info {
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
uint8_t guid[WIMLIB_GUID_LEN];
+
+ /** For ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE and
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, this is the
+ * number of files that have been processed so far. Once the
+ * corresponding phase of extraction is complete, this value
+ * will be equal to @c end_file_count. */
+ uint64_t current_file_count;
+
+ /** For ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE and
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, this is
+ * total number of files that will be processed.
+ *
+ * This number is provided for informational purposes only.
+ * This number will not necessarily be equal to the number of
+ * files actually being extracted. This is because extraction
+ * backends are free to implement an extraction algorithm that
+ * might be more efficient than processing every file in the
+ * "extract file structure" and "extract metadata" phases. For
+ * example, the current implementation of the UNIX extraction
+ * backend will create files on-demand during the stream
+ * extraction phase. Therefore, when using that particular
+ * extraction backend, @p end_file_count will only include
+ * directories and empty files. */
+ uint64_t end_file_count;
} extract;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_RENAME. */
@@ -979,6 +1163,89 @@ union wimlib_progress_info {
/** Flags passed to wimlib_unmount_image(). */
uint32_t unmount_flags;
} unmount;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE. */
+ struct wimlib_progress_info_done_with_file {
+ /* Path to the file whose data has been written to the WIM file,
+ * or is currently being asynchronously compressed in memory,
+ * and therefore is no longer needed by wimlib.
+ *
+ * WARNING: The file data will not actually be accessible in the
+ * WIM file until the WIM file has been completely written.
+ * Ordinarily you should not treat this message as a
+ * green light to go ahead and delete the specified file, since
+ * that would result in data loss if the WIM file cannot be
+ * successfully created for any reason.
+ *
+ * If a file has multiple names (hard links),
+ * ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE will only be received
+ * for one name. Also, this message will not be received for
+ * empty files or reparse points (or symbolic links), unless
+ * they have nonempty named data streams.
+ */
+ const wimlib_tchar *path_to_file;
+ } done_with_file;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE and
+ * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE. */
+ struct wimlib_progress_info_verify_image {
+ const wimlib_tchar *wimfile;
+ uint32_t total_images;
+ uint32_t current_image;
+ } verify_image;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS. */
+ struct wimlib_progress_info_verify_streams {
+ const wimlib_tchar *wimfile;
+ uint64_t total_streams;
+ uint64_t total_bytes;
+ uint64_t completed_streams;
+ uint64_t completed_bytes;
+ } verify_streams;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION. */
+ struct wimlib_progress_info_test_file_exclusion {
+
+ /**
+ * Path to the file for which exclusion is being tested.
+ *
+ * UNIX capture mode: The path will be a standard relative or
+ * absolute UNIX filesystem path.
+ *
+ * NTFS-3g capture mode: The path will be given relative to the
+ * root of the NTFS volume, with a leading slash.
+ *
+ * Windows capture mode: The path will be a Win32 namespace
+ * path to the file.
+ */
+ const wimlib_tchar *path;
+
+ /**
+ * Indicates whether the file or directory will be excluded from
+ * capture or not. This will be false by default. The
+ * progress function can set this to true if it decides
+ * that the file needs to be excluded.
+ */
+ 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 false by default; the progress function may
+ * set it to true.
+ */
+ bool will_ignore;
+ } handle_error;
};
/**
@@ -1005,7 +1272,7 @@ typedef enum wimlib_progress_status
void *progctx);
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** An array of these structures is passed to wimlib_add_image_multisource() to
@@ -1023,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
@@ -1050,8 +1318,10 @@ struct wimlib_capture_source {
#define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008
/** @} */
-/** @ingroup G_wim_information
- * @{ */
+
+/** @addtogroup G_wim_information */
+
+/** @{ */
/** General information about a WIM file. */
struct wimlib_wim_info {
@@ -1103,11 +1373,11 @@ struct wimlib_wim_info {
/** 1 if the WIM is considered readonly for any reason. */
uint32_t is_readonly : 1;
- /** 1 if reparse-point fixups are supposedly enabled for one or more
- * images in the WIM. */
+ /** 1 if reparse-point fixups are enabled for one or more images in the
+ * WIM. */
uint32_t has_rpfix : 1;
- /** 1 if the WIM is marked as read-only. */
+ /** 1 if the WIM is marked read-only. */
uint32_t is_marked_readonly : 1;
/** 1 if the WIM is part of a spanned set. */
@@ -1124,27 +1394,26 @@ 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;
/** Compressed size of the stream in bytes. This will be the same as @p
- * uncompressed_size if the stream is uncompressed. Or, if @p
- * is_packed_streams is 1, this will be 0. */
+ * uncompressed_size if the stream is uncompressed. Or, if @p packed is
+ * 1, this will be 0. */
uint64_t compressed_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;
/** SHA1 message digest of the stream's uncompressed contents. */
uint8_t sha1_hash[20];
- /** Which part number of the split WIM this stream is in. This should
- * be the same as the part number provided by wimlib_get_wim_info(). */
+ /** Which part of WIM this stream is in. */
uint32_t part_number;
/** Number of times this stream is referenced over all WIM images. */
@@ -1166,28 +1435,39 @@ 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 is_packed_streams is 1, then this will specify the compressed
- * size of the packed resource in the WIM. */
+ /** If @p packed is 1, then this will specify the compressed size of the
+ * solid resource in the WIM. */
uint64_t raw_resource_compressed_size;
- uint64_t reserved[2];
+ /** If @p packed is 1, then this will specify the uncompressed size of
+ * the solid resource in the WIM. */
+ uint64_t raw_resource_uncompressed_size;
+
+ uint64_t reserved[1];
};
-/** A stream of a file in the WIM. */
+/**
+ * Information about a stream of a particular file in the WIM.
+ *
+ * Normally, only WIM images captured from NTFS filesystems will have multiple
+ * streams per file. In practice, this is a rarely used feature of the
+ * filesystem.
+ */
struct wimlib_stream_entry {
/** Name of the stream, or NULL if the stream is unnamed. */
const wimlib_tchar *stream_name;
- /** Location, size, etc. of the stream within the WIM file. */
+ /** Location, size, and other information about the stream's data as
+ * stored in the WIM file. */
struct wimlib_resource_entry resource;
uint64_t reserved[4];
};
@@ -1197,15 +1477,16 @@ struct wimlib_stream_entry {
* entry ("dentry") because hard links are allowed. The hard_link_group_id
* field can be used to distinguish actual file inodes. */
struct wimlib_dir_entry {
- /** Name of the file, or NULL if this file is unnamed (only possible for
- * the root directory) */
+ /** Name of the file, or NULL if this file is unnamed. Only the root
+ * directory of an image will be unnamed. */
const wimlib_tchar *filename;
- /** 8.3 DOS name of this file, or NULL if this file has no such name.
- * */
+ /** 8.3 name (or "DOS name", or "short name") of this file; or NULL if
+ * this file has no such name. */
const wimlib_tchar *dos_name;
- /** Full path to this file within the WIM image. */
+ /** Full path to this file within the WIM image. Path separators will
+ * be ::WIMLIB_WIM_PATH_SEPARATOR. */
const wimlib_tchar *full_path;
/** Depth of this directory entry, where 0 is the root, 1 is the root's
@@ -1253,20 +1534,28 @@ struct wimlib_dir_entry {
#define WIMLIB_REPARSE_TAG_FILTER_MANAGER 0x8000000B
#define WIMLIB_REPARSE_TAG_WOF 0x80000017
#define WIMLIB_REPARSE_TAG_SYMLINK 0xA000000C
- /** If the file is a reparse point (FILE_ATTRIBUTE_DIRECTORY set in the
- * attributes), this will give the reparse tag. This tells you whether
- * the reparse point is a symbolic link, junction point, or some other,
- * more unusual kind of reparse point. */
+ /** If the file is a reparse point (FILE_ATTRIBUTE_REPARSE_POINT set in
+ * the attributes), this will give the reparse tag. This tells you
+ * whether the reparse point is a symbolic link, junction point, or some
+ * other, more unusual kind of reparse point. */
uint32_t reparse_tag;
- /* Number of (hard) links to this file. */
+ /** Number of links to this file's inode (hard links).
+ *
+ * Currently, this will always be 1 for directories. However, it can be
+ * greater than 1 for nondirectory files. */
uint32_t num_links;
- /** Number of named data streams that this file has. Normally 0. */
+ /** Number of named data streams this file has. Normally 0. */
uint32_t num_named_streams;
- /** Roughly, the inode number of this file. However, it may be 0 if
- * @p num_links == 1. */
+ /** A unique identifier for this file's inode. However, as a special
+ * case, if the inode only has a single link (@p num_links == 1), this
+ * value may be 0.
+ *
+ * Note: if a WIM image is captured from a filesystem, this value is not
+ * guaranteed to be the same as the original number of the inode on the
+ * filesystem. */
uint64_t hard_link_group_id;
/** Time this file was created. */
@@ -1278,20 +1567,43 @@ struct wimlib_dir_entry {
/** Time this file was last accessed. */
struct timespec last_access_time;
- /* UNIX data (wimlib extension), only valid if unix_mode != 0 */
+ /** The UNIX user ID of this file. This is a wimlib extension.
+ *
+ * This field is only valid if @p unix_mode != 0. */
uint32_t unix_uid;
+
+ /** The UNIX group ID of this file. This is a wimlib extension.
+ *
+ * This field is only valid if @p unix_mode != 0. */
uint32_t unix_gid;
+
+ /** The UNIX mode of this file. This is a wimlib extension.
+ *
+ * If this field is 0, then @p unix_uid, @p unix_gid, @p unix_mode, and
+ * @p unix_rdev are all unknown (fields are not present in the WIM
+ * image). */
uint32_t unix_mode;
+
+ /** The UNIX device ID (major and minor number) of this file. This is a
+ * wimlib extension.
+ *
+ * This field is only valid if @p unix_mode != 0. */
uint32_t unix_rdev;
uint64_t reserved[14];
- /** Array of streams that make up this file. The first entry will
- * always exist and will correspond to the unnamed data stream (default
- * file contents), so it will have @p stream_name == @c NULL. There
- * will then be @p num_named_streams additional entries that specify the
- * named data streams, if any, each of which will have @p stream_name !=
- * @c NULL. */
+ /**
+ * Array of streams that make up this file.
+ *
+ * The first entry will always exist and will correspond to the unnamed
+ * data stream (default file contents), so it will have stream_name
+ * == NULL. Alternatively, for reparse point files, the first entry
+ * will corresponding to the reparse data stream.
+ *
+ * Then, following the first entry, there be @p num_named_streams
+ * additional entries that specify the named data streams, if any, each
+ * of which will have stream_name != NULL.
+ */
struct wimlib_stream_entry streams[];
};
@@ -1326,15 +1638,21 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
-/** Directly capture an NTFS volume rather than a generic directory. This flag
- * cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
+/** UNIX-like systems only: Directly capture an NTFS volume rather than a
+ * generic directory. This requires that wimlib was compiled with support for
+ * libntfs-3g.
+ *
+ * This flag cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA.
+ *
+ * Do not use this flag on Windows, where wimlib already supports all
+ * Windows-native filesystems, including NTFS, through the Windows APIs. */
#define WIMLIB_ADD_FLAG_NTFS 0x00000001
-/** Follow symlinks; archive and dump the files they point to. Currently only
+/** Follow symbolic links when scanning the directory tree. Currently only
* supported on UNIX-like systems. */
#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
@@ -1343,65 +1661,72 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* scanned. */
#define WIMLIB_ADD_FLAG_VERBOSE 0x00000004
-/** Mark the image being added as the bootable image of the WIM. Not valid for
- * wimlib_update_image(). */
+/** Mark the image being added as the bootable image of the WIM. This flag is
+ * valid only for wimlib_add_image() and wimlib_add_image_multisource().
+ *
+ * Note that you can also change the bootable image of a WIM using
+ * wimlib_set_wim_info().
+ *
+ * Note: ::WIMLIB_ADD_FLAG_BOOT does something different from, and independent
+ * from, ::WIMLIB_ADD_FLAG_WIMBOOT. */
#define WIMLIB_ADD_FLAG_BOOT 0x00000008
/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID
- * (major and minor number) of each file. See the documentation for the
+ * (major and minor number) of each file. Also allows capturing special files
+ * such as device nodes and FIFOs. See the documentation for the
* --unix-data option to wimlib-imagex capture for more
* information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
- * mode, or in Windows native builds. */
+ * mode, or in Windows native builds. */
#define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020
/** Fail immediately if the full security descriptor of any file or directory
* cannot be accessed. Only has an effect in Windows native builds. The
* default behavior without this flag is to first try omitting the SACL from the
* security descriptor, then to try omitting the security descriptor entirely.
- * */
+ */
#define WIMLIB_ADD_FLAG_STRICT_ACLS 0x00000040
/** Call the progress function with the message
* ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from
* capture. This is a subset of the messages provided by
- * ::WIMLIB_ADD_FLAG_VERBOSE. */
+ * ::WIMLIB_ADD_FLAG_VERBOSE. */
#define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE 0x00000080
-/** Reparse-point fixups: Modify absolute symbolic links (or junction points,
- * in the case of Windows) that point inside the directory being captured to
- * instead be absolute relative to the directory being captured, rather than the
- * current root.
+/** Reparse-point fixups: Modify absolute symbolic links (and junctions, in the
+ * case of Windows) that point inside the directory being captured to instead be
+ * absolute relative to the directory being captured.
*
- * Without this flag, the default is to do this if WIM_HDR_FLAG_RP_FIX is set in
- * the WIM header or if this is the first image being added.
- * WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is captured with
- * reparse point fixups enabled and currently cannot be unset. */
+ * Without this flag, the default is to do reparse-point fixups if
+ * WIM_HDR_FLAG_RP_FIX is set in the WIM header or if this is the first image
+ * being added. WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is
+ * captured with reparse point fixups enabled and currently cannot be unset. */
#define WIMLIB_ADD_FLAG_RPFIX 0x00000100
-/** Don't do reparse point fixups. The default behavior is described in the
- * documentation for ::WIMLIB_ADD_FLAG_RPFIX. */
+/** Don't do reparse point fixups. See ::WIMLIB_ADD_FLAG_RPFIX. */
#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200
/** Do not automatically exclude unsupported files or directories from capture;
* e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on
- * UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
- * such a file is encountered. */
+ * UNIX-like systems when not also using ::WIMLIB_ADD_FLAG_UNIX_DATA. Instead,
+ * fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered. */
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
/**
* Automatically select a capture configuration appropriate for capturing
* filesystems containing Windows operating systems. For example,
- * "pagefile.sys" and "System Volume Information" will be excluded.
+ * "/pagefile.sys" and "System Volume Information" will be excluded.
*
- * When this flag is specified, the corresponding @p config parameter or member
- * must be @c NULL.
+ * When this flag is specified, the corresponding @p config parameter (for
+ * wimlib_add_image()) or member (for wimlib_update_image()) must be @c NULL.
+ * Otherwise, ::WIMLIB_ERR_INVALID_PARAM will be returned.
*
- * Note that the default behavior--- that is, when this flag is not specified
- * and @p config is @c NULL--- is to use no capture configuration, meaning that
- * no files are excluded from capture.
+ * Note that the default behavior--- that is, when neither
+ * ::WIMLIB_ADD_FLAG_WINCONFIG nor ::WIMLIB_ADD_FLAG_WIMBOOT is specified and @p
+ * config is @c NULL--- is to use no capture configuration, meaning that no
+ * files are excluded from capture.
*/
#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
@@ -1423,6 +1748,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*
* since that makes access to the data faster (at the cost of a worse
* compression ratio compared to the 32768-byte LZX chunks usually used).
+ *
+ * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and
+ * independent from, ::WIMLIB_ADD_FLAG_BOOT.
*/
#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
@@ -1435,6 +1763,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000
+/**
+ * Send ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress
+ * function.
+ *
+ * Note: This method for file exclusions is independent from the capture
+ * configuration file mechanism.
+ */
+#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
@@ -1452,7 +1791,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** Do not issue an error if the path to delete does not exist. */
@@ -1463,7 +1802,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/**
@@ -1491,8 +1830,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* Mark each exported image as WIMBoot-compatible.
*
* Note: by itself, this does change the destination WIM's compression type, nor
- * does it add the file \Windows\System32\WimBootCompress.ini in the WIM image.
- * Before writing the destination WIM, it's recommended to do something like:
+ * does it add the file @c \\Windows\\System32\\WimBootCompress.ini in the WIM
+ * image. Before writing the destination WIM, it's recommended to do something
+ * like:
*
* \code
* wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS);
@@ -1504,7 +1844,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010
/** @} */
-/** @ingroup G_extracting_wims
+/** @addtogroup G_extracting_wims
* @{ */
/** Extract the image directly to an NTFS volume rather than a generic directory.
@@ -1556,29 +1896,39 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** Instead of ignoring files and directories with names that cannot be
* represented on the current platform (note: Windows has more restrictions on
* filenames than POSIX-compliant systems), try to replace characters or append
- * junk to the names so that they can be extracted in some form. */
+ * junk to the names so that they can be extracted in some form.
+ *
+ * Note: this flag is unlikely to have any effect when extracting a WIM image
+ * that was captured on Windows.
+ */
#define WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES 0x00000800
/** On Windows, when there exist two or more files with the same case
* insensitive name but different case sensitive names, try to extract them all
* by appending junk to the end of them, rather than arbitrarily extracting only
- * one. */
+ * one.
+ *
+ * Note: this flag is unlikely to have any effect when extracting a WIM image
+ * that was captured on Windows.
+ */
#define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000
-/** Do not ignore failure to set timestamps on extracted files. */
+/** Do not ignore failure to set timestamps on extracted files. This flag
+ * currently only has an effect when extracting to a directory on UNIX-like
+ * systems. */
#define WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000
-/** Do not ignore failure to set short names on extracted files. */
+/** Do not ignore failure to set short names on extracted files. This flag
+ * currently only has an effect on Windows. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000
-/** On Windows, do not ignore failure to extract symbolic links and junctions
- * due to permissions problems. By default, such failures are ignored since the
- * default configuration of Windows only allows the Administrator to create
- * symbolic links. */
+/** Do not ignore failure to extract symbolic links and junctions due to
+ * permissions problems. This flag currently only has an effect on Windows. By
+ * default, such failures are ignored since the default configuration of Windows
+ * only allows the Administrator to create symbolic links. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
-/** TODO: this flag is intended to allow resuming an aborted extraction, but the
- * behavior is currently less than satisfactory. Do not use (yet). */
+/** Reserved for future use. */
#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the
@@ -1586,10 +1936,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* wildcard characters @c ? and @c *. The @c ? character matches any
* non-path-separator character, whereas the @c * character matches zero or more
* non-path-separator characters. Consequently, each glob may match zero or
- * more actual paths in the WIM image. By default, if a glob does not match any
- * files, a warning but not an error will be issued, even if the glob did not
- * actually contain wildcard characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB
- * to get an error instead. */
+ * more actual paths in the WIM image.
+ *
+ * By default, if a glob does not match any files, a warning but not an error
+ * will be issued. This is the case even if the glob did not actually contain
+ * wildcard characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error
+ * instead.
+ * */
#define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000
/** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error
@@ -1597,28 +1950,34 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* one of the provided globs did not match a file. */
#define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000
-/** Do not extract Windows file attributes such as readonly, hidden, etc. */
+/** Do not extract Windows file attributes such as readonly, hidden, etc.
+ *
+ * This flag has an effect on Windows as well as in the NTFS-3g extraction mode.
+ */
#define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not
* preserve the directory structure of the archive when extracting --- that is,
* place each extracted file or directory tree directly in the target directory.
- */
+ *
+ * The target directory will still be created if it does not already exist. */
#define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000
-/** Windows only: Extract files as "pointers" back to the WIM archive. See the
- * documentation for the --wimboot option of wimlib-imagex apply
- * for more information. */
+/** Windows only: Extract files as "pointers" back to the WIM archive.
+ *
+ * The effects of this option are fairly complex. See the documentation for the
+ * --wimboot option of wimlib-imagex apply for more information.
+ */
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
/** @} */
-/** @ingroup G_mounting_wim_images
+/** @addtogroup G_mounting_wim_images
* @{ */
/** Mount the WIM image read-write rather than the default of read-only. */
#define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001
-/** Enable FUSE debugging by passing the @c -d flag to @c fuse_main().*/
+/** Enable FUSE debugging by passing the @c -d option to @c fuse_main(). */
#define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002
/** Do not allow accessing named data streams in the mounted WIM image. */
@@ -1638,36 +1997,37 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020
/** Allow other users to see the mounted filesystem. This passes the @c
- * allow_other option to the FUSE mount. */
+ * allow_other option to fuse_main(). */
#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040
/** @} */
-/** @ingroup G_creating_and_opening_wims
+/** @addtogroup G_creating_and_opening_wims
* @{ */
/** Verify the WIM contents against the WIM's integrity table, if present. This
* causes the raw data of the WIM file, divided into 10 MB chunks, to be
* checksummed and checked against the SHA1 message digests specified in the
- * integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any
- * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the
- * integrity table is invalid). */
+ * integrity table. If there are any mismatches, ::WIMLIB_ERR_INTEGRITY is
+ * issued. If the WIM file does not contain an integrity table, this flag has
+ * no effect. */
#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001
-/** Issue an error if the WIM is part of a split WIM. Software can provide
- * this flag for convenience if it explicitly does not want to support split
- * WIMs. */
+/** Issue an error (::WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split
+ * WIM. Software can provide this flag for convenience if it explicitly does
+ * not want to support split WIMs. */
#define WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002
-/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it
- * is not. A WIM is considered writable 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. */
+/** Check if the WIM is writable and issue an error
+ * (::WIMLIB_ERR_WIM_IS_READONLY) if it is not. A WIM is considered writable
+ * 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 immediately rather
+ * than potentially much later, when wimlib_overwrite() is finally called. */
#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
/** @} */
-/** @ingroup G_mounting_wim_images
+/** @addtogroup G_mounting_wim_images
* @{ */
/** Provide ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image.
@@ -1703,7 +2063,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
@@ -1711,7 +2071,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001
/** @} */
-/** @ingroup G_writing_and_overwriting_wims
+/** @addtogroup G_writing_and_overwriting_wims
* @{ */
/**
@@ -1734,9 +2094,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/**
* Write the WIM as "pipable". After writing a WIM with this flag specified,
* images from it can be applied directly from a pipe using
- * wimlib_extract_image_from_pipe(). See the documentation for the --pipable
- * flag of `wimlib-imagex capture' for more information. Beware: WIMs written
- * with this flag will not be compatible with Microsoft's software.
+ * wimlib_extract_image_from_pipe(). See the documentation for the
+ * --pipable option of wimlib-imagex capture for more information.
+ * Beware: WIMs written with this flag will not be compatible with Microsoft's
+ * software.
*
* For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to
* write the WIM as pipable if and only if it was pipable before. For
@@ -1757,16 +2118,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* from which an image has been exported using wimlib_export_image()).
*
* ::WIMLIB_WRITE_FLAG_RECOMPRESS can be used to recompress with a higher
- * compression ratio for the same compression type and chunk size. wimlib's LZX
- * compressor currently can be given different parameters in order to achieve
- * different balances between compression ratio and time. In its default mode
- * as of v1.5.3, it usually compresses slightly better than the competing
- * Microsoft implementation.
- *
- * ::WIMLIB_WRITE_FLAG_RECOMPRESS can also 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.)
+ * compression ratio for the same compression type and chunk size. Simply using
+ * the default compression settings may suffice for this, especially if the WIM
+ * file was created using another program/library that may not use as
+ * sophisticated compression algorithms. Or,
+ * wimlib_set_default_compression_level() can be called beforehand to set an
+ * even higher compression level than the default.
+ *
+ * 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 not cause recompression of streams
* that would not otherwise be written. For example, a call to
@@ -1780,18 +2142,26 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/**
* Immediately before closing the WIM file, sync its data to disk.
*
+ * This flag forces the function to wait until the data is safely on disk before
+ * returning success. Otherwise, modern operating systems tend to cache data
+ * for some time (in some cases, 30+ seconds) before actually writing it to
+ * disk, even after reporting to the application that the writes have succeeded.
+ *
* wimlib_overwrite() will set this flag automatically if it decides to
- * overwrite the WIM file via a temporary file instead of in-place.
+ * overwrite the WIM file via a temporary file instead of in-place. This is
+ * necessary on POSIX systems; it will, for example, avoid problems with delayed
+ * allocation on ext4.
*/
#define WIMLIB_WRITE_FLAG_FSYNC 0x00000020
/**
* For wimlib_overwrite(), rebuild the entire WIM file, even if it otherwise
- * could be updated merely be appending to it.
+ * could be updated in-place by appending to it.
*
* When rebuilding the WIM file, stream reference counts will be recomputed, and
* any streams with 0 reference count (e.g. from deleted files or images) will
- * not be included in the resulting WIM file.
+ * not be included in the resulting WIM file. This can free up space that is
+ * currently not being used.
*
* This flag can be combined with ::WIMLIB_WRITE_FLAG_RECOMPRESS to force all
* data to be recompressed. Otherwise, compressed data is re-used if possible.
@@ -1852,8 +2222,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.
*
@@ -1867,26 +2237,46 @@ 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
+ * 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
+ * file. This is only needed in the unusual case that the library user needs to
+ * know exactly when wimlib has read each file for the last time.
+ */
+#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
/** @} */
-/** @ingroup G_general
+/** @addtogroup G_general
* @{ */
/** Assume that strings are represented in UTF-8, even if this is not the
@@ -1926,7 +2316,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020
/** @} */
-/** @ingroup G_nonstandalone_wims
+/** @addtogroup G_nonstandalone_wims
* @{ */
/** For wimlib_reference_resource_files(), enable shell-style filename globbing.
@@ -1943,7 +2333,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002
/** @} */
-/** @ingroup G_modifying_wims
+/** @addtogroup G_modifying_wims
* @{ */
/** The specific type of update to perform. */
@@ -2016,7 +2406,7 @@ struct wimlib_update_command {
};
/** @} */
-/** @ingroup G_general
+/** @addtogroup G_general
* @{ */
/**
@@ -2100,6 +2490,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,
};
@@ -2139,10 +2530,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,
@@ -2167,8 +2554,7 @@ wimlib_add_empty_image(WIMStruct *wim,
* any) until wimlib_write() or wimlib_overwrite() is called.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file to which the image will be
- * added.
+ * Pointer to the ::WIMStruct to which to add the image.
* @param source
* A path to a directory or unmounted NTFS volume that will be captured as
* a WIM image.
@@ -2263,9 +2649,15 @@ wimlib_add_tree(WIMStruct *wim, int image,
* @param ctype
* The type of compression to be used in the new WIM file, as one of the
* ::wimlib_compression_type constants.
+ *
+ * This choice is not necessarily final; if desired, it can still be
+ * changed at any time before the WIM is written to disk, using
+ * wimlib_set_output_compression_type(). In addition, if you wish to use a
+ * non-default chunk size, you will need to call
+ * wimlib_set_output_chunk_size().
* @param wim_ret
* On success, a pointer to an opaque ::WIMStruct for the new WIM file is
- * written to the memory location pointed to by this paramater. The
+ * written to the memory location pointed to by this parameter. The
* ::WIMStruct must be freed using using wimlib_free() when finished with
* it.
* @return 0 on success; nonzero on error.
@@ -2282,12 +2674,8 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
*
* Deletes an image, or all images, from a WIM file.
*
- * All streams referenced by the image(s) being deleted are removed from the
- * lookup table of the WIM if they are not referenced by any other images in the
- * WIM.
- *
- * Please note that @b no changes are committed to the underlying WIM file (if
- * any) until wimlib_write() or wimlib_overwrite() is called.
+ * Note: no changes are committed to the underlying WIM file (if any) until
+ * wimlib_write() or wimlib_overwrite() is called.
*
* @param wim
* Pointer to the ::WIMStruct for the WIM file that contains the image(s)
@@ -2295,6 +2683,7 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
* @param image
* The number of the image to delete, or ::WIMLIB_ALL_IMAGES to delete all
* images.
+ *
* @return 0 on success; nonzero on failure. On failure, @p wim is guaranteed
* to be left unmodified only if @p image specified a single image. If instead
* @p image was ::WIMLIB_ALL_IMAGES and @p wim contained more than one image, it's
@@ -2303,10 +2692,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,
@@ -2337,13 +2722,9 @@ wimlib_delete_path(WIMStruct *wim, int image,
*
* The destination image is made to share the same dentry tree and security data
* structure as the source image. This places some restrictions on additional
- * functions that may be called. wimlib_mount_image() may not be called on
- * either the source image or the destination image without an intervening call
- * to a function that un-shares the images, such as wimlib_free() on @p
- * dest_wim, or wimlib_delete_image() on either the source or destination image.
- * Furthermore, you may not call wimlib_free() on @p src_wim before calling
- * wimlib_write() or wimlib_overwrite() on @p dest_wim because @p dest_wim will
- * have references back to @p src_wim.
+ * functions that may be called. For example, you may not call wimlib_free() on
+ * @p src_wim before calling wimlib_write() or wimlib_overwrite() on @p dest_wim
+ * because @p dest_wim will have references back to @p src_wim.
*
* If this function fails, all changes to @p dest_wim are rolled back.
*
@@ -2401,10 +2782,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,
@@ -2430,8 +2807,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
* controllable by the @p extract_flags parameter, but there also are
* differences depending on the platform (UNIX-like vs Windows). See the manual
* page for wimlib-imagex apply for more information, including about the
- * special "NTFS volume extraction mode" entered by providing
- * ::WIMLIB_EXTRACT_FLAG_NTFS.
+ * NTFS-3g extraction mode.
*
* @param wim
* The WIM from which to extract the image(s), specified as a pointer to
@@ -2443,7 +2819,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
* @param image
* The image to extract, specified as either the 1-based index of a single
* image to extract, or ::WIMLIB_ALL_IMAGES to specify that all images are
- * to be extracted. ::WIMLIB_ALL_IMAGES cannot be used if
+ * to be extracted. However, ::WIMLIB_ALL_IMAGES cannot be used if
* ::WIMLIB_EXTRACT_FLAG_NTFS is specified in @p extract_flags.
* @param target
* Directory to extract the WIM image(s) to; or, with
@@ -2460,10 +2836,11 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
* @retval ::WIMLIB_ERR_INVALID_PARAM
* The extraction flags were invalid; more details may be found in the
* documentation for the specific extraction flags that were specified. Or
- * @p target was @c NULL or the empty string, or @p wim was @c NULL.
+ * @p target was @c NULL or an empty string, or @p wim was @c NULL.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
* The SHA1 message digest of an extracted stream did not match the SHA1
- * message digest given in the WIM.
+ * message digest given in the WIM. In other words, the WIM file is
+ * corrupted, so the data cannot be extracted in its original form.
* @retval ::WIMLIB_ERR_LINK
* Failed to create a symbolic link or a hard link.
* @retval ::WIMLIB_ERR_METADATA_NOT_FOUND
@@ -2488,22 +2865,20 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
* @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
* One of the files or directories that needed to be extracted referenced a
* stream not present in the WIM's lookup table (or in any of the lookup
- * tables of the split WIM parts).
+ * tables of the split WIM parts). This can happen if the WIM is not
+ * standalone and the necessary resource WIMs, or split WIM parts, were not
+ * referenced with wimlib_reference_resource_files().
* @retval ::WIMLIB_ERR_SET_ATTRIBUTES
* Failed to set attributes on a file.
* @retval ::WIMLIB_ERR_SET_REPARSE_DATA
* Failed to set reparse data on a file (only if reparse data was supported
* by the extraction mode).
* @retval ::WIMLIB_ERR_SET_SECURITY
- * Failed to set security descriptor on a file
- * (only if ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS was specified in @p
- * extract_flags).
+ * Failed to set security descriptor on a file.
* @retval ::WIMLIB_ERR_SET_SHORT_NAME
- * Failed to set the short name of a file (only if
- * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES was specified in @p extract_flags).
+ * Failed to set the short name of a file.
* @retval ::WIMLIB_ERR_SET_TIMESTAMPS
- * Failed to set timestamps on a file (only if
- * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS was specified in @p extract_flags).
+ * Failed to set timestamps on a file.
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
* Unexpected end-of-file occurred when reading data from the WIM.
* @retval ::WIMLIB_ERR_UNSUPPORTED
@@ -2529,7 +2904,9 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
*
* If a progress function is registered with @p wim, then as each image is
* extracted it will receive ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, then
- * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then
+ * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE messages, then zero
+ * or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then zero or more
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, then
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END.
*/
extern int
@@ -2539,11 +2916,10 @@ wimlib_extract_image(WIMStruct *wim, int image,
/**
* @ingroup G_extracting_wims
*
- * Since wimlib v1.5.0: Extract one image from a pipe on which a pipable WIM is
- * being sent.
+ * Extract one image from a pipe on which a pipable WIM is being sent.
*
- * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
- * about pipable WIMs.
+ * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE, and @ref
+ * subsec_pipable_wims, for more information about pipable WIMs.
*
* This function operates in a special way to read the WIM fully sequentially.
* As a result, there is no ::WIMStruct is made visible to library users, and
@@ -2573,7 +2949,7 @@ wimlib_extract_image(WIMStruct *wim, int image,
* @retval ::WIMLIB_ERR_INVALID_PIPABLE_WIM
* Data read from the pipable WIM was invalid.
* @retval ::WIMLIB_ERR_NOT_PIPABLE
- * The WIM being piped in a @p pipe_fd is a normal WIM, not a pipable WIM.
+ * The WIM being piped over @p pipe_fd is a normal WIM, not a pipable WIM.
*/
extern int
wimlib_extract_image_from_pipe(int pipe_fd,
@@ -2600,17 +2976,18 @@ wimlib_extract_image_from_pipe_with_progress(int pipe_fd,
/**
* @ingroup G_extracting_wims
*
- * Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to
- * extract from the WIM image are specified in the UTF-8 text file named by @p
+ * Similar to wimlib_extract_paths(), but the paths to extract from the WIM
+ * image are specified in the ASCII, UTF-8, or UTF-16LE text file named by @p
* path_list_file which itself contains the list of paths to use, one per line.
- * Leading and trailing whitespace, and otherwise empty lines and lines
- * beginning with the ';' character are ignored. No quotes are needed as paths
- * are otherwise delimited by the newline character.
+ * Leading and trailing whitespace is ignored. Empty lines and lines beginning
+ * with the ';' or '#' characters are ignored. No quotes are needed, as paths
+ * are otherwise delimited by the newline character. However, quotes will be
+ * stripped if present.
*
* The error codes are the same as those returned by wimlib_extract_paths(),
* except that wimlib_extract_pathlist() returns an appropriate error code if it
- * cannot read the path list file (::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
- * ::WIMLIB_ERR_READ, ::WIMLIB_ERR_NOMEM, or ::WIMLIB_ERR_INVALID_UTF8_STRING).
+ * cannot read the path list file (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
+ * ::WIMLIB_ERR_READ).
*/
extern int
wimlib_extract_pathlist(WIMStruct *wim, int image,
@@ -2621,8 +2998,8 @@ wimlib_extract_pathlist(WIMStruct *wim, int image,
/**
* @ingroup G_extracting_wims
*
- * Since wimlib v1.6.0: Extract zero or more paths (files or directory trees)
- * from the specified WIM image.
+ * Extract zero or more paths (files or directory trees) from the specified WIM
+ * image.
*
* By default, each path will be extracted to a corresponding subdirectory of
* the target based on its location in the WIM image. For example, if one of
@@ -2650,8 +3027,9 @@ wimlib_extract_pathlist(WIMStruct *wim, int image,
* file or directory within the WIM image. Separators may be either
* forwards or backwards slashes, and leading path separators are optional.
* The paths will be interpreted either case-sensitively (UNIX default) or
- * case-insensitively (Windows default); this can be changed by
- * wimlib_global_init().
+ * case-insensitively (Windows default); however, the behavior can be
+ * configured explicitly at library initialization time by passing an
+ * appropriate flag to wimlib_global_init().
*
* By default, the characters @c * and @c ? are interpreted literally.
* This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p
@@ -2675,9 +3053,6 @@ wimlib_extract_pathlist(WIMStruct *wim, int image,
* as those returned by wimlib_extract_image(). Below, some of the error codes
* returned in situations specific to path-mode extraction are documented:
*
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image was ::WIMLIB_ALL_IMAGES or was otherwise not a valid single
- * image in the WIM.
* @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST
* One of the paths to extract did not exist in the WIM image. This error
* code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not
@@ -2712,8 +3087,8 @@ wimlib_extract_paths(WIMStruct *wim,
* See wimlib_get_xml_data() to read the XML data into memory instead.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file, which does not necessarily
- * have to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param fp
* @c stdout, or a FILE* opened for writing, to extract the data to.
*
@@ -2721,9 +3096,11 @@ wimlib_extract_paths(WIMStruct *wim,
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p wim is not a ::WIMStruct that was created by wimlib_open_wim().
* @retval ::WIMLIB_ERR_NOMEM
+ * Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_READ
+ * Error reading the XML data from the WIM file.
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
- * Failed to read the XML data from the WIM.
+ * Error reading the XML data from the WIM file.
* @retval ::WIMLIB_ERR_WRITE
* Failed to completely write the XML data to @p fp.
*/
@@ -2737,7 +3114,7 @@ wimlib_extract_xml_data(WIMStruct *wim, FILE *fp);
* with it.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file.
+ * Pointer to the ::WIMStruct to free.
*
* @return This function has no return value.
*/
@@ -2768,8 +3145,9 @@ wimlib_get_compression_type_string(int ctype);
* The error code returned by one of wimlib's functions.
*
* @return
- * Pointer to a statically allocated string describing the error code,
- * or @c NULL if the error code is not valid.
+ * Pointer to a statically allocated string describing the error code. If
+ * the error code is for some reason not recognized by the library, the
+ * string will be "Unknown error".
*/
extern const wimlib_tchar *
wimlib_get_error_string(enum wimlib_error_code code);
@@ -2780,8 +3158,8 @@ wimlib_get_error_string(enum wimlib_error_code code);
* Returns the description of the specified image.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param image
* The number of the image, numbered starting at 1.
*
@@ -2801,8 +3179,8 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
* Returns the name of the specified image.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param image
* The number of the image, numbered starting at 1.
*
@@ -2824,7 +3202,7 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
* bits contain the patch version.
*
* In other words, the returned value is equal to ((WIMLIB_MAJOR_VERSION
- * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)
for the
+ * << 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION) for the
* corresponding header file.
*/
extern uint32_t
@@ -2836,8 +3214,8 @@ wimlib_get_version(void);
* Get basic information about a WIM file.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param info
* A ::wimlib_wim_info structure that will be filled in with information
* about the WIM file.
@@ -2857,8 +3235,8 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info);
* instead.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file, which does not necessarily
- * have to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param buf_ret
* On success, a pointer to an allocated buffer containing the raw UTF16-LE
* XML data is written to this location.
@@ -2915,7 +3293,8 @@ wimlib_global_cleanup(void);
* Determines if an image name is already used by some image in the WIM.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file.
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param name
* The name to check.
*
@@ -2998,8 +3377,8 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path,
* explicitly referenced.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file that does not necessarily have
- * to be standalone (e.g. it could be part of a split WIM).
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
*
* @param flags
* Reserved; set to 0.
@@ -3104,7 +3483,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms,
* ::WIMLIB_MOUNT_FLAG_READWRITE is not specified in @p mount_flags. If
* left @c NULL, the staging directory is created in the same directory as
* the WIM file that @p wim was originally read from. The staging
- * directory is deleted when the image is unmounted.
+ * directory is automatically deleted when the image is unmounted.
*
* @return 0 on success; nonzero on error. The possible error codes include:
*
@@ -3116,7 +3495,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms,
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not specify an existing, single image in @p wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p wim was @c NULL; or @p dir was NULL or the empty string; or an
+ * @p wim was @c NULL; or @p dir was NULL or an empty string; or an
* unrecognized flag was specified in @p mount_flags; or the WIM image has
* already been modified in memory (e.g. by wimlib_update_image()).
* @retval ::WIMLIB_ERR_MKDIR
@@ -3127,9 +3506,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms,
* WIM file is considered read-only because of any of the reasons mentioned
* in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_UNSUPPORTED
- * Mounting is not supported, either because the platform is Windows, or
- * because the platform is UNIX-like and wimlib was compiled using
- * --without-fuse
.
+ * Mounting is not supported in this build of the library.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
@@ -3177,60 +3554,62 @@ wimlib_mount_image(WIMStruct *wim,
* @param wim_ret
* On success, a pointer to an opaque ::WIMStruct for the opened WIM file
* is written to the memory location pointed to by this parameter. The
- * ::WIMStruct can be freed using using wimlib_free() when finished with
+ * ::WIMStruct must be freed using using wimlib_free() when finished with
* it.
*
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_IMAGE_COUNT
- * The WIM is not the non-first part of a split WIM, and the number of
- * metadata resources found in the WIM did not match the image count given
- * in the WIM header, or the number of <IMAGE> elements in the XML
- * data for the WIM did not match the image count given in the WIM header.
+ * The number of metadata resources found in the WIM did not match the
+ * image count specified in the WIM header, or the number of <IMAGE>
+ * elements in the XML data of the WIM did not match the image count
+ * specified in the WIM header.
* @retval ::WIMLIB_ERR_INTEGRITY
- * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p
- * wim_file contains an integrity table, but the SHA1 message digest for a
- * chunk of the WIM does not match the corresponding message digest given
- * in the integrity table.
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and
+ * the WIM contained an integrity table, but the SHA1 message digest for a
+ * chunk of the WIM did not match the corresponding value in the integrity
+ * table.
* @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE
- * Resources in @p wim_file are compressed, but the chunk size was invalid
- * for the WIM's compression type.
+ * The library did not recognize the compression chunk size of the WIM as
+ * valid for its compression type.
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * The header of @p wim_file says that resources in the WIM are compressed,
- * but the header flag for a recognized compression type is not set.
+ * The library did not recognize the compression type of the WIM.
* @retval ::WIMLIB_ERR_INVALID_HEADER
- * The header of @p wim_file was otherwise invalid.
+ * The header of the WIM was otherwise invalid.
* @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE
- * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p
- * wim_file contains an integrity table, but the integrity table is
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and
+ * the WIM contained an integrity table, but the integrity table was
* invalid.
* @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY
- * The lookup table for the WIM was invalid.
+ * The lookup table of the WIM was invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p wim_ret was @c NULL.
+ * @p wim_ret was @c NULL; or, @p wim_file was not a nonempty string.
* @retval ::WIMLIB_ERR_IS_SPLIT_WIM
- * @p wim_file is a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was
+ * The WIM was a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was
* specified in @p open_flags.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocated needed memory.
* @retval ::WIMLIB_ERR_NOT_A_WIM_FILE
- * @p wim_file does not begin with the expected magic characters.
+ * The file did not begin with the magic characters that identify a WIM
+ * file.
* @retval ::WIMLIB_ERR_OPEN
- * Failed to open the file @p wim_file for reading.
+ * Failed to open the WIM file for reading. Some possible reasons: the WIM
+ * file does not exist, or the calling process does not have permission to
+ * open it.
* @retval ::WIMLIB_ERR_READ
- * Failed to read data from @p wim_file.
+ * Failed to read data from the WIM file.
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
- * Unexpected end-of-file while reading data from @p wim_file.
+ * Unexpected end-of-file while reading data from the WIM file.
* @retval ::WIMLIB_ERR_UNKNOWN_VERSION
* The WIM version number was not recognized. (May be a pre-Vista WIM.)
* @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED
* The WIM cannot be opened because it contains encrypted segments. (It
- * may be a Windows 8 "ESD" file).
+ * may be a Windows 8 "ESD" file.)
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
* documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_XML
- * The XML data for @p wim_file is invalid.
+ * The XML data of the WIM was invalid.
*/
extern int
wimlib_open_wim(const wimlib_tchar *wim_file,
@@ -3242,10 +3621,11 @@ wimlib_open_wim(const wimlib_tchar *wim_file,
*
* Same as wimlib_open_wim(), but allows specifying a progress function and
* progress context. If successful, the progress function will be registered in
- * the newly open ::WIMStruct. In addition, if
+ * the newly open ::WIMStruct, as if by an automatic call to
+ * wimlib_register_progress_function(). In addition, if
* ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, the
* progress function will receive ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY
- * messages while checking the WIM's integrity.
+ * messages while checking the WIM file's integrity.
*/
extern int
wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
@@ -3265,10 +3645,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
* rebuild. In this mode, the new WIM is written to a temporary file and then
* renamed to the original file after it is has been completely written. The
* temporary file is made in the same directory as the original WIM file. A
- * full rebuild may take a while, but can be used even if images have been
- * modified or deleted, will produce a WIM with no holes, and has little chance
- * of unintentional data loss because the temporary WIM is fsync()ed before
- * being renamed to the original WIM.
+ * full rebuild may take a while, but it will save space by producing a WIM with
+ * no "holes".
*
* The second way to overwrite a WIM is by appending to the end of it and
* overwriting the header. This can be much faster than a full rebuild, but the
@@ -3287,16 +3665,9 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
* ::WIMLIB_WRITE_FLAG_SOFT_DELETE to request the in-place overwrite even if
* images have been deleted from the WIM.
*
- * In the temporary-file overwrite mode, no changes are made to the WIM on
- * failure, and the temporary file is deleted if possible. Abnormal termination
- * of the program will result in the temporary file being orphaned. In the
- * direct append mode, the WIM is truncated to the original length on failure;
- * and while abnormal termination of the program will result in extra data
- * appended to the original WIM, it should still be a valid WIM.
- *
* If this function completes successfully, no more functions should be called
- * on @p wim other than wimlib_free(). You must use wimlib_open_wim() to read
- * the WIM file anew.
+ * on @p wim other than wimlib_free(). If you need to continue using the WIM,
+ * you must use wimlib_open_wim() to read it anew.
*
* @param wim
* Pointer to the ::WIMStruct for the WIM file to write. There may have
@@ -3305,7 +3676,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
* @param write_flags
* Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG.
* @param num_threads
- * Number of threads to use for compression (see wimlib_write()).
+ * Number of threads to use for compression, or 0 for the default. (See
+ * wimlib_write().)
*
* @return 0 on success; nonzero on error. This function may return most error
* codes returned by wimlib_write() as well as the following error codes:
@@ -3316,8 +3688,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
* because another thread or process has mounted an image from the WIM
* read-write or is currently modifying the WIM in-place.
* @retval ::WIMLIB_ERR_NO_FILENAME
- * @p wim corresponds to a WIM created with wimlib_create_new_wim() rather
- * than a WIM read with wimlib_open_wim().
+ * @p wim corresponds to a ::WIMStruct created with wimlib_create_new_wim()
+ * rather than a WIM read with wimlib_open_wim().
* @retval ::WIMLIB_ERR_RENAME
* The temporary file that the WIM was written to could not be renamed to
* the original filename of @p wim.
@@ -3340,7 +3712,8 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads);
* Prints information about one image, or all images, contained in a WIM.
*
* @param wim
- * Pointer to the ::WIMStruct for a WIM file.
+ * Pointer to the ::WIMStruct to query. This need not represent a
+ * standalone WIM (e.g. it could represent part of a split WIM).
* @param image
* The image about which to print information. Can be the number of an
* image, or ::WIMLIB_ALL_IMAGES to print information about all images in the
@@ -3583,6 +3956,43 @@ extern int
wimlib_resolve_image(WIMStruct *wim,
const wimlib_tchar *image_name_or_num);
+/**
+ * @ingroup G_general
+ *
+ * Sets the file to which the library will print error and warning messages.
+ *
+ * This version of the function takes a C library FILE * opened for
+ * writing (or appending). Use wimlib_set_error_file_by_name() to specify the
+ * file by name instead.
+ *
+ * This also enables error messages, as if by a call to
+ * wimlib_set_print_errors(true).
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
+ * wimlib was compiled using the --without-error-messages option.
+ */
+extern int
+wimlib_set_error_file(FILE *fp);
+
+/**
+ * @ingroup G_general
+ *
+ * Sets the path to the file to which the library will print error and warning
+ * messages. The library will open this file for appending.
+ *
+ * This also enables error messages, as if by a call to
+ * wimlib_set_print_errors(true).
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_OPEN
+ * The file named by @p path could not be opened for appending.
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
+ * wimlib was compiled using the --without-error-messages option.
+ */
+extern int
+wimlib_set_error_file_by_name(const wimlib_tchar *path);
+
/**
* @ingroup G_modifying_wims
*
@@ -3602,9 +4012,6 @@ wimlib_resolve_image(WIMStruct *wim,
* @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,
@@ -3616,10 +4023,6 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
* Set the compression chunk size of a WIM to use in subsequent calls to
* wimlib_write() or wimlib_overwrite().
*
- * For compatibility reasons, using this function is not generally recommended.
- * See the documentation for the @c --chunk-size option of wimlib-imagex
- * capture for more information.
- *
* A larger compression chunk size will likely result in a better compression
* ratio, but the speed of random access to the WIM will be reduced.
* Furthermore, the effect of a larger compression chunk size is limited by the
@@ -3629,10 +4032,10 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
* ::WIMStruct for a WIM.
* @param chunk_size
* The chunk size (in bytes) to set. The valid chunk sizes are dependent
- * on the compression format; see the documentation for the @c --chunk-size
- * option of wimlib-imagex capture for more information. As a
- * special case, if @p chunk_size is specified as 0, the chunk size is set
- * to the default for the currently selected output compression type.
+ * on the compression format. See the documentation for each
+ * ::wimlib_compression_type constant for more information. As a special
+ * case, if @p chunk_size is specified as 0, the chunk size is set to the
+ * default for the currently selected output compression type.
*
* @return 0 on success; nonzero on error.
*
@@ -3647,7 +4050,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);
@@ -3678,7 +4081,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);
@@ -3700,12 +4103,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
@@ -3734,9 +4131,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);
@@ -3762,9 +4156,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);
@@ -3780,7 +4171,7 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
* library.
*
* Please note that some external functions, such as those in @c libntfs-3g, may
- * use the standard memory allocation functions.
+ * use the standard memory allocation functions regardless of this setting.
*
* @param malloc_func
* A function equivalent to @c malloc() that wimlib will use to allocate
@@ -3857,11 +4248,6 @@ wimlib_set_print_errors(bool show_messages);
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p swm_name was not a nonempty string, or @p part_size was 0.
*
- * Note: the WIM's uncompressed and compressed resources are not checksummed
- * when they are copied from the joined WIM to the split WIM parts, nor are
- * compressed resources re-compressed (unless explicitly requested with
- * ::WIMLIB_WRITE_FLAG_RECOMPRESS).
- *
* If a progress function is registered with @p wim, for each split WIM part
* that is written it will receive the messages
* ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and
@@ -3873,6 +4259,45 @@ wimlib_split(WIMStruct *wim,
uint64_t part_size,
int write_flags);
+/**
+ * @ingroup G_general
+ *
+ * Perform verification checks on a WIM file.
+ *
+ * @param wim
+ * The ::WIMStruct for the WIM file to verify. Note: for an extra layer of
+ * verification, it is a good idea to have used
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY when you opened the file.
+ *
+ * If verifying a split WIM, specify the first part of the split WIM here,
+ * and reference the other parts using wimlib_reference_resource_files()
+ * before calling this function.
+ *
+ * @param verify_flags
+ * Reserved; must be 0.
+ *
+ * @retval 0 if the WIM file was successfully verified; nonzero if it failed
+ * verification or another error occurred. Some of the possible error codes
+ * are:
+ *
+ * @retval ::WIMLIB_ERR_DECOMPRESSION
+ * A compressed resource could not be decompressed.
+ * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE
+ * The metadata resource for an image is invalid.
+ * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
+ * One of the files did not decompress to its original data, as given by a
+ * cryptographic checksum.
+ * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
+ * One of the files referenced by an image could not be located.
+ *
+ * If a progress function is registered with @p wim, it will receive the
+ * following progress messages: ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE,
+ * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE, and
+ * ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS.
+ */
+extern int
+wimlib_verify_wim(WIMStruct *wim, int verify_flags);
+
/**
* @ingroup G_mounting_wim_images
*
@@ -3900,9 +4325,7 @@ wimlib_split(WIMStruct *wim,
* @retval ::WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT
* The WIM image was mounted by a different user.
* @retval ::WIMLIB_ERR_UNSUPPORTED
- * Mounting is not supported, either because the platform is Windows, or
- * because the platform is UNIX-like and wimlib was compiled using @c
- * --without-fuse.
+ * Mounting is not supported in this build of the library.
*
* Note: you can also unmount the image by using the @c umount() system call, or
* by using the @c umount or @c fusermount programs. However, you need to call
@@ -3946,6 +4369,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.
@@ -4014,10 +4440,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,
@@ -4061,12 +4483,10 @@ wimlib_update_image(WIMStruct *wim,
* Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG.
* @param num_threads
* Number of threads to use for compressing data. If 0, the number of
- * threads is taken to be the number of online processors. Note: if no
- * data compression needs to be done, no additional threads will be created
- * regardless of this parameter (e.g. if writing an uncompressed WIM, or
- * exporting an image from a compressed WIM to another WIM of the same
- * compression type without ::WIMLIB_WRITE_FLAG_RECOMPRESS specified in @p
- * write_flags).
+ * threads will be set by the library automatically. This chosen value
+ * will generally be the number of online processors, but the
+ * implementation may take into account other information (e.g. available
+ * memory and overall system activity).
*
* @return 0 on success; nonzero on error.
*
@@ -4074,11 +4494,11 @@ wimlib_update_image(WIMStruct *wim,
* @p image does not specify a single existing image in @p wim, and is not
* ::WIMLIB_ALL_IMAGES.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
- * A file that had previously been scanned for inclusion in the WIM by
- * wimlib_add_image() was concurrently modified, so it failed the SHA1
- * message digest check.
+ * A file resource failed a SHA-1 message digest check. This can happen if
+ * a file that had previously been scanned for inclusion in the WIM by was
+ * concurrently modified.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p path was @c NULL.
+ * @p path was not a nonempty string, or invalid flags were passed.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_OPEN
@@ -4103,8 +4523,7 @@ wimlib_update_image(WIMStruct *wim,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
* ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or
* ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for
- * different reasons) to read the metadata resource for an image that needed to
- * be written.
+ * different reasons) to read the data from a WIM archive.
*
* If a progress function is registered with @p wim, it will receive the
* messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
@@ -4121,12 +4540,11 @@ wimlib_write(WIMStruct *wim,
/**
* @ingroup G_writing_and_overwriting_wims
*
- * Since wimlib v1.5.0: Same as wimlib_write(), but write the WIM directly to a
- * file descriptor, which need not be seekable if the write is done in a special
- * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p
- * write_flags. This can, for example, allow capturing a WIM image and
- * streaming it over the network. See the documentation for
- * ::WIMLIB_WRITE_FLAG_PIPABLE for more information about pipable WIMs.
+ * Same as wimlib_write(), but write the WIM directly to a file descriptor,
+ * which need not be seekable if the write is done in a special pipable WIM
+ * format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p write_flags. This can,
+ * for example, allow capturing a WIM image and streaming it over the network.
+ * See @ref subsec_pipable_wims for more information about pipable WIMs.
*
* The file descriptor @p fd will @b not be closed when the write is complete;
* the calling code is responsible for this.
@@ -4148,157 +4566,19 @@ wimlib_write_to_fd(WIMStruct *wim,
/**
* @defgroup G_compression Compression and decompression functions
*
- * @brief Functions for LZX, XPRESS, and LZMS compression and decompression,
- * exported for convenience only, as they are already used by wimlib internally
- * when appropriate.
+ * @brief Functions for XPRESS, LZX, and LZMS compression and decompression.
*
- * These functions can be used for general-purpose lossless data compression,
- * but some limitations apply; for example, none of the compressors or
- * decompressors currently support sliding windows, and there also exist
- * slightly different variants of these formats that are not supported
- * unmodified.
+ * These functions are already used by wimlib internally when appropriate for
+ * reading and writing WIM archives. But they are exported and documented so
+ * that they can be used in other applications or libraries for general-purpose
+ * lossless data compression. They are implemented in highly optimized C code,
+ * using state-of-the-art compression techniques. The main limitation is the
+ * lack of sliding window support; this has, however, allowed the algorithms to
+ * be optimized for block-based compression.
*
* @{
*/
-/** Header for compression parameters to pass to wimlib_create_compressor() or
- * wimlib_set_default_compressor_params(). */
-struct wimlib_compressor_params_header {
- /** Size of the parameters, in bytes. */
- uint32_t size;
-};
-
-/** Header for decompression parameters to pass to wimlib_create_decompressor()
- * or wimlib_set_default_decompressor_params() */
-struct wimlib_decompressor_params_header {
- /** Size of the parameters, in bytes. */
- uint32_t size;
-};
-
-/** LZX compression parameters that can optionally be passed to
- * wimlib_create_compressor() with the compression type
- * ::WIMLIB_COMPRESSION_TYPE_LZX. */
-struct wimlib_lzx_compressor_params {
- /** hdr.size Must be set to the size of this structure, in bytes. */
- struct wimlib_compressor_params_header hdr;
-
- /** Relatively fast LZX compression algorithm with a decent compression
- * ratio. */
-#define WIMLIB_LZX_ALGORITHM_FAST 0
-
- /** Slower LZX compression algorithm that provides a better compression
- * ratio. This is the default. */
-#define WIMLIB_LZX_ALGORITHM_SLOW 1
-
- /** Algorithm to use to perform the compression: either
- * ::WIMLIB_LZX_ALGORITHM_FAST or ::WIMLIB_LZX_ALGORITHM_SLOW. The
- * format is still LZX; this refers to the method the code will use to
- * perform LZX-compatible compression. */
- uint32_t algorithm : 3;
-
- /** If set to 1, the default parameters for the specified algorithm are
- * used rather than the ones specified in the following union. */
- uint32_t use_defaults : 1;
-
- union {
- /** Parameters for the fast algorithm. */
- struct wimlib_lzx_fast_params {
- uint32_t fast_reserved1[10];
- } fast;
-
- /** Parameters for the "slow" algorithm. */
- struct wimlib_lzx_slow_params {
- /** If set to 1, the compressor can output length 2
- * matches. If set 0, the compressor can only output
- * matches of length 3 or greater. Suggested value: 1
- */
- uint32_t use_len2_matches : 1;
-
- uint32_t slow_reserved1 : 31;
-
- /** Matches with length (in bytes) greater than or equal
- * to this value are immediately taken without spending
- * time on minimum-cost measurements. Suggested value:
- * 32. */
- uint32_t nice_match_length;
-
- /** Number of passes to compute a match/literal sequence
- * for each LZX block. This is for an iterative
- * algorithm that attempts to minimize the cost of the
- * match/literal sequence by using a cost model provided
- * by the previous iteration. Must be at least 1.
- * Suggested value: 2. */
- uint32_t num_optim_passes;
-
- /** Reserved; set to 0. */
- uint32_t slow_reserved_blocksplit;
-
- /** Maximum depth to search for matches at each
- * position. Suggested value: 50. */
- uint32_t max_search_depth;
-
- /* Note: max_matches_per_pos has been removed and no
- * longer has any effect. */
-
- uint32_t slow_reserved2[3];
-
- /** Assumed cost of a main symbol with zero frequency.
- * Must be at least 1 and no more than 16. Suggested
- * value: 15. */
- uint8_t main_nostat_cost;
-
- /** Assumed cost of a length symbol with zero frequency.
- * Must be at least 1 and no more than 16. Suggested
- * value: 15. */
- uint8_t len_nostat_cost;
-
- /** Assumed cost of an aligned symbol with zero
- * frequency. Must be at least 1 and no more than 8.
- * Suggested value: 7. */
- uint8_t aligned_nostat_cost;
-
- uint8_t slow_reserved3[5];
- } slow;
- } alg_params;
-};
-
-/** LZMS compression parameters that can optionally be passed to
- * wimlib_create_compressor() with the compression type
- * ::WIMLIB_COMPRESSION_TYPE_LZMS. */
-struct wimlib_lzms_compressor_params {
- /** hdr.size Must be set to the size of this structure, in bytes. */
- struct wimlib_compressor_params_header hdr;
-
- /** Minimum match length to output. This must be at least 2. Suggested
- * value: 2 */
- uint32_t min_match_length;
-
- /** Maximum match length to output. This must be at least @p
- * min_match_length. Suggested value: @p UINT32_MAX. */
- uint32_t max_match_length;
-
- /** Matches with length (in bytes) greater than or equal to this value
- * are immediately taken without spending time on minimum-cost
- * measurements. The minimum of @p max_match_length and @p
- * nice_match_length may not exceed 65536. Suggested value: 32. */
- uint32_t nice_match_length;
-
- /** Maximum depth to search for matches at each position. Suggested
- * value: 50. */
- uint32_t max_search_depth;
-
- /* Note: max_matches_per_pos has been removed and no longer has any
- * effect. */
-
- uint32_t reserved1;
-
- /** Length of the array for the near-optimal LZ parsing algorithm. This
- * must be at least 1. Suggested value: 1024. */
- uint32_t optim_array_length;
-
- uint64_t reserved2[4];
-};
-
/** Opaque compressor handle. */
struct wimlib_compressor;
@@ -4306,85 +4586,135 @@ struct wimlib_compressor;
struct wimlib_decompressor;
/**
- * Set the default compression parameters for the specified compression type.
- * This will affect both explicit and wimlib-internal calls to
- * wimlib_create_compressor().
+ * Set the default compression level for the specified compression type. This
+ * is the compression level that wimlib_create_compressor() assumes if it is
+ * called with @p compression_level specified as 0.
+ *
+ * wimlib's WIM writing code (e.g. wimlib_write()) will pass 0 to
+ * wimlib_create_compressor() internally. Therefore, calling this function will
+ * affect the compression level of any data later written to WIM files using the
+ * specified compression type.
+ *
+ * The initial state, before this function is called, is that all compression
+ * types have a default compression level of 50.
*
* @param ctype
- * Compression type for which to set the default compression parameters.
- * @param params
- * Compression-type specific parameters. This may be @c NULL, in which
- * case the "default default" parameters are restored.
+ * Compression type for which to set the default compression level, as one
+ * of the ::wimlib_compression_type constants. Or, if this is the special
+ * value -1, the default compression levels for all compression types will
+ * be set.
+ * @param compression_level
+ * The default compression level to set. If 0, the "default default" level
+ * of 50 is restored. Otherwise, a higher value indicates higher
+ * compression, whereas a lower value indicates lower compression. See
+ * wimlib_create_compressor() for more information.
*
* @return 0 on success; nonzero on error.
*
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * @p ctype was not a supported compression type.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p params were invalid.
- * @retval ::WIMLIB_ERR_NOMEM
- * Not enough memory to duplicate the parameters (perhaps @c params->size
- * was invalid).
+ * @p ctype was neither a supported compression type nor -1.
*/
extern int
-wimlib_set_default_compressor_params(enum wimlib_compression_type ctype,
- const struct wimlib_compressor_params_header *params);
+wimlib_set_default_compression_level(int ctype, unsigned int compression_level);
/**
* Returns the approximate number of bytes needed to allocate a compressor with
- * wimlib_create_compressor() for the specified compression type, block size,
- * and parameters. @p params may be @c NULL, in which case the current default
- * parameters for @p ctype are used. Returns 0 if the compression type or
- * parameters are invalid.
+ * wimlib_create_compressor() for the specified compression type, maximum block
+ * size, and compression level. @p compression_level may be 0, in which case
+ * the current default compression level for @p ctype is used. Returns 0 if the
+ * compression type is invalid, or the @p max_block_size for that compression
+ * type is invalid.
*/
extern uint64_t
wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype,
size_t max_block_size,
- const struct wimlib_compressor_params_header *params);
+ unsigned int compression_level);
+
+#define WIMLIB_COMPRESSOR_FLAG_DESTRUCTIVE 0x80000000
/**
* Allocate a compressor for the specified compression type using the specified
- * parameters.
+ * parameters. This function is part of wimlib's compression API; it is not
+ * necessary to call this to process a WIM file.
*
* @param ctype
- * Compression type for which to create the compressor.
+ * Compression type for which to create the compressor, as one of the
+ * ::wimlib_compression_type constants.
* @param max_block_size
- * Maximum block size to support. The exact meaning and allowed values for
- * this parameter depend on the compression type, but it at least specifies
- * the maximum allowed value for @p uncompressed_size to wimlib_compress().
- * @param extra_params
- * An optional pointer to extra compressor parameters for the specified
- * compression type. For LZX, a pointer to ::wimlib_lzx_compressor_params
- * may be specified here. If left @c NULL, the default parameters are
- * used.
+ * The maximum compression block size to support. This specifies the
+ * maximum allowed value for the @p uncompressed_size parameter of
+ * wimlib_compress() when called using this compressor.
+ *
+ * Usually, the amount of memory used by the compressor will scale in
+ * proportion to the @p max_block_size parameter.
+ * wimlib_get_compressor_needed_memory() can be used to query the specific
+ * amount of memory that will be required.
+ *
+ * This parameter must be at least 1 and must be less than or equal to a
+ * compression-type-specific limit.
+ *
+ * In general, the same value of @p max_block_size must be passed to
+ * wimlib_create_decompressor() when the data is later decompressed.
+ * However, some compression types have looser requirements regarding this.
+ * @param compression_level
+ * The compression level to use. If 0, the default compression level (50,
+ * or another value as set through wimlib_set_default_compression_level())
+ * is used. Otherwise, a higher value indicates higher compression. The
+ * values are scaled so that 10 is low compression, 50 is medium
+ * compression, and 100 is high compression. This is not a percentage;
+ * values above 100 are also valid.
+ *
+ * Using a higher-than-default compression level can result in a better
+ * compression ratio, but can significantly reduce performance. Similarly,
+ * using a lower-than-default compression level can result in better
+ * performance, but can significantly worsen the compression ratio. The
+ * exact results will depend heavily on the compression type and what
+ * algorithms are implemented for it. If you are considering using a
+ * non-default compression level, you should run benchmarks to see if it is
+ * worthwhile for your application.
+ *
+ * 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.
+ *
+ * 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,
- * which can be used for any number of calls to wimlib_compress() before
- * being freed with wimlib_free_compressor().
+ * A location into which to return the pointer to the allocated compressor.
+ * The allocated compressor can be used for any number of calls to
+ * wimlib_compress() before being freed with wimlib_free_compressor().
*
* @return 0 on success; nonzero on error.
*
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
* @p ctype was not a supported compression type.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * The compression parameters were invalid.
+ * @p max_block_size was invalid for the compression type, or @p
+ * compressor_ret was @c NULL.
* @retval ::WIMLIB_ERR_NOMEM
* Insufficient memory to allocate the compressor.
*/
extern int
wimlib_create_compressor(enum wimlib_compression_type ctype,
size_t max_block_size,
- const struct wimlib_compressor_params_header *extra_params,
+ unsigned int compression_level,
struct wimlib_compressor **compressor_ret);
/**
- * Losslessly compress a block of data using a compressor previously created
- * with wimlib_create_compressor().
+ * Compress a buffer of data.
*
* @param uncompressed_data
* Buffer containing the data to compress.
* @param uncompressed_size
- * Size, in bytes, of the data to compress.
+ * Size, in bytes, of the data to compress. This cannot be greater than
+ * the @p max_block_size with which wimlib_create_compressor() was called.
+ * (If it is, the data will not be compressed and 0 will be returned.)
* @param compressed_data
* Buffer into which to write the compressed data.
* @param compressed_size_avail
@@ -4393,8 +4723,8 @@ wimlib_create_compressor(enum wimlib_compression_type ctype,
* A compressor previously allocated with wimlib_create_compressor().
*
* @return
- * The size of the compressed data, in bytes, or 0 if the input data could
- * not be compressed to @p compressed_size_avail or fewer bytes.
+ * The size of the compressed data, in bytes, or 0 if the data could not be
+ * compressed to @p compressed_size_avail or fewer bytes.
*/
extern size_t
wimlib_compress(const void *uncompressed_data, size_t uncompressed_size,
@@ -4405,71 +4735,51 @@ wimlib_compress(const void *uncompressed_data, size_t uncompressed_size,
* Free a compressor previously allocated with wimlib_create_compressor().
*
* @param compressor
- * The compressor to free.
+ * The compressor to free. If @c NULL, no action is taken.
*/
extern void
wimlib_free_compressor(struct wimlib_compressor *compressor);
/**
- * Set the default decompression parameters for the specified compression type.
- * This will affect both explicit and wimlib-internal calls to
- * wimlib_create_decompressor().
+ * Allocate a decompressor for the specified compression type. This function is
+ * part of wimlib's compression API; it is not necessary to call this to process
+ * a WIM file.
*
* @param ctype
- * Compression type for which to set the default decompression parameters.
- * @param params
- * Compression-type specific parameters. This may be @c NULL, in which
- * case the "default default" parameters are restored.
- *
- * @return 0 on success; nonzero on error.
- *
- * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * @p ctype was not a supported compression type.
- * @retval ::WIMLIB_ERR_NOMEM
- * Not enough memory to duplicate the parameters (perhaps @c params->size
- * was invalid).
- */
-extern int
-wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype,
- const struct wimlib_decompressor_params_header *params);
-
-/**
- * Allocate a decompressor for the specified compression type using the
- * specified parameters.
- *
- * @param ctype
- * Compression type for which to create the decompressor.
+ * Compression type for which to create the decompressor, as one of the
+ * ::wimlib_compression_type constants.
* @param max_block_size
- * Maximum block size to support. The exact meaning and allowed values for
- * this parameter depend on the compression type, but it at least specifies
- * the maximum allowed value for @p uncompressed_size to
+ * The maximum compression block size to support. This specifies the
+ * maximum allowed value for the @p uncompressed_size parameter of
* wimlib_decompress().
- * @param extra_params
- * An optional pointer to extra decompressor parameters for the specified
- * compression type. If @c NULL, the default parameters are used.
+ *
+ * In general, this parameter must be the same as the @p max_block_size
+ * that was passed to wimlib_create_compressor() when the data was
+ * compressed. However, some compression types have looser requirements
+ * regarding this.
* @param decompressor_ret
* A location into which to return the pointer to the allocated
- * decompressor, which can be used for any number of calls to
- * wimlib_decompress() before being freed with wimlib_free_decompressor().
+ * decompressor. The allocated decompressor can be used for any number of
+ * calls to wimlib_decompress() before being freed with
+ * wimlib_free_decompressor().
*
* @return 0 on success; nonzero on error.
*
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
* @p ctype was not a supported compression type.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * The decompression parameters were invalid.
+ * @p max_block_size was invalid for the compression type, or @p
+ * decompressor_ret was @c NULL.
* @retval ::WIMLIB_ERR_NOMEM
* Insufficient memory to allocate the decompressor.
*/
extern int
wimlib_create_decompressor(enum wimlib_compression_type ctype,
size_t max_block_size,
- const struct wimlib_decompressor_params_header *extra_params,
struct wimlib_decompressor **decompressor_ret);
/**
- * Decompress a block of data using a decompressor previously created with
- * wimlib_create_decompressor().
+ * Decompress a buffer of data.
*
* @param compressed_data
* Buffer containing the data to decompress.
@@ -4478,11 +4788,22 @@ wimlib_create_decompressor(enum wimlib_compression_type ctype,
* @param uncompressed_data
* Buffer into which to write the uncompressed data.
* @param uncompressed_size
- * Size, in bytes, of the data when uncompressed.
+ * Size, in bytes, of the data when uncompressed. This cannot exceed the
+ * @p max_block_size with which wimlib_create_decompressor() was called.
+ * (If it does, the data will not be decompressed and a nonzero value will
+ * be returned.)
* @param decompressor
* A decompressor previously allocated with wimlib_create_decompressor().
*
* @return 0 on success; nonzero on error.
+ *
+ * No specific error codes are defined; any nonzero value indicates that the
+ * decompression failed. This can only occur if the data is truly invalid;
+ * there will never be transient errors like "out of memory", for example.
+ *
+ * This function requires that the exact uncompressed size of the data be passed
+ * as the @p uncompressed_size parameter. If this is not done correctly,
+ * decompression may fail or the data may be decompressed incorrectly.
*/
extern int
wimlib_decompress(const void *compressed_data, size_t compressed_size,
@@ -4493,7 +4814,7 @@ wimlib_decompress(const void *compressed_data, size_t compressed_size,
* Free a decompressor previously allocated with wimlib_create_decompressor().
*
* @param decompressor
- * The decompressor to free.
+ * The decompressor to free. If @c NULL, no action is taken.
*/
extern void
wimlib_free_decompressor(struct wimlib_decompressor *decompressor);