X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=63cc3e200c2b0e486a24ec65606019f3d18f7d15;hp=ea48aaefb7cfdf050fdd75ef5419c179d5381765;hb=8b709192cd2811b83c248fbe61ca4f11ee9de797;hpb=d444f2e5ddee51e7d9d0401cffcf88477c180422 diff --git a/include/wimlib.h b/include/wimlib.h index ea48aaef..63cc3e20 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -2,57 +2,67 @@ * @file wimlib.h * @brief External header for wimlib. * - * This file contains extensive comments for generating documentation with - * Doxygen. The built HTML documentation can be viewed at - * http://wimlib.sourceforge.net. Make sure to see the Modules page to make more sense of the declarations - * 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/. + * This file contains comments for generating documentation with Doxygen. The + * built HTML documentation can be viewed at http://wimlib.sourceforge.net. + * Make sure to see the Modules page to make more + * sense of the declarations in this header. */ /** * @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.1, a C * library for creating, modifying, extracting, and mounting files in the * Windows Imaging Format. This documentation is intended for developers only. * If you have installed wimlib and want to know how to use the @b wimlib-imagex - * 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 * @@ -85,9 +95,13 @@ * * This design is very much on purpose as it makes the library more useful in * general by allowing functions to be composed in different ways. For example, - * you can make multiple changes to a WIM and commit them all to the underlying + * you can make multiple changes to a WIM and commit them all to the backing * 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 @@ -97,14 +111,15 @@ * * @section sec_error_handling Error Handling * - * Most functions in wimlib return 0 on success and a positive error code on - * failure. Use wimlib_get_error_string() to get a string that describes an - * error code. wimlib also can print error messages to standard error itself - * when an error happens, and these may be more informative than the error code; - * to enable this, call wimlib_set_print_errors(). Please note that this is for - * convenience only, and some errors can occur without a message being printed. - * Currently, error messages and strings (as well as all documentation, for that - * matter) are only available in English. + * Most functions in wimlib return 0 on success and a positive + * ::wimlib_error_code value on failure. Use wimlib_get_error_string() to get a + * string that describes an error code. wimlib also can print error messages to + * standard error itself when an error happens, and these may be more + * informative than the error code; to enable this, call + * wimlib_set_print_errors(). Please note that this is for convenience only, + * and some errors can occur without a message being printed. Currently, error + * messages and strings (as well as all documentation, for that matter) are only + * available in English. * * @section sec_encodings Locales and character encodings * @@ -153,21 +168,27 @@ * * @subsection subsec_thread_safety Thread Safety * - * wimlib is thread-safe, with the following exceptions: - * - Different threads cannot operate on the same ::WIMStruct at the same time; - * they must use different ::WIMStruct's. - * - You must call wimlib_global_init() in one thread before calling any other - * functions. - * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally. - * - wimlib_mount_image(), while it can be used to mount multiple WIMs - * concurrently in the same process, will daemonize the entire process when it - * does so for the first time. This includes changing the working directory - * to the root directory. + * A ::WIMStruct is not thread-safe and cannot be accessed by multiple threads + * concurrently, even for "read-only" operations such as extraction. However, + * users are free to use different ::WIMStruct's from different threads + * concurrently. It is even allowed for multiple ::WIMStruct's to be backed by + * the same on-disk WIM file, although "overwrites" should never be done in such + * a scenario. + * + * In addition, several functions change global state and should only be called + * when a single thread is active in the library. These functions are: + * + * - wimlib_global_init() + * - wimlib_global_cleanup() + * - wimlib_set_memory_allocator() + * - wimlib_set_print_errors() + * - wimlib_set_error_file() + * - wimlib_set_error_file_by_name() * * @subsection subsec_limitations Limitations * * This section documents some technical limitations of wimlib not already - * documented in the man page for @b wimlib-imagex. + * described in the documentation for @b wimlib-imagex. * * - The old WIM format from Vista pre-releases is not supported. * - wimlib does not provide a clone of the @b PEImg tool, or the @b DISM @@ -178,7 +199,7 @@ * * @subsection more_info More information * - * You are advised to read the README as well as the manual pages for + * You are advised to read the README as well as the documentation for * wimlib-imagex, since not all relevant information is repeated here in * the API documentation. */ @@ -190,7 +211,8 @@ /** @defgroup G_creating_and_opening_wims Creating and Opening WIMs * - * @brief Create new WIMs and open existing WIMs. + * @brief Open an existing WIM file as a ::WIMStruct, or create a new + * ::WIMStruct which can be used to create a new WIM file. */ /** @defgroup G_wim_information Retrieving WIM information and directory listings @@ -200,7 +222,8 @@ /** @defgroup G_modifying_wims Modifying WIMs * - * @brief Make changes to a WIM. + * @brief Make changes to a ::WIMStruct, in preparation of persisting the + * ::WIMStruct to an on-disk file. * * @section sec_adding_images Capturing and adding WIM images * @@ -223,7 +246,7 @@ * wimlib_add_image_multisource() do internally.) * * Note that some details of how image addition/capture works are documented - * more fully in the manual page for wimlib-imagex capture. + * more fully in the documentation for wimlib-imagex capture. * * @section sec_deleting_images Deleting WIM images * @@ -265,22 +288,25 @@ * wimlib_extract_image_from_pipe() extracts an image from a pipable WIM sent * over a pipe; see @ref subsec_pipable_wims. * - * Some details of how WIM extraction works are documented more fully in the - * manual pages for wimlib-imagex apply and wimlib-imagex extract. + * Some details of how WIM extraction works are described more fully in the + * documentation for wimlib-imagex apply and wimlib-imagex + * extract. */ /** @defgroup G_mounting_wim_images Mounting WIM images * * @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()). */ /** @@ -309,29 +335,30 @@ /** @defgroup G_writing_and_overwriting_wims Writing and Overwriting WIMs * - * @brief Write and overwrite on-disk WIM files. + * @brief Create or update an on-disk WIM file. * - * 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. + * wimlib_write() creates a new on-disk WIM file, whereas wimlib_overwrite() + * updates an existing WIM file. See @ref sec_basic_wim_handling_concepts for + * more information about the API design. */ /** @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 - * 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 - * fully supported by wimlib. However, as a result, in such cases a ::WIMStruct - * created from one of these on-disk files initially only partially represents - * the full WIM and needs to, in effect, be logically combined with other - * ::WIMStruct's before performing certain operations, such as extracting files - * with wimlib_extract_image() or wimlib_extract_paths(). This is done by - * calling wimlib_reference_resource_files() or wimlib_reference_resources(). + * A ::WIMStruct backed by an on-disk file normally represents a fully + * standalone WIM archive. However, WIM archives 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 fully supported by + * wimlib. However, as a result, in such cases a ::WIMStruct created from one + * of these on-disk files initially only partially represents the full WIM and + * needs to, in effect, be logically combined with other ::WIMStruct's before + * performing certain operations, such as extracting files with + * wimlib_extract_image() or wimlib_extract_paths(). This is done by calling + * wimlib_reference_resource_files() or wimlib_reference_resources(). Note: if + * you fail to do so, you may see the error code + * ::WIMLIB_ERR_RESOURCE_NOT_FOUND; this just indicates that data is not + * available because the appropriate WIM files have not yet been referenced. * * wimlib_write() can create delta WIMs as well as standalone WIMs, but a * specialized function (wimlib_split()) is needed to create a split WIM. @@ -346,39 +373,24 @@ #include #include -/** @ingroup G_general +/** @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 +#define WIMLIB_PATCH_VERSION 1 #ifdef __cplusplus 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 - * obtained from wimlib_open_wim() depends on the underlying on-disk WIM file - * continuing to exist so that data can be read from it as needed. - * - * Most functions in this library will work the same way regardless of whether a - * given ::WIMStruct was obtained through wimlib_open_wim() or - * wimlib_create_new_wim(). Exceptions are documented. - * - * Use wimlib_write() or wimlib_overwrite() to actually write an on-disk WIM - * file from a ::WIMStruct. - * + * Opaque structure that represents a WIM, possibly backed by an on-disk file. * See @ref sec_basic_wim_handling_concepts for more information. */ #ifndef WIMLIB_WIMSTRUCT_DECLARED @@ -394,11 +406,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,39 +426,97 @@ 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), in bytes. */ #define WIMLIB_GUID_LEN 16 /** - * Specifies the compression type of a WIM file. + * Specifies a compression type. + * + * A WIM file has a default compression type, indicated by its file header. + * Normally, each resource in the WIM file is compressed with this compression + * type. However, resources may be stored as uncompressed; for example, wimlib + * may 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 resources with different compression types. */ enum wimlib_compression_type { - /** An invalid compression type. */ - WIMLIB_COMPRESSION_TYPE_INVALID = -1, - - /** 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 @@ -464,6 +536,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 and directories are being created, prior to file data + * 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. */ @@ -473,14 +553,22 @@ enum wimlib_progress_msg { * @p info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5, - /** Confirms that the image has been successfully extracted. @p info - * will point to ::wimlib_progress_info.extract. This is paired with + /** This message may be sent periodically (not necessarily for every + * file) while file and directory metadata is being extracted, following + * file data extraction. @p info will point to + * ::wimlib_progress_info.extract. 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, + + /** 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. */ WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END = 7, - /** Confirms that the files or directory trees have been successfully - * extracted. @p info will point to ::wimlib_progress_info.extract. - * This is paired with ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */ + /** The files or directory trees have been successfully extracted. @p + * info will point to ::wimlib_progress_info.extract. This is paired + * with ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END = 8, /** The directory or NTFS volume is about to be scanned for metadata. @@ -496,35 +584,33 @@ enum wimlib_progress_msg { * been specified. */ WIMLIB_PROGRESS_MSG_SCAN_DENTRY = 10, - /** Confirms that the directory or NTFS volume has been successfully - * scanned. @p info will point to ::wimlib_progress_info.scan. This is - * paired with a previous ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN message, - * possibly with many intervening ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY - * messages. */ + /** The directory or NTFS volume has been successfully scanned. @p info + * will point to ::wimlib_progress_info.scan. This is paired with a + * previous ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN message, possibly with many + * intervening ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY messages. */ WIMLIB_PROGRESS_MSG_SCAN_END = 11, - /** File resources ("streams") are currently being written to the WIM. - * @p info will point to ::wimlib_progress_info.write_streams. This - * message may be received many times while the WIM file is being - * written or appended to with wimlib_write(), wimlib_overwrite(), or - * wimlib_write_to_fd(). */ + /** File data is currently being written to the WIM. @p info will point + * to ::wimlib_progress_info.write_streams. This message may be + * received many times while the WIM file is being written or appended + * to with wimlib_write(), wimlib_overwrite(), or wimlib_write_to_fd(). + */ WIMLIB_PROGRESS_MSG_WRITE_STREAMS = 12, /** Per-image metadata is about to be written to the WIM file. @p info * will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN = 13, - /** Confirms that per-image metadata has been successfully been written - * to the WIM file. @p info will not be valid. This message is paired - * with a preceding ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message. - */ + /** The per-image metadata has been written to the WIM file. @p info + * will not be valid. This message is paired with a preceding + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_END = 14, /** wimlib_overwrite() has successfully renamed the temporary file to - * the original WIM file, thereby committing the update. @p info will - * point to ::wimlib_progress_info.rename. Note: this message is not - * received if wimlib_overwrite() chose to append to the WIM file - * in-place. */ + * the original WIM file, thereby committing the changes to the WIM + * file. @p info will point to ::wimlib_progress_info.rename. Note: + * this message is not received if wimlib_overwrite() chose to append to + * the WIM file in-place. */ WIMLIB_PROGRESS_MSG_RENAME = 15, /** The contents of the WIM file are being checked against the integrity @@ -549,13 +635,13 @@ enum wimlib_progress_msg { * finished. @p info will point to ::wimlib_progress_info.split. */ WIMLIB_PROGRESS_MSG_SPLIT_END_PART = 20, - /** A WIM update command is just about to be executed. @p info will - * point to ::wimlib_progress_info.update. This message is received - * once per update command when wimlib_update_image() is called with the - * flag ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */ + /** A WIM update command is about to be executed. @p info will point to + * ::wimlib_progress_info.update. This message is received once per + * update command when wimlib_update_image() is called with the flag + * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */ WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND = 21, - /** A WIM update command has just been executed. @p info will point to + /** A WIM update command has been executed. @p info will point to * ::wimlib_progress_info.update. This message is received once per * update command when wimlib_update_image() is called with the flag * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */ @@ -568,17 +654,72 @@ enum wimlib_progress_msg { * command. */ WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM = 23, - /** 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. - */ + /** A WIM image is being extracted 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. */ 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 file data 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 @@ -598,88 +739,56 @@ 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 * function. */ union wimlib_progress_info { - /* N.B. I wanted these to be anonymous structs, but Doxygen won't - * document them if they aren't given a name... */ - /** Valid on the message ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. This is * the primary message for tracking the progress of writing a WIM file. */ struct wimlib_progress_info_write_streams { - /** Total number of uncompressed bytes of stream data being - * written. This can be thought of as the total uncompressed - * size of the files being archived, with some caveats. WIM - * files use single-instance streams, so the size provided here - * only counts distinct streams, except for the following - * exception: the size provided here may include the sizes of - * all newly added (e.g. with wimlib_add_image() streams, - * pending automatic de-duplication during the write operation - * itself. When each such stream de-duplication occurs, this - * number will be decreased by the size of the duplicate stream - * that need not be written. - * - * In the case of a wimlib_overwrite() that the library opted to - * perform in-place, both @p total_streams and @p total_bytes - * will only count the streams actually being written and not - * pre-existing streams in the WIM file. */ + + /** An upper bound on the number of bytes of file data that will + * be written. This number is the uncompressed size; the actual + * size may be lower due to compression. In addition, this + * number may decrease over time as duplicated file data is + * discovered. */ uint64_t total_bytes; - /** Total number of streams being written. This can be thought - * of as the total number of files being archived, with some - * caveats. In general, a single file or directory may contain - * multiple data streams, each of which will be represented - * separately in this number. Furthermore, WIM files use - * single-instance streams, so the stream count provided here - * only counts distinct streams, except for the following - * exception: the stream count provided here may include newly - * added (e.g. with wimlib_add_image() streams, pending - * automatic de-duplication during the write operation itself. - * When each such stream de-duplication occurs, this number will - * be decreased by 1 to account for the duplicate stream that - * need not be written. */ + /** An upper bound on the number of distinct file data "blobs" + * that will be written. This will often be similar to the + * "number of files", but for several reasons (hard links, named + * data streams, empty files, etc.) it can be different. In + * addition, this number may decrease over time as duplicated + * file data is discovered. */ uint64_t total_streams; - /** Number of uncompressed bytes of stream data that have been - * written so far. This number be 0 initially, and will be - * equal to @p total_bytes at the end of the write operation. - * Note that @p total_bytes (but not @p completed_bytes) may - * decrease throughout the write operation due to the discovery - * of stream duplications. */ + /** The number of bytes of file data that have been written so + * far. This starts at 0 and ends at @p total_bytes. This + * number is the uncompressed size; the actual size may be lower + * due to compression. */ uint64_t completed_bytes; - /** Number of streams that have been written so far. This - * number will be 0 initially, and will be equal to @p - * total_streams at the end of the write operation. Note that - * @p total_streams (but not @p completed_streams) may decrease - * throughout the write operation due to the discovery of stream - * duplications. - * - * For applications that wish to calculate a simple "percent - * complete" for the write operation, it will likely be more - * accurate to calculate the percentage from @p completed_bytes - * and @p total_bytes rather than @p completed_streams and - * @p total_streams because the time for the operation to - * complete is mainly determined by the number of bytes that - * need to be read, compressed, and written, not just the number - * of files being archived. */ + /** The number of distinct file data "blobs" that have been + * written so far. This starts at 0 and ends at @p + * total_streams. */ uint64_t completed_streams; - /** Number of threads that are being used to compress streams, - * or 1 if streams are being written uncompressed. */ + /** The number of threads being used for data compression; or, + * if no compression is being peformed, this will be 1. */ uint32_t num_threads; - /** The compression type being used to write the streams, as one - * of the ::wimlib_compression_type constants. */ + /** The compression type being used, as one of the + * ::wimlib_compression_type constants. */ int32_t compression_type; - /** Number of split WIM parts from which streams are being - * written (may be 0 if irrelevant). */ + /** The number of on-disk WIM files from which file data is + * being exported into the output WIM file. This can be 0, 1, + * or more than 1, depending on the situation. */ uint32_t total_parts; /** This is currently broken and will always be 0. */ @@ -690,6 +799,7 @@ union wimlib_progress_info { * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY, and * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ struct wimlib_progress_info_scan { + /** Top-level directory being scanned; or, when capturing an NTFS * volume with ::WIMLIB_ADD_FLAG_NTFS, this is instead the path * to the file or block device that contains the NTFS volume @@ -705,25 +815,17 @@ union wimlib_progress_info { /** Dentry scan status, valid on * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. */ enum { - /** The file looks okay and will be captured. */ + /** File looks okay and will be captured. */ WIMLIB_SCAN_DENTRY_OK = 0, /** File is being excluded from capture due to the * capture configuration. */ WIMLIB_SCAN_DENTRY_EXCLUDED, - /** File is being excluded from capture due to being - * unsupported (e.g. an encrypted or device file). */ + /** File is being excluded from capture due to being of + * an unsupported type. */ WIMLIB_SCAN_DENTRY_UNSUPPORTED, - /** The file is an absolute symbolic link or junction - * point and it is being excluded from capture because - * it points outside of the capture directory and - * reparse-point fixups are enabled. (Reparse point - * fixups can be disabled by using the flag - * ::WIMLIB_ADD_FLAG_NORPFIX.) */ - WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, - /** The file is an absolute symbolic link or junction * that points into the capture directory, and * reparse-point fixups are enabled, so its target is @@ -731,6 +833,12 @@ union wimlib_progress_info { * disabled with the flag ::WIMLIB_ADD_FLAG_NORPFIX.) */ WIMLIB_SCAN_DENTRY_FIXED_SYMLINK, + + /** Reparse-point fixups are enabled, but the file is an + * absolute symbolic link or junction that does + * not point into the capture directory, so its + * target is not being adjusted. */ + WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, } status; union { @@ -740,50 +848,24 @@ union wimlib_progress_info { const wimlib_tchar *wim_target_path; /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status - * of @p WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK or @p - * WIMLIB_SCAN_DENTRY_FIXED_SYMLINK, this is the target - * of the absolute symbolic link or junction. */ + * of @p WIMLIB_SCAN_DENTRY_FIXED_SYMLINK or @p + * WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, this is the + * target of the absolute symbolic link or junction. */ const wimlib_tchar *symlink_target; }; - /** Number of directories scanned so far, including the root - * directory but excluding any unsupported/excluded directories. - * - * Details: On Windows and in NTFS capture mode, a reparse point - * counts as a directory if and only if it has - * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link - * counts as a directory if and only if when fully dereferenced - * it points to an accessible directory. If a file has multiple - * names (hard links), it is only counted one time. */ + /** The number of directories scanned so far, not counting + * excluded/unsupported files. */ uint64_t num_dirs_scanned; - /** Number of non-directories scanned so far, excluding any - * unsupported/excluded files. - * - * Details: On Windows and in NTFS capture mode, a reparse point - * counts as a non-directory if and only if it does not have - * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link - * counts as a non-directory if and only if when fully - * dereferenced it points to a non-directory or its target is - * inaccessible. If a file has multiple names (hard links), it - * is only counted one time. */ + /** The number of non-directories scanned so far, not counting + * excluded/unsupported files. If a file has multiple names + * (hard links), it is only counted one time. */ uint64_t num_nondirs_scanned; - /** Number of bytes of file data that have been detected so far. - * - * Details: This data may not actually have been read yet, and - * it will not actually be written to the WIM file until - * wimlib_write() or wimlib_overwrite() has been called. Data - * from excluded files is not counted. This number includes - * default file contents as well as named data streams and - * reparse point data. The size of reparse point data is - * tallied after any reparse-point fixups, and in the case of - * capturing a symbolic link on a UNIX-like system, the creation - * of the reparse point data itself. If a file has multiple - * names (hard links), its size(s) are only counted one time. - * On Windows, encrypted files have their encrypted size - * counted, not their unencrypted size; however, compressed - * files have their uncompressed size counted. */ + /** The number of bytes of file data detected so far, not + * counting excluded/unsupported files. If a file has multiple + * names (hard links), its data is counted only one time. */ uint64_t num_bytes_scanned; } scan; @@ -791,31 +873,33 @@ 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. * * Note: most of the time of an extraction operation will be spent - * extracting streams, and the application will receive + * extracting file data, and the application will receive * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS during this time. Using @p * completed_bytes and @p total_bytes, the application can calculate a - * percentage complete. However, note that this message does not, in - * general, actually provide information about which "file" is currently - * being extracted. This is because wimlib, by default, extracts the - * individual data streams in whichever order it determines to be the - * most efficient. + * percentage complete. However, there is no way for applications to + * know which file is currently being extracted. This is by design + * because the best way to complete the extraction operation is not + * necessarily file-by-file. */ struct wimlib_progress_info_extract { - /** Number of the image from which files are being extracted - * (1-based). */ + + /** The 1-based index of the image from which files are being + * extracted. */ uint32_t image; /** Extraction flags being used. */ uint32_t extract_flags; - /** Full path to the WIM file from which files are being - * extracted, or @c NULL if the WIMStruct has no associated - * on-disk file. */ + /** If the ::WIMStruct from which the extraction being performed + * has a backing file, then this is an absolute path to that + * backing file. Otherwise, this is @c NULL. */ const wimlib_tchar *wimfile_name; /** Name of the image from which files are being extracted, or @@ -829,30 +913,22 @@ union wimlib_progress_info { /** Reserved. */ const wimlib_tchar *reserved; - /** Number of bytes of uncompressed data that will be extracted. - * If a file has multiple names (hard links), its size (or - * sizes, in the case of named data streams) is only counted one - * time. For "reparse points" and symbolic links, the size to - * be extracted is the size of the reparse data buffer. - * - * This number will stay constant throughout the extraction. */ + /** The number of bytes of file data that will be extracted. */ uint64_t total_bytes; - /** Number of bytes of uncompressed data that have been - * extracted so far. This initially be 0 and will equal to @p - * total_bytes at the end of the extraction. */ + /** The number of bytes of file data that have been extracted so + * far. This starts at 0 and ends at @p total_bytes. */ uint64_t completed_bytes; - /** Number of (not necessarily unique) streams that will be - * extracted. This may be more or less than the number of - * "files" to be extracted due to hard links as well as - * 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; + /** The number of file streams that will be extracted. This + * will often be similar to the "number of files", but for + * several reasons (hard links, named data streams, empty files, + * etc.) it can be different. */ + uint64_t total_streams; - /** Reserved. */ - const wimlib_tchar *reserved_2; + /** The number of file streams that have been extracted so far. + * This starts at 0 and ends at @p total_streams. */ + uint64_t completed_streams; /** Currently only used for * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ @@ -865,6 +941,31 @@ 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, e.g. + * for a progress bar. 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 file metadata" phases. For example, the current + * implementation of the UNIX extraction backend will create + * files on-demand during the "extract file data" 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. */ @@ -896,28 +997,29 @@ union wimlib_progress_info { /** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY and * ::WIMLIB_PROGRESS_MSG_CALC_INTEGRITY. */ struct wimlib_progress_info_integrity { - /** Number of bytes from the end of the WIM header to the end of - * the lookup table (the area that is covered by the SHA1 - * integrity checks.) */ + + /** The number of bytes in the WIM file that are covered by + * integrity checks. */ uint64_t total_bytes; - /** Number of bytes that have been SHA1-summed so far. Will be - * 0 initially, and equal @p total_bytes at the end. */ + /** The number of bytes that have been checksummed so far. This + * starts at 0 and ends at @p total_bytes. */ uint64_t completed_bytes; - /** Number of chunks that the checksummed region is divided - * into. */ + /** The number of individually checksummed "chunks" the + * integrity-checked region is divided into. */ uint32_t total_chunks; - /** Number of chunks that have been SHA1-summed so far. Will - * be 0 initially, and equal to @p total_chunks at the end. */ + /** The number of chunks that have been checksummed so far. + * This starts at 0 and ends at @p total_chunks. */ uint32_t completed_chunks; - /** Size of the chunks used for the integrity calculation. */ + /** The size of each individually checksummed "chunk" in the + * integrity-checked region. */ uint32_t chunk_size; - /** Filename of the WIM (only valid if the message is - * ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY). */ + /** For ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages, this is + * the path to the WIM file being checked. */ const wimlib_tchar *filename; } integrity; @@ -984,6 +1086,90 @@ 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; }; /** @@ -1010,7 +1196,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 @@ -1028,14 +1214,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 @@ -1047,35 +1234,45 @@ struct wimlib_capture_source { * ::wimlib_wim_info.boot_index of the @p info parameter. */ #define WIMLIB_CHANGE_BOOT_INDEX 0x00000004 -/** Change the WIM_HDR_FLAG_RP_FIX flag of the WIM file to the value specified - * in ::wimlib_wim_info.has_rpfix of the @p info parameter. This flag generally - * indicates whether an image in the WIM has been captured with reparse-point - * fixups enabled. wimlib also treats this flag as specifying whether to do - * reparse-point fixups by default when capturing or applying WIM images. */ +/** Change the WIM_HDR_FLAG_RP_FIX flag of the WIM file to the value + * specified in ::wimlib_wim_info.has_rpfix of the @p info parameter. This flag + * generally indicates whether an image in the WIM has been captured with + * reparse-point fixups enabled. wimlib also treats this flag as specifying + * whether to do reparse-point fixups by default when capturing or applying WIM + * images. */ #define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 /** @} */ -/** @ingroup G_wim_information - * @{ */ -/** General information about a WIM file. */ +/** @addtogroup G_wim_information */ + +/** @{ */ + +/** + * General information about a WIM file. + * + * This info can also be requested for a ::WIMStruct that does not have a + * backing file. In this case, fields that only make sense given a backing file + * are set to default values. + */ struct wimlib_wim_info { - /** Globally unique identifier for the WIM file. Note: all parts of a - * split WIM should have an identical value in this field. */ - uint8_t guid[WIMLIB_GUID_LEN]; + /** The globally unique identifier for this WIM. (Note: all parts of a + * split WIM normally have identical GUIDs.) */ + uint8_t guid[WIMLIB_GUID_LEN]; - /** Number of images in the WIM. */ + /** The number of images in this WIM file. */ uint32_t image_count; - /** 1-based index of the bootable image in the WIM, or 0 if no image is - * bootable. */ + /** The 1-based index of the bootable image in this WIM file, or 0 if no + * image is bootable. */ uint32_t boot_index; - /** Version of the WIM file. */ + /** The version of the WIM file format used in this WIM file. */ uint32_t wim_version; - /** Chunk size used for compression. */ + /** The default compression chunk size of resources in this WIM file. + */ uint32_t chunk_size; /** For split WIMs, the 1-based index of this part within the split WIM; @@ -1086,114 +1283,162 @@ struct wimlib_wim_info { * otherwise 1. */ uint16_t total_parts; - /** One of the ::wimlib_compression_type values that specifies the - * method used to compress resources in the WIM. */ - int32_t compression_type; + /** The default compression type of resources in this WIM file, as one + * of the ::wimlib_compression_type constants. */ + int32_t compression_type; - /** Size of the WIM file in bytes, excluding the XML data and integrity - * table. */ + /** The size of this WIM file in bytes, excluding the XML data and + * integrity table. */ uint64_t total_bytes; - /** 1 if the WIM has an integrity table. Note: if the ::WIMStruct was - * created via wimlib_create_new_wim() rather than wimlib_open_wim(), - * this will always be 0, even if the ::WIMStruct was written to - * somewhere by calling wimlib_write() with the - * ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY flag specified. */ + /** 1 iff this WIM file has an integrity table. */ uint32_t has_integrity_table : 1; - /** 1 if the ::WIMStruct was created via wimlib_open_wim() rather than - * wimlib_create_new_wim(). */ + /** 1 iff this info struct is for a ::WIMStruct that has a backing file. + */ uint32_t opened_from_file : 1; - /** 1 if the WIM is considered readonly for any reason. */ + /** 1 iff this WIM file is considered readonly for any reason (e.g. the + * "readonly" header flag is set, or this is part of a split WIM, or + * filesystem permissions deny writing) */ uint32_t is_readonly : 1; - /** 1 if reparse-point fixups are supposedly enabled for one or more - * images in the WIM. */ + /** 1 iff the "reparse point fix" flag is set in this WIM's header */ uint32_t has_rpfix : 1; - /** 1 if the WIM is marked as read-only. */ + /** 1 iff the "readonly" flag is set in this WIM's header */ uint32_t is_marked_readonly : 1; - /** 1 if the WIM is part of a spanned set. */ + /** 1 iff the "spanned" flag is set in this WIM's header */ uint32_t spanned : 1; + /** 1 iff the "write in progress" flag is set in this WIM's header */ uint32_t write_in_progress : 1; + + /** 1 iff the "metadata only" flag is set in this WIM's header */ uint32_t metadata_only : 1; + + /** 1 iff the "resource only" flag is set in this WIM's header */ uint32_t resource_only : 1; - /** 1 if the WIM is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */ + /** 1 iff this WIM file is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */ uint32_t pipable : 1; uint32_t reserved_flags : 22; uint32_t reserved[9]; }; -/** 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.) */ +/** + * Information about a "blob", which is a fixed length sequence of binary data. + * Each nonempty stream of each file in a WIM image is associated with a blob. + * Blobs are deduplicated within a WIM file. + * + * TODO: this struct needs to be renamed, and perhaps made into a union since + * there are several cases. I'll try to list them below: + * + * 1. The blob is "missing", meaning that it is referenced by hash but not + * actually present in the WIM file. In this case we only know the + * sha1_hash. This case can only occur with wimlib_iterate_dir_tree(), never + * wimlib_iterate_lookup_table(). + * + * 2. Otherwise we know the sha1_hash, the uncompressed_size, the + * reference_count, and the is_metadata flag. In addition: + * + * A. If the blob is located in a non-solid WIM resource, then we also know + * the compressed_size and offset. + * + * B. If the blob is located in a solid WIM resource, then we also know the + * offset, raw_resource_offset_in_wim, raw_resource_compressed_size, and + * raw_resource_uncompressed_size. But the "offset" is actually the + * offset in the uncompressed solid resource rather than the offset from + * the beginning of the WIM file. + * + * C. If the blob is *not* located in any type of WIM resource, then we don't + * know any additional information. + * + * Unknown or irrelevant fields are left zeroed. + */ struct wimlib_resource_entry { - /** Uncompressed size of the stream in bytes. */ + + /** If this blob is not missing, then this is the uncompressed size of + * this blob 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. */ + /** If this blob is located in a non-solid WIM resource, then this is + * the compressed size of that resource. */ 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. - */ + /** If this blob is located in a non-solid WIM resource, then this is + * the offset of that resource within the WIM file containing it. If + * this blob is located in a solid WIM resource, then this is the offset + * of this blob within that solid resource when uncompressed. */ uint64_t offset; - /** SHA1 message digest of the stream's uncompressed contents. */ + /** The SHA-1 message digest of the blob'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(). */ + /** If this blob is located in a WIM resource, then this is the part + * number of the WIM file containing it. */ uint32_t part_number; - /** Number of times this stream is referenced over all WIM images. */ + /** If this blob is not missing, then this is the number of times this + * blob is referenced over all images in the WIM. This number is not + * guaranteed to be correct. */ uint32_t reference_count; - /** 1 if this stream is compressed. */ + /** 1 iff this blob is located in a non-solid compressed WIM resource. + */ uint32_t is_compressed : 1; - /** 1 if this stream is a metadata resource rather than a file resource. - * */ + /** 1 iff this blob contains the metadata for an image. */ uint32_t is_metadata : 1; uint32_t is_free : 1; uint32_t is_spanned : 1; - /** 1 if this stream was not found in the lookup table of the - * ::WIMStruct. This normally implies a missing call to - * wimlib_reference_resource_files() or wimlib_reference_resources(). - * */ + /** 1 iff a blob with this hash was not found in the blob lookup table + * of the ::WIMStruct. This normally implies a missing call to + * wimlib_reference_resource_files() or wimlib_reference_resources(). */ uint32_t is_missing : 1; - /** 1 if this stream is located in a packed resource which may contain - * other streams (all compressed together) as well. */ + /** 1 iff this blob is located in a solid resource. */ uint32_t packed : 1; uint32_t reserved_flags : 26; - /** If @p packed is 1, then this will specify the offset of the packed - * resource in the WIM. */ + /** If this blob is located in a solid WIM resource, then this is the + * offset of that solid resource within the WIM file containing it. */ 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 this blob is located in a solid WIM resource, then this is the + * compressed size of that solid resource. */ uint64_t raw_resource_compressed_size; - uint64_t reserved[2]; + /** If this blob is located in a solid WIM resource, then this is the + * uncompressed size of that solid resource. */ + 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. + * + * TODO: the library now explicitly tracks stream types, which allows it to have + * multiple unnamed streams (e.g. both a reparse point stream and unnamed data + * stream). However, this isn't yet exposed by wimlib_iterate_dir_tree(). + */ struct wimlib_stream_entry { - /** Name of the stream, or NULL if the stream is unnamed. */ + + /** 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. */ + + /** Info about this stream's data, such as its hash and size if known.*/ struct wimlib_resource_entry resource; + uint64_t reserved[4]; }; @@ -1202,15 +1447,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 @@ -1258,20 +1504,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. */ @@ -1283,20 +1537,45 @@ 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 correspond to the reparse data stream. Alternatively, for + * encrypted files, the first entry will correspond to the encrypted + * data. + * + * 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[]; }; @@ -1322,24 +1601,30 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * itself; only its children (in the case of a non-empty directory) */ #define WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002 -/** Return ::WIMLIB_ERR_RESOURCE_NOT_FOUND if any resources needed to fill in - * the ::wimlib_resource_entry's for the iteration cannot be found in the lookup - * table of the ::WIMStruct. The default behavior without this flag is to fill - * in the SHA1 message digest of the ::wimlib_resource_entry and set the @ref - * wimlib_resource_entry::is_missing "is_missing" flag. */ +/** Return ::WIMLIB_ERR_RESOURCE_NOT_FOUND if any file data blobs needed to fill + * in the ::wimlib_resource_entry's for the iteration cannot be found in the + * blob lookup table of the ::WIMStruct. The default behavior without this flag + * is to fill in the @ref wimlib_resource_entry::sha1_hash "sha1_hash" and set + * the @ref wimlib_resource_entry::is_missing "is_missing" flag. */ #define WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED 0x00000004 /** @} */ -/** @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 @@ -1348,87 +1633,97 @@ 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. In addition, capture 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; also exclude absolute symbolic links that point outside the - * directory tree being captured. +/** 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. */ #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. */ +/** Do not automatically exclude unsupported files or directories from capture, + * such as encrypted files in NTFS-3g capture mode, or device files and FIFOs on + * 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 /** - * Capture image as WIMBoot compatible. In addition, if no capture + * Capture image as "WIMBoot compatible". In addition, if no capture * configuration file is explicitly specified use the capture configuration file * $SOURCE/Windows/System32/WimBootCompress.ini if it exists, where * $SOURCE is the directory being captured; or, if a capture * configuration file is explicitly specified, use it and also place it at - * /Windows/System32/WimBootCompress.ini in the WIM image. + * /Windows/System32/WimBootCompress.ini in the WIM image. * - * Note: this will not by itself change the compression type. Before writing - * the WIM file, it's recommended to also do: + * This flag does not, by itself, change the compression type or chunk size. + * Before writing the WIM file, you may wish to set the compression format to + * be the same as that used by WIMGAPI and DISM: * * \code * wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS); * wimlib_set_output_chunk_size(wim, 4096); * \endcode * - * 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). + * However, "WIMBoot" also works with other XPRESS chunk sizes as well as LZX + * with 32768 byte chunks. + * + * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and + * independent from, ::WIMLIB_ADD_FLAG_BOOT. */ #define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000 @@ -1441,6 +1736,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 @@ -1458,7 +1764,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. */ @@ -1469,7 +1775,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 * @{ */ /** @@ -1497,8 +1803,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); @@ -1510,7 +1817,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. @@ -1546,8 +1853,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * reparse-point fixups on, so absolute symbolic links or junction points will * be fixed to be absolute relative to the actual extraction root. Reparse- * point fixups are done by default for wimlib_extract_image() and - * wimlib_extract_image_from_pipe() if WIM_HDR_FLAG_RP_FIX is set in the WIM - * header. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX. */ + * wimlib_extract_image_from_pipe() if WIM_HDR_FLAG_RP_FIX is set in the + * WIM header. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX. + * */ #define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100 /** Force reparse-point fixups on extraction off, regardless of the state of the @@ -1562,29 +1870,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 @@ -1592,10 +1910,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 @@ -1603,28 +1924,58 @@ 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 +/** EXPERIMENTAL and only works on Windows 10 and later: compress the extracted + * files using the System Compression feature (when possible). System + * Compression is only supported by Windows 10 or later. Several different + * compression formats may be used with System Compression; this particular flag + * selects the XPRESS compression format with 4096 byte chunks. This flag is + * currently experimental and may be changed or removed in future releases of + * wimlib. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000 + +/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with + * 8192 byte chunks. This flag is currently experimental and may be changed + * or removed in future releases of wimlib. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000 + +/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with + * 16384 byte chunks. This flag is currently experimental and may be changed + * or removed in future releases of wimlib. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000 + +/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with + * 32768 byte chunks. This flag is currently experimental and may be changed + * or removed in future releases of wimlib. */ +#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000 + /** @} */ -/** @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. */ @@ -1644,36 +1995,38 @@ 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). */ +/** Verify the WIM contents against the WIM's integrity table, if present. The + * integrity table stores checksums for the raw data of the WIM file, divided + * into fixed size chunks. Verification will compute checksums and compare them + * with the stored values. If there are any mismatches, then + * ::WIMLIB_ERR_INTEGRITY will be issued. If the WIM file does not contain an + * integrity table, then 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. @@ -1709,7 +2062,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 @@ -1717,7 +2070,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 * @{ */ /** @@ -1740,9 +2093,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 @@ -1758,27 +2112,28 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_NOT_PIPABLE 0x00000008 /** - * When writing streams to the WIM file, recompress them, even if their data is - * already available in the desired compressed form (for example, in a WIM file - * from which an image has been exported using wimlib_export_image()). + * When writing data to the WIM file, recompress it, even if the data is already + * available in the desired compressed form (for example, in a WIM file 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.) - * - * ::WIMLIB_WRITE_FLAG_RECOMPRESS does not cause recompression of streams + * 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 data * that would not otherwise be written. For example, a call to * wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_RECOMPRESS will not, by itself, - * cause already-existing streams in the WIM file to be recompressed. To force - * the WIM file to be fully rebuilt and recompressed, combine + * cause already-existing data in the WIM file to be recompressed. To force the + * WIM file to be fully rebuilt and recompressed, combine * ::WIMLIB_WRITE_FLAG_RECOMPRESS with ::WIMLIB_WRITE_FLAG_REBUILD. */ #define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000010 @@ -1786,18 +2141,24 @@ 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. - * - * 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. + * For wimlib_overwrite(): rebuild the entire WIM file, even if it otherwise + * could be updated in-place by appending to it. Any data that existed in the + * original WIM file but is not actually needed by any of the remaining images + * will not be included. This can free up space left over after previous + * in-place modifications to the WIM file. * * 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. @@ -1807,12 +2168,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_REBUILD 0x00000040 /** - * For wimlib_overwrite(), override the default behavior after one or more calls + * For wimlib_overwrite(): override the default behavior after one or more calls * to wimlib_delete_image(), which is to rebuild the entire WIM file. With this * flag, only minimal changes to correctly remove the image from the WIM file - * will be taken. In particular, all streams will be retained, even if they are - * no longer referenced. This may not be what you want, because no space will - * be saved by deleting an image in this way. + * will be taken. This can be much faster, but it will result in the WIM file + * getting larger rather than smaller. * * wimlib_write() ignores this flag. */ @@ -1820,8 +2180,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** * For wimlib_overwrite(), allow overwriting the WIM file even if the readonly - * flag (WIM_HDR_FLAG_READONLY) is set in the WIM header. This can be used - * following a call to wimlib_set_wim_info() with the + * flag (WIM_HDR_FLAG_READONLY) is set in the WIM header. This can be + * used following a call to wimlib_set_wim_info() with the * ::WIMLIB_CHANGE_READONLY_FLAG flag to actually set the readonly flag on the * on-disk WIM file. * @@ -1830,23 +2190,14 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 /** - * Do not include streams already present in other WIMs. This flag can be used - * to write a "delta" WIM after resources from the WIM on which the delta is to - * be based were referenced with wimlib_reference_resource_files() or + * Do not include file data already present in other WIMs. This flag can be + * used to write a "delta" WIM after the WIM files on which the delta is to be + * based were referenced with wimlib_reference_resource_files() or * wimlib_reference_resources(). */ #define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200 -/** - * Advises the library that for writes of all WIM images, all streams needed for - * the WIM are already present (not in external resource WIMs) and their - * reference counts are correct, so the code does not need to recalculate which - * streams are referenced. This is for optimization purposes only, since with - * this flag specified, the metadata resources may not need to be decompressed - * and parsed. - * - * wimlib_overwrite() will set this flag automatically. - */ +/** Deprecated; this flag should not be used outside of the library itself. */ #define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 /** @@ -1858,41 +2209,64 @@ 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 - * is also known as creating a "solid archive". This tends to produce a better - * compression ratio at the cost of much slower random access. + * Concatenate files and compress them together, rather than compress each file + * 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. * * WIM files created with this flag are only compatible with wimlib v1.6.0 or * later, WIMGAPI Windows 8 or later, and DISM Windows 8.1 or later. WIM files * created with this flag use a different version number in their header (3584 * instead of 68864) and are also called "ESD files". * - * If this flag is passed to wimlib_overwrite(), any new data streams will be - * written in solid mode. Use both ::WIMLIB_WRITE_FLAG_REBUILD and - * ::WIMLIB_WRITE_FLAG_RECOMPRESS to force the entire WIM file be rebuilt with - * all streams recompressed in solid mode. + * Note that providing this flag does not affect the "append by default" + * behavior of wimlib_overwrite(). In other words, wimlib_overwrite() with just + * ::WIMLIB_WRITE_FLAG_SOLID can be used to append solid-compressed data to a + * WIM file that originally did not contain any solid-compressed data. But if + * you instead want to rebuild and recompress an entire WIM file in solid mode, + * then also provide ::WIMLIB_WRITE_FLAG_REBUILD and + * ::WIMLIB_WRITE_FLAG_RECOMPRESS. * - * Currently, new solid blocks will, by default, be written using LZMS - * compression with 32 MiB (33554432 byte) chunks. Use + * Currently, new solid resources will, by default, be written using LZMS + * compression with 64 MiB (67108864 byte) chunks. Use * wimlib_set_output_pack_compression_type() and/or * wimlib_set_output_pack_chunk_size() to change this. This is independent of * the WIM's main compression type and chunk size; you can have a WIM that * nominally uses LZX compression and 32768 byte chunks but actually contains - * LZMS-compressed solid blocks, for example. However, if including solid - * blocks, I suggest that you set the WIM's main compression type to LZMS as + * LZMS-compressed solid resources, for example. However, if including solid + * resources, I suggest that you set the WIM's main compression type to LZMS as * well, either by creating the WIM with * ::wimlib_create_new_wim(::WIMLIB_COMPRESSION_TYPE_LZMS, ...) or by calling * ::wimlib_set_output_compression_type(..., ::WIMLIB_COMPRESSION_TYPE_LZMS). * * This flag will be set by default when writing or overwriting a WIM file that - * either already contains packed streams, or has had packed streams exported + * either already contains solid resources, or has had solid resources exported * into it and the WIM's main compression type is LZMS. */ -#define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000 +#define WIMLIB_WRITE_FLAG_SOLID 0x00001000 + +/** + * Deprecated: this is the old name for ::WIMLIB_WRITE_FLAG_SOLID, retained for + * source compatibility. + */ +#define WIMLIB_WRITE_FLAG_PACK_STREAMS WIMLIB_WRITE_FLAG_SOLID + +/** + * Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM + * 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 + +/** + * Do not consider content similarily when arranging file data for solid + * compression. Providing this flag will typically worsen the compression + * ratio, so only provide this flag if you know what you are doing. + */ +#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 @@ -1902,11 +2276,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Windows-only: do not attempt to acquire additional privileges (currently * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and - * SeTakeOwnershipPrivilege) when initializing the library. This is intended - * for the case where the calling program manages these privileges itself. - * Note: no error is issued if privileges cannot be acquired, although related - * errors may be reported later, depending on if the operations performed - * actually require additional privileges or not. */ + * SeTakeOwnershipPrivilege) when initializing the library. This flag is + * intended for the case where the calling program manages these privileges + * itself. Note: by default, no error is issued if privileges cannot be + * acquired, although related errors may be reported later, depending on if the + * operations performed actually require additional privileges or not. */ #define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002 /** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, @@ -1932,7 +2306,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. @@ -1949,7 +2323,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. */ @@ -2022,7 +2396,7 @@ struct wimlib_update_command { }; /** @} */ -/** @ingroup G_general +/** @addtogroup G_general * @{ */ /** @@ -2032,88 +2406,82 @@ struct wimlib_update_command { * codes can be returned by a given function, and what they mean. */ enum wimlib_error_code { - WIMLIB_ERR_SUCCESS = 0, - WIMLIB_ERR_ALREADY_LOCKED, - WIMLIB_ERR_DECOMPRESSION, - WIMLIB_ERR_DELETE_STAGING_DIR, - WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED, - WIMLIB_ERR_FORK, - WIMLIB_ERR_FUSE, - WIMLIB_ERR_FUSERMOUNT, - WIMLIB_ERR_GLOB_HAD_NO_MATCHES, - WIMLIB_ERR_ICONV_NOT_AVAILABLE, - WIMLIB_ERR_IMAGE_COUNT, - WIMLIB_ERR_IMAGE_NAME_COLLISION, - WIMLIB_ERR_INSUFFICIENT_PRIVILEGES, - WIMLIB_ERR_INTEGRITY, - WIMLIB_ERR_INVALID_CAPTURE_CONFIG, - WIMLIB_ERR_INVALID_CHUNK_SIZE, - WIMLIB_ERR_INVALID_COMPRESSION_TYPE, - WIMLIB_ERR_INVALID_HEADER, - WIMLIB_ERR_INVALID_IMAGE, - WIMLIB_ERR_INVALID_INTEGRITY_TABLE, - WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY, - WIMLIB_ERR_INVALID_METADATA_RESOURCE, - WIMLIB_ERR_INVALID_MULTIBYTE_STRING, - WIMLIB_ERR_INVALID_OVERLAY, - WIMLIB_ERR_INVALID_PARAM, - WIMLIB_ERR_INVALID_PART_NUMBER, - WIMLIB_ERR_INVALID_PIPABLE_WIM, - WIMLIB_ERR_INVALID_REPARSE_DATA, - WIMLIB_ERR_INVALID_RESOURCE_HASH, - WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE, - WIMLIB_ERR_INVALID_UTF16_STRING, - WIMLIB_ERR_INVALID_UTF8_STRING, - WIMLIB_ERR_IS_DIRECTORY, - WIMLIB_ERR_IS_SPLIT_WIM, - WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE, - WIMLIB_ERR_LINK, - WIMLIB_ERR_METADATA_NOT_FOUND, - WIMLIB_ERR_MKDIR, - WIMLIB_ERR_MQUEUE, - WIMLIB_ERR_NOMEM, - WIMLIB_ERR_NOTDIR, - WIMLIB_ERR_NOTEMPTY, - WIMLIB_ERR_NOT_A_REGULAR_FILE, - WIMLIB_ERR_NOT_A_WIM_FILE, - WIMLIB_ERR_NOT_PIPABLE, - WIMLIB_ERR_NO_FILENAME, - WIMLIB_ERR_NTFS_3G, - WIMLIB_ERR_OPEN, - WIMLIB_ERR_OPENDIR, - WIMLIB_ERR_PATH_DOES_NOT_EXIST, - WIMLIB_ERR_READ, - WIMLIB_ERR_READLINK, - WIMLIB_ERR_RENAME, - WIMLIB_ERR_REOPEN, - WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED, - WIMLIB_ERR_RESOURCE_NOT_FOUND, - WIMLIB_ERR_RESOURCE_ORDER, - WIMLIB_ERR_SET_ATTRIBUTES, - WIMLIB_ERR_SET_REPARSE_DATA, - WIMLIB_ERR_SET_SECURITY, - WIMLIB_ERR_SET_SHORT_NAME, - WIMLIB_ERR_SET_TIMESTAMPS, - WIMLIB_ERR_SPLIT_INVALID, - WIMLIB_ERR_STAT, - WIMLIB_ERR_TIMEOUT, - WIMLIB_ERR_UNEXPECTED_END_OF_FILE, - WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE, - WIMLIB_ERR_UNKNOWN_VERSION, - WIMLIB_ERR_UNSUPPORTED, - WIMLIB_ERR_UNSUPPORTED_FILE, - WIMLIB_ERR_VOLUME_LACKS_FEATURES, - WIMLIB_ERR_WIM_IS_READONLY, - WIMLIB_ERR_WRITE, - WIMLIB_ERR_XML, - WIMLIB_ERR_WIM_IS_ENCRYPTED, - WIMLIB_ERR_WIMBOOT, - WIMLIB_ERR_ABORTED_BY_PROGRESS, - WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS, - WIMLIB_ERR_MKNOD, - WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY, - WIMLIB_ERR_NOT_A_MOUNTPOINT, - WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT, + WIMLIB_ERR_SUCCESS = 0, + WIMLIB_ERR_ALREADY_LOCKED = 1, + WIMLIB_ERR_DECOMPRESSION = 2, + WIMLIB_ERR_FUSE = 6, + WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8, + WIMLIB_ERR_ICONV_NOT_AVAILABLE = 9, + WIMLIB_ERR_IMAGE_COUNT = 10, + WIMLIB_ERR_IMAGE_NAME_COLLISION = 11, + WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12, + WIMLIB_ERR_INTEGRITY = 13, + WIMLIB_ERR_INVALID_CAPTURE_CONFIG = 14, + WIMLIB_ERR_INVALID_CHUNK_SIZE = 15, + WIMLIB_ERR_INVALID_COMPRESSION_TYPE = 16, + WIMLIB_ERR_INVALID_HEADER = 17, + WIMLIB_ERR_INVALID_IMAGE = 18, + WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19, + WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20, + WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21, + WIMLIB_ERR_INVALID_MULTIBYTE_STRING = 22, + WIMLIB_ERR_INVALID_OVERLAY = 23, + WIMLIB_ERR_INVALID_PARAM = 24, + WIMLIB_ERR_INVALID_PART_NUMBER = 25, + WIMLIB_ERR_INVALID_PIPABLE_WIM = 26, + WIMLIB_ERR_INVALID_REPARSE_DATA = 27, + WIMLIB_ERR_INVALID_RESOURCE_HASH = 28, + WIMLIB_ERR_INVALID_UTF16_STRING = 30, + WIMLIB_ERR_INVALID_UTF8_STRING = 31, + WIMLIB_ERR_IS_DIRECTORY = 32, + WIMLIB_ERR_IS_SPLIT_WIM = 33, + WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34, + WIMLIB_ERR_LINK = 35, + WIMLIB_ERR_METADATA_NOT_FOUND = 36, + WIMLIB_ERR_MKDIR = 37, + WIMLIB_ERR_MQUEUE = 38, + WIMLIB_ERR_NOMEM = 39, + WIMLIB_ERR_NOTDIR = 40, + WIMLIB_ERR_NOTEMPTY = 41, + WIMLIB_ERR_NOT_A_REGULAR_FILE = 42, + WIMLIB_ERR_NOT_A_WIM_FILE = 43, + WIMLIB_ERR_NOT_PIPABLE = 44, + WIMLIB_ERR_NO_FILENAME = 45, + WIMLIB_ERR_NTFS_3G = 46, + WIMLIB_ERR_OPEN = 47, + WIMLIB_ERR_OPENDIR = 48, + WIMLIB_ERR_PATH_DOES_NOT_EXIST = 49, + WIMLIB_ERR_READ = 50, + WIMLIB_ERR_READLINK = 51, + WIMLIB_ERR_RENAME = 52, + WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED = 54, + WIMLIB_ERR_RESOURCE_NOT_FOUND = 55, + WIMLIB_ERR_RESOURCE_ORDER = 56, + WIMLIB_ERR_SET_ATTRIBUTES = 57, + WIMLIB_ERR_SET_REPARSE_DATA = 58, + WIMLIB_ERR_SET_SECURITY = 59, + WIMLIB_ERR_SET_SHORT_NAME = 60, + WIMLIB_ERR_SET_TIMESTAMPS = 61, + WIMLIB_ERR_SPLIT_INVALID = 62, + WIMLIB_ERR_STAT = 63, + WIMLIB_ERR_UNEXPECTED_END_OF_FILE = 65, + WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE = 66, + WIMLIB_ERR_UNKNOWN_VERSION = 67, + WIMLIB_ERR_UNSUPPORTED = 68, + WIMLIB_ERR_UNSUPPORTED_FILE = 69, + WIMLIB_ERR_WIM_IS_READONLY = 71, + WIMLIB_ERR_WRITE = 72, + WIMLIB_ERR_XML = 73, + WIMLIB_ERR_WIM_IS_ENCRYPTED = 74, + WIMLIB_ERR_WIMBOOT = 75, + WIMLIB_ERR_ABORTED_BY_PROGRESS = 76, + WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS = 77, + WIMLIB_ERR_MKNOD = 78, + 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, + WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83, }; @@ -2128,35 +2496,30 @@ enum wimlib_error_code { /** * @ingroup G_modifying_wims * - * Appends an empty image to a WIM file. This empty image will initially - * contain no files or directories, although if written without further - * modifications, a root directory will be created automatically for it. After - * calling this function, you can use wimlib_update_image() to add files to the - * new WIM image. This gives you slightly more control over making the new - * image compared to calling wimlib_add_image() or - * wimlib_add_image_multisource() directly. + * Append an empty image to a ::WIMStruct. + * + * The new image will initially contain no files or directories, although if + * written without further modifications, then a root directory will be created + * automatically for it. + * + * After calling this function, you can use wimlib_update_image() to add files + * to the new WIM image. This gives you more control over making the new image + * compared to calling wimlib_add_image() or wimlib_add_image_multisource(). * * @param wim - * Pointer to the ::WIMStruct for the WIM file to which the image is to be - * added. + * Pointer to the ::WIMStruct to which to add the image. * @param name * Name to give the new image. If @c NULL or empty, the new image is given * no name. If nonempty, it must specify a name that does not already * exist in @p wim. * @param new_idx_ret - * If non-NULL, the index of the newly added image is returned - * in this location. + * If non-NULL, the index of the newly added image is returned in + * this location. * - * @return 0 on success; nonzero on failure. The possible error codes are: + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * 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. + * The WIM already contains an image with the requested name. */ extern int wimlib_add_empty_image(WIMStruct *wim, @@ -2166,23 +2529,22 @@ wimlib_add_empty_image(WIMStruct *wim, /** * @ingroup G_modifying_wims * - * Adds an image to a WIM file from an on-disk directory tree or NTFS volume. + * Add an image to a ::WIMStruct from an on-disk directory tree or NTFS volume. * * The directory tree or NTFS volume is scanned immediately to load the dentry - * tree into memory, and file attributes and symbolic links are read. However, - * actual file data is not read until wimlib_write() or wimlib_overwrite() is - * called. + * tree into memory, and file metadata is read. However, actual file data may + * not be read until the ::WIMStruct is persisted to disk using wimlib_write() + * or wimlib_overwrite(). * - * See the manual page for the @b wimlib-imagex program for more information + * See the documentation for the @b wimlib-imagex program for more information * about the "normal" capture mode versus the NTFS capture mode (entered by * providing the flag ::WIMLIB_ADD_FLAG_NTFS). * - * Note that @b no changes are committed to the underlying WIM file (if - * any) until wimlib_write() or wimlib_overwrite() is called. + * Note that no changes are committed to disk 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. @@ -2192,19 +2554,17 @@ wimlib_add_empty_image(WIMStruct *wim, * exist in @p wim. * @param config_file * Path to capture configuration file, or @c NULL. This file may specify, - * among other things, which files to exclude from capture. See the man - * page for wimlib-imagex capture (--config option) for - * details of the file format. If @c NULL, the default capture - * configuration shall be used. Ordinarily, the default capture + * among other things, which files to exclude from capture. See the + * documentation for wimlib-imagex capture (--config option) + * for details of the file format. If @c NULL, the default capture + * configuration will be used. Ordinarily, the default capture * configuration will result in no files being excluded from capture purely * based on name; however, the ::WIMLIB_ADD_FLAG_WINCONFIG and * ::WIMLIB_ADD_FLAG_WIMBOOT flags modify the default. * @param add_flags * Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG. * - * @return 0 on success; nonzero on error. On error, changes to @p wim are - * discarded so that it appears to be in the same state as when this function - * was called. + * @return 0 on success; a ::wimlib_error_code value on failure. * * This function is implemented by calling wimlib_add_empty_image(), then * calling wimlib_update_image() with a single "add" command, so any error code @@ -2212,7 +2572,7 @@ wimlib_add_empty_image(WIMStruct *wim, * codes returned by wimlib_update_image() other than ones documented as only * being returned specifically by an update involving delete or rename commands. * - * If a progress function is registered with @p wim, it will receive the + * If a progress function is registered with @p wim, then it will receive the * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and ::WIMLIB_PROGRESS_MSG_SCAN_END. * In addition, if ::WIMLIB_ADD_FLAG_VERBOSE is specified in @p add_flags, it * will receive ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. @@ -2235,15 +2595,10 @@ wimlib_add_image(WIMStruct *wim, * capture for full details on how this mode works. * * In addition to the error codes that wimlib_add_image() can return, - * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY - * when trying to overlay a non-directory on a directory or when otherwise - * trying to overlay multiple conflicting files to the same location in the WIM - * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if - * ::WIMLIB_ADD_FLAG_NTFS was specified in @p add_flags but there - * was not exactly one capture source with the target being the root directory. - * (In this respect, there is no advantage to using - * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting - * NTFS mode.) */ + * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY when + * trying to overlay a non-directory on a directory or when otherwise trying to + * overlay multiple conflicting files to the same location in the WIM image. + */ extern int wimlib_add_image_multisource(WIMStruct *wim, const struct wimlib_capture_source *sources, @@ -2269,65 +2624,61 @@ wimlib_add_tree(WIMStruct *wim, int image, /** * @ingroup G_creating_and_opening_wims * - * Creates a ::WIMStruct for a new WIM file. - * - * This only creates an in-memory structure for a WIM that initially contains no - * images. No on-disk file is created until wimlib_write() is called. + * Create a ::WIMStruct which initially contains no images and is not backed by + * an on-disk file. * * @param ctype - * The type of compression to be used in the new WIM file, as one of the - * ::wimlib_compression_type constants. + * The "output compression type" to assign to the ::WIMStruct. This is the + * compression type that will be used if the ::WIMStruct is later persisted + * to an on-disk file using wimlib_write(). + *
+ * This choice is not necessarily final. If desired, it can still be + * changed at any time before wimlib_write() is called, using + * wimlib_set_output_compression_type(). In addition, if you wish to use a + * non-default compression chunk size, then 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 - * ::WIMStruct must be freed using using wimlib_free() when finished with - * it. - * @return 0 on success; nonzero on error. + * On success, a pointer to the new ::WIMStruct is written to the memory + * location pointed to by this parameter. This ::WIMStruct must be freed + * using using wimlib_free() when finished with it. + * + * @return 0 on success; a ::wimlib_error_code value on failure. + * * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE * @p ctype was not a supported compression type. * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. + * Insufficient memory to allocate a new ::WIMStruct. */ extern int -wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); +wimlib_create_new_wim(enum wimlib_compression_type ctype, WIMStruct **wim_ret); /** * @ingroup G_modifying_wims * - * 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. + * Delete an image, or all images, from a ::WIMStruct. * - * Please note that @b no changes are committed to the underlying WIM file (if - * any) until wimlib_write() or wimlib_overwrite() is called. + * Note that no changes are committed to disk until wimlib_write() or + * wimlib_overwrite() is called. * * @param wim - * Pointer to the ::WIMStruct for the WIM file that contains the image(s) - * being deleted. + * Pointer to the ::WIMStruct from which to delete the image. * @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 - * possible for some but not all of the images to have been deleted when a - * failure status is returned. + * The 1-based index of the image to delete, or ::WIMLIB_ALL_IMAGES to + * delete all images. + * + * @return 0 on success; a ::wimlib_error_code value on failure. * * @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. + * @p image does not exist in the WIM. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::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 deleted. + * ::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 deleted. + * + * If this function fails when @p image was ::WIMLIB_ALL_IMAGES, then it's + * possible that some but not all of the images were deleted. */ extern int wimlib_delete_image(WIMStruct *wim, int image); @@ -2347,22 +2698,15 @@ wimlib_delete_path(WIMStruct *wim, int image, /** * @ingroup G_modifying_wims * - * Exports an image, or all the images, from a WIM file, into another WIM file. + * Export an image, or all images, from a ::WIMStruct into another ::WIMStruct. * - * 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. + * Note: after calling this function, the exported WIM image(s) cannot be + * independently modified because the image metadata will be shared between the + * two ::WIMStruct's. In addition, @p dest_wim will depend on @p src_wim, so @p + * src_wim cannot be freed until @p dest_wim is ready to be freed as well. * - * If this function fails, all changes to @p dest_wim are rolled back. - * - * Please note that no changes are committed to the underlying WIM file of @p - * dest_wim (if any) until wimlib_write() or wimlib_overwrite() is called. + * Note: no changes are committed to disk until wimlib_write() or + * wimlib_overwrite() is called. * * @param src_wim * The WIM from which to export the images, specified as a pointer to the @@ -2372,11 +2716,10 @@ wimlib_delete_path(WIMStruct *wim, int image, * referenced using wimlib_reference_resources() or * wimlib_reference_resource_files(). * @param src_image - * The image to export from @p src_wim, as either a 1-based image index to - * export a single image, or ::WIMLIB_ALL_IMAGES to export all images. + * The 1-based index of the image from @p src_wim to export, or + * ::WIMLIB_ALL_IMAGES. * @param dest_wim - * Pointer to the ::WIMStruct for a WIM that will receive the images being - * exported. + * The ::WIMStruct to which to export the images. * @param dest_name * For single-image exports, the name to give the exported image in @p * dest_wim. If left @c NULL, the name from @p src_wim is used. For @@ -2392,40 +2735,25 @@ wimlib_delete_path(WIMStruct *wim, int image, * @param export_flags * Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG. * - * @return 0 on success; nonzero on error. + * @return 0 on success; a ::wimlib_error_code value on failure. + * * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION * One or more of the names being given to an exported image was already in * use in the destination WIM. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p src_image does not exist in @p src_wim and was not - * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p src_wim and/or @p dest_wim were @c NULL; or @p src_image was - * ::WIMLIB_ALL_IMAGES but @p dest_name and/or @p dest_description were not - * @c NULL. + * @p src_image does not exist in @p src_wim. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND - * Either @p src_wim or @p dest_wim did not contain metadata resources; for - * example, one of them was a non-first part of a split WIM. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. + * At least one of @p src_wim and @p dest_wim do not contain image + * metadata. For example, one of them was a non-first part of a split WIM. * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND - * A resource that needed to be exported could not be found in either the - * source or destination WIMs. This error can occur if, for example, @p - * src_wim is part of a split WIM but needed resources from the other split - * 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. + * A file data blob that needed to be exported could not be found in the + * blob lookup table of @p src_wim. See @ref G_nonstandalone_wims. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::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 in @p src_wim - * that needed to be exported. + * ::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 in @p src_wim that needed to be exported. */ extern int wimlib_export_image(WIMStruct *src_wim, int src_image, @@ -2437,36 +2765,36 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, /** * @ingroup G_extracting_wims * - * Extracts an image, or all images, from a WIM to a directory or NTFS volume - * image. + * Extract an image, or all images, from a ::WIMStruct. * * The exact behavior of how wimlib extracts files from a WIM image is * 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. + * differences depending on the platform (UNIX-like vs Windows). See the + * documentation for wimlib-imagex apply for more information, including + * about the NTFS-3g extraction mode. * * @param wim - * The WIM from which to extract the image(s), specified as a pointer to - * the ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 - * of a split WIM. In the case of a WIM file that is not standalone, this + * The WIM from which to extract the image(s), specified as a pointer to the + * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a + * split WIM. In the case of a WIM file that is not standalone, this * ::WIMStruct must have had any needed external resources previously * referenced using wimlib_reference_resources() or * wimlib_reference_resource_files(). * @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 - * ::WIMLIB_EXTRACT_FLAG_NTFS is specified in @p extract_flags. + * The 1-based index of the image to extract, or ::WIMLIB_ALL_IMAGES to + * extract all images. Note: ::WIMLIB_ALL_IMAGES is unsupported in NTFS-3g + * extraction mode. * @param target - * Directory to extract the WIM image(s) to; or, with - * ::WIMLIB_EXTRACT_FLAG_NTFS specified in @p extract_flags, the path to - * the unmounted NTFS volume to which to extract the image. + * A null-terminated string which names the location to which the image(s) + * will be extracted. By default, this is interpreted as a path to a + * directory. Alternatively, if ::WIMLIB_EXTRACT_FLAG_NTFS is specified in + * @p extract_flags, then this is interpreted as a path to an unmounted + * NTFS volume. * @param extract_flags * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG. * - * @return 0 on success; nonzero on error. + * @return 0 on success; a ::wimlib_error_code value on failure. + * * @retval ::WIMLIB_ERR_DECOMPRESSION * Failed to decompress data contained in the WIM. * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE @@ -2474,10 +2802,9 @@ 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. + * The data of a file that needed to be extracted was corrupt. * @retval ::WIMLIB_ERR_LINK * Failed to create a symbolic link or a hard link. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND @@ -2485,8 +2812,6 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * This can happen if @p wim represents a non-first part of a split WIM. * @retval ::WIMLIB_ERR_MKDIR * Failed create a directory. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_OPEN * Could not create a file, or failed to open an already-extracted file. * @retval ::WIMLIB_ERR_READ @@ -2500,24 +2825,19 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS was specified in @p * extract_flags.) * @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). + * A file data blob that needed to be extracted could not be found in the + * blob lookup table of @p wim. See @ref G_nonstandalone_wims. * @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 @@ -2537,13 +2857,16 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags. * @retval ::WIMLIB_ERR_WIMBOOT * ::WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in @p extract_flags, but - * there was a problem creating WIMBoot pointer files. + * there was a problem creating WIMBoot pointer files or registering a + * source WIM file with the Windows Overlay Filesystem (WOF) driver. * @retval ::WIMLIB_ERR_WRITE * Failed to write data to a file being extracted. * * 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 @@ -2553,11 +2876,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 @@ -2580,21 +2902,21 @@ wimlib_extract_image(WIMStruct *wim, int image, * @param extract_flags * Same as the corresponding parameter to wimlib_extract_image(). * - * @return 0 on success; nonzero on error. The possible error codes include - * those returned by wimlib_extract_image() and wimlib_open_wim() as well as the - * following: + * @return 0 on success; a ::wimlib_error_code value on failure. The possible + * error codes include those returned by wimlib_extract_image() and + * wimlib_open_wim() as well as the following: * * @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, const wimlib_tchar *image_num_or_name, const wimlib_tchar *target, int extract_flags); -/* +/** * @ingroup G_extracting_wims * * Same as wimlib_extract_image_from_pipe(), but allows specifying a progress @@ -2614,17 +2936,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, @@ -2635,17 +2958,18 @@ 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 - * the paths to extract is "/Windows/explorer.exe" and the target is "outdir", - * the file will be extracted to "outdir/Windows/explorer.exe". This behavior - * can be changed by providing the flag - * ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE, which will cause each file - * or directory tree to be placed directly in the target directory --- so the - * same example would extract "/Windows/explorer.exe" to "outdir/explorer.exe". + * the paths to extract is /Windows/explorer.exe and the target is + * outdir, the file will be extracted to + * outdir/Windows/explorer.exe. This behavior can be changed by + * providing the flag ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE, which + * will cause each file or directory tree to be placed directly in the target + * directory --- so the same example would extract /Windows/explorer.exe + * to outdir/explorer.exe. * * Symbolic links will not be dereferenced when paths in the WIM image are * interpreted. @@ -2658,14 +2982,15 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * referenced using wimlib_reference_resources() or * wimlib_reference_resource_files(). * @param image - * 1-based index of the WIM image from which to extract the paths. + * The 1-based index of the WIM image from which to extract the paths. * @param paths * Array of paths to extract. Each element must be the absolute path to a - * file or directory within the WIM image. Separators may be either + * file or directory within the WIM image. Path 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 @@ -2685,15 +3010,13 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * @param extract_flags * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG. * - * @return 0 on success; nonzero on error. Most of the error codes are the same - * as those returned by wimlib_extract_image(). Below, some of the error codes - * returned in situations specific to path-mode extraction are documented: + * @return 0 on success; a ::wimlib_error_code value on failure. Most of the + * error codes are the same 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 + * One of the paths to extract does not exist in the WIM image. This error * code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not * specified in @p extract_flags, or if both * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS and ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB @@ -2702,12 +3025,8 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified in @p extract_flags, but * one of the paths to extract did not name a regular file. * - * If a progress function is registered with @p wim, it will receive - * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. Note that because the extraction code - * is stream-based and not file-based, there is no way to get information about - * which path is currently being extracted, but based on byte count you can - * still calculate an approximate percentage complete for the extraction overall - * which may be all you really need anyway. + * If a progress function is registered with @p wim, then it will receive + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. */ extern int wimlib_extract_paths(WIMStruct *wim, @@ -2720,26 +3039,16 @@ wimlib_extract_paths(WIMStruct *wim, /** * @ingroup G_wim_information * - * Extracts the XML data of a WIM file to a file stream. Every WIM file - * includes a string of XML that describes the images contained in the WIM. - * - * See wimlib_get_xml_data() to read the XML data into memory instead. + * Similar to wimlib_get_xml_data(), but the XML document will be written to the + * specified standard C FILE* instead of retrieved in an in-memory + * buffer. * - * @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). - * @param fp - * @c stdout, or a FILE* opened for writing, to extract the data to. + * @return 0 on success; a ::wimlib_error_code value on failure. This may + * return any error code which can be returned by wimlib_get_xml_data() as well + * as the following error codes: * - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(). - * @retval ::WIMLIB_ERR_NOMEM - * @retval ::WIMLIB_ERR_READ - * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Failed to read the XML data from the WIM. * @retval ::WIMLIB_ERR_WRITE - * Failed to completely write the XML data to @p fp. + * Failed to write the data to the requested file. */ extern int wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); @@ -2747,13 +3056,11 @@ wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); /** * @ingroup G_general * - * Frees all memory allocated for a WIMStruct and closes all files associated - * with it. + * Free all memory allocated for a WIMStruct and close all files associated with + * it. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * - * @return This function has no return value. + * Pointer to the ::WIMStruct to free. If @c NULL, no action is taken. */ extern void wimlib_free(WIMStruct *wim); @@ -2761,29 +3068,31 @@ wimlib_free(WIMStruct *wim); /** * @ingroup G_general * - * Converts a ::wimlib_compression_type value into a string. + * Convert a ::wimlib_compression_type value into a string. * * @param ctype - * The ::wimlib_compression_type value to convert. + * The compression type value to convert. * * @return - * A statically allocated string naming the compression algorithm, - * such as "None", "LZX", "XPRESS", or "Invalid". + * A statically allocated string naming the compression type, such as + * "None", "LZX", or "XPRESS". If the value was unrecognized, then + * the resulting string will be "Invalid". */ extern const wimlib_tchar * -wimlib_get_compression_type_string(int ctype); +wimlib_get_compression_type_string(enum wimlib_compression_type ctype); /** * @ingroup G_general * - * Converts an error code into a string describing it. + * Convert a wimlib error code into a string describing it. * * @param code - * The error code returned by one of wimlib's functions. + * An 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 value was unrecognized, then the resulting string will be "Unknown + * error". */ extern const wimlib_tchar * wimlib_get_error_string(enum wimlib_error_code code); @@ -2791,20 +3100,19 @@ wimlib_get_error_string(enum wimlib_error_code code); /** * @ingroup G_wim_information * - * Returns the description of the specified image. + * Get 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. + * The 1-based index of the image for which to query the description. * * @return * The description of the image, or @c NULL if there is no such image, or - * @c NULL if the specified image has no description. The description - * string is in library-internal memory and may not be modified or freed; - * in addition, the string will become invalid if the description of the - * image is changed, the image is deleted, or the ::WIMStruct is destroyed. + * @c NULL if the specified image has no description. The string may not + * remain valid after later library calls, so the caller should duplicate + * it if needed. */ extern const wimlib_tchar * wimlib_get_image_description(const WIMStruct *wim, int image); @@ -2812,20 +3120,18 @@ wimlib_get_image_description(const WIMStruct *wim, int image); /** * @ingroup G_wim_information * - * Returns the name of the specified image. + * Get 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. + * The 1-based index of the image for which to query the name. * * @return * The name of the image, or @c NULL if there is no such image, or an empty - * string if the image is unnamed. The name string is in - * library-internal memory and may not be modified or freed; in addition, - * the string will become invalid if the name of the image is changed, the - * image is deleted, or the ::WIMStruct is destroyed. + * string if the image is unnamed. The string may not remain valid after + * later library calls, so the caller should duplicate it if needed. */ extern const wimlib_tchar * wimlib_get_image_name(const WIMStruct *wim, int image); @@ -2833,12 +3139,12 @@ wimlib_get_image_name(const WIMStruct *wim, int image); /** * @ingroup G_general * - * Returns the version of wimlib as a 32-bit number whose top 12 bits contain - * the major version, the next 10 bits contain the minor version, and the low 10 + * Return the version of wimlib as a 32-bit number whose top 12 bits contain the + * major version, the next 10 bits contain the minor version, and the low 10 * 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 + * In other words, the returned value is equal to ((WIMLIB_MAJOR_VERSION << + * 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION) for the * corresponding header file. */ extern uint32_t @@ -2850,13 +3156,13 @@ 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. - * @return - * 0 + * + * @return 0 */ extern int wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); @@ -2864,29 +3170,29 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); /** * @ingroup G_wim_information * - * Read the XML data of a WIM file into an in-memory buffer. Every WIM file - * includes a string of XML that describes the images contained in the WIM. + * Read a WIM file's XML document into an in-memory buffer. * - * See wimlib_extract_xml_data() to extract the XML data to a file stream - * instead. + * The XML document contains metadata about the WIM file and the images stored + * in it. * * @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. + * XML document is written to this location. * @param bufsize_ret - * The size of the XML data in bytes is written to this location. + * The size of the XML document in bytes is written to this location. * - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(), or - * @p buf_ret or @p bufsize_ret was @c NULL. - * @retval ::WIMLIB_ERR_NOMEM + * @return 0 on success; a ::wimlib_error_code value on failure. + * + * @retval ::WIMLIB_ERR_NO_FILENAME + * @p wim is not backed by a file and therefore does not have an XML + * document. * @retval ::WIMLIB_ERR_READ + * Failed to read the XML document from the WIM file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Failed to read the XML data from the WIM. + * Failed to read the XML document from the WIM file. */ extern int wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); @@ -2895,16 +3201,15 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); * @ingroup G_general * * Initialization function for wimlib. Call before using any other wimlib - * function except wimlib_set_print_errors(). If not done manually, this - * function will be called automatically with @p init_flags set to + * function (except possibly wimlib_set_print_errors()). If not done manually, + * this function will be called automatically with @p init_flags set to * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again * after it has already successfully run. * * @param init_flags * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. * - * @return 0 on success; nonzero on failure. Currently, only the following - * error code is defined: + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES * ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES and/or @@ -2926,17 +3231,18 @@ wimlib_global_cleanup(void); /** * @ingroup G_wim_information * - * Determines if an image name is already used by some image in the WIM. + * Determine 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. * * @return * @c true if there is already an image in @p wim named @p name; @c false * if there is no image named @p name in @p wim. If @p name is @c NULL or - * the empty string, @c false is returned. + * the empty string, then @c false is returned. */ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); @@ -2946,52 +3252,42 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * * Iterate through a file or directory tree in the WIM image. By specifying * appropriate flags and a callback function, you can get the attributes of a - * file in the WIM, get a directory listing, or even get a listing of the entire - * WIM image. + * file in the WIM image, get a directory listing, or even get a listing of the + * entire WIM image. * * @param wim - * The WIM containing the image(s) over which to iterate, specified as a - * pointer to the ::WIMStruct for a standalone WIM file, a delta WIM file, - * or part 1 of a split WIM. In the case of a WIM file that is not - * standalone, this ::WIMStruct should have had any needed external - * resources previously referenced using wimlib_reference_resources() or - * wimlib_reference_resource_files(). If not, see - * ::WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED for information about - * the behavior when resources are missing. - * + * The ::WIMStruct containing the image(s) over which to iterate. This + * ::WIMStruct must contain image metadata, so it cannot be the non-first + * part of a split WIM (for example). * @param image - * The 1-based number of the image in @p wim that contains the files or - * directories to iterate over, or ::WIMLIB_ALL_IMAGES to repeat the same - * iteration on all images in the WIM. - * + * The 1-based index of the image that contains the files or directories to + * iterate over, or ::WIMLIB_ALL_IMAGES to iterate over all images. * @param path * Path in the WIM image at which to do the iteration. - * * @param flags * Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG. - * * @param cb * A callback function that will receive each directory entry. - * * @param user_ctx * An extra parameter that will always be passed to the callback function * @p cb. * * @return Normally, returns 0 if all calls to @p cb returned 0; otherwise the - * first nonzero value that was returned from @p cb. However, additional error - * codes may be returned, including the following: + * first nonzero value that was returned from @p cb. However, additional + * ::wimlib_error_code values may be returned, including the following: * * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST - * @p path did not exist in the WIM image. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate memory needed to create a ::wimlib_dir_entry. + * @p path does not exist in the WIM image. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * ::WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED was specified, but the + * data for some files could not be found in the blob lookup table of @p + * wim. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::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 over which - * iteration needed to be done. + * ::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 over which iteration needed to be done. */ extern int wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, @@ -3001,26 +3297,25 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, /** * @ingroup G_wim_information * - * Iterate through the lookup table of a WIM file. This can be used to directly - * get a listing of the unique resources contained in a WIM file over all - * images. Both file resources and metadata resources are included. However, - * only resources actually included in the file represented by @a wim, plus - * explicitly referenced external resources (via wimlib_reference_resources() or - * wimlib_reference_resource_files()) are included in the iteration. For - * example, if @p wim represents just one part of a split WIM, then only - * resources in that part will be included, unless other resources were - * explicitly referenced. + * Iterate through the blob lookup table of a ::WIMStruct. This can be used to + * directly get a listing of the unique "blobs" contained in a WIM file, which + * are deduplicated over all images. * - * @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). + * Specifically, each listed blob may be from any of the following sources: * + * - Metadata blobs, if the ::WIMStruct contains image metadata + * - File blobs from the on-disk WIM file (if any) backing the ::WIMStruct + * - File blobs from files that have been added to the in-memory ::WIMStruct, + * e.g. by using wimlib_add_image() + * - File blobs from external WIMs referenced by + * wimlib_reference_resource_files() or wimlib_reference_resources() + * + * @param wim + * Pointer to the ::WIMStruct for which to get the blob listing. * @param flags * Reserved; set to 0. - * * @param cb - * A callback function that will receive each resource. - * + * A callback function that will receive each blob. * @param user_ctx * An extra parameter that will always be passed to the callback function * @p cb. @@ -3036,7 +3331,7 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, /** * @ingroup G_nonstandalone_wims * - * Joins a split WIM into a stand-alone one-part WIM. + * Join a split WIM into a stand-alone (one-part) WIM. * * @param swms * An array of strings that gives the filenames of all parts of the split @@ -3053,9 +3348,9 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * @param output_path * The path to write the joined WIM file to. * - * @return 0 on success; nonzero on error. This function may return most error - * codes that can be returned by wimlib_open_wim() and wimlib_write(), as well - * as the following error code: + * @return 0 on success; a ::wimlib_error_code value on failure. This function + * may return most error codes that can be returned by wimlib_open_wim() and + * wimlib_write(), as well as the following error codes: * * @retval ::WIMLIB_ERR_SPLIT_INVALID * The split WIMs do not form a valid WIM because they do not include all @@ -3100,12 +3395,14 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, /** * @ingroup G_mounting_wim_images * - * Mounts an image from a WIM file on a directory read-only or read-write. + * Mount an image from a WIM file on a directory read-only or read-write. * * @param wim - * Pointer to the ::WIMStruct containing the image to be mounted. + * Pointer to the ::WIMStruct containing the image to be mounted. This + * ::WIMStruct must have a backing file. * @param image - * The 1-based index of the image to mount. + * The 1-based index of the image to mount. This image cannot have been + * previously modified in memory. * @param dir * The path to an existing empty directory on which to mount the WIM image. * @param mount_flags @@ -3117,20 +3414,19 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * storing modified or added files will be created. Ignored if * ::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. + * the backing WIM file. The staging directory is automatically deleted + * when the image is unmounted. * - * @return 0 on success; nonzero on error. The possible error codes include: + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_ALREADY_LOCKED - * An image from the WIM file is already mounted read-write, or another - * process is currently appending data to the WIM file. + * Another process is currently modifying the WIM file. * @retval ::WIMLIB_ERR_FUSE * A non-zero status code was returned by @c fuse_main(). * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not specify an existing, single image in @p wim. + * @p image does not exist 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 @@ -3141,31 +3437,28 @@ 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, - * ::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 the image to mount. + * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which + * indicate failure (for different reasons) to read the metadata resource for + * the image to mount. * * The ability to mount WIM image is implemented using FUSE (Filesystem in * UserSpacE). Depending on how FUSE is set up on your system, this function * may work as normal users in addition to the root user. * * Mounting WIM images is not supported if wimlib was configured - * --without-fuse. This includes Windows builds of wimlib; + * --without-fuse. This includes Windows builds of wimlib; * ::WIMLIB_ERR_UNSUPPORTED will be returned in such cases. * * Calling this function daemonizes the process, unless * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early error occurs. * - * It is safe to mount multiple images from the same underlying WIM file - * read-only at the same time, but only if different ::WIMStruct's are used. It - * is @b not safe to mount multiple images from the same WIM file read-write at - * the same time. + * It is safe to mount multiple images from the same WIM file read-only at the + * same time, but only if different ::WIMStruct's are used. It is @b not safe + * to mount multiple images from the same WIM file read-write at the same time. * * To unmount the image, call wimlib_unmount_image(). This may be done in a * different process. @@ -3180,71 +3473,68 @@ wimlib_mount_image(WIMStruct *wim, /** * @ingroup G_creating_and_opening_wims * - * Opens a WIM file and creates a ::WIMStruct for it. + * Open a WIM file and create a ::WIMStruct for it. * * @param wim_file * The path to the WIM file to open. - * * @param open_flags * Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG. - * * @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 - * it. + * On success, a pointer to a new ::WIMStruct backed by the specified + * on-disk WIM file is written to the memory location pointed to by this + * parameter. This ::WIMStruct must be freed using using wimlib_free() + * when finished with it. + * + * @return 0 on success; a ::wimlib_error_code value on failure. * - * @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 file failed the integrity check. * @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, @@ -3256,10 +3546,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 - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, the + * 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, then 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, @@ -3271,76 +3562,57 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, /** * @ingroup G_writing_and_overwriting_wims * - * Overwrites the file that the WIM was originally read from, with changes made. - * This only makes sense for ::WIMStruct's obtained from wimlib_open_wim() - * rather than wimlib_create_new_wim(). - * - * There are two ways that a WIM may be overwritten. The first is to do a full - * 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. - * - * 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 - * disadvantage is that some space will be wasted. Writing a WIM in this mode - * begins with writing any new file resources *after* everything in the old WIM, - * even though this will leave a hole where the old lookup table, XML data, and - * integrity were. This is done so that the WIM remains valid even if the - * operation is aborted mid-write. The WIM header is only overwritten at the - * very last moment, and up until that point the WIM will be seen as the old - * version. - * - * By default, wimlib_overwrite() does the append-style overwrite described - * above, unless resources in the WIM are arranged in an unusual way or if - * images have been deleted from the WIM. Use the flag - * ::WIMLIB_WRITE_FLAG_REBUILD to explicitly request a full rebuild, and use the - * ::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. + * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it + * as needed. + * + * There are two alternative ways in which changes may be committed: + * + * 1. Full rebuild: write the updated WIM to a temporary file, then rename the + * temporary file to the original. + * 2. Appending: append updates to the new original WIM file, then overwrite + * its header such that those changes become visible to new readers. + * + * Append mode is often much faster, but it wastes some amount of space due to + * leaving "holes" in the WIM file. Because of the greater efficiency, + * wimlib_overwrite() normally defaults to append mode. However, + * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild. + * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then + * the default mode switches to rebuild mode, and + * ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append + * mode. + * + * If this function completes successfully, then no more functions can be called + * on the ::WIMStruct other than wimlib_free(). If you need to continue using + * the WIM file, you must use wimlib_open_wim() to open a new ::WIMStruct for + * it. * * @param wim - * Pointer to the ::WIMStruct for the WIM file to write. There may have - * been in-memory changes made to it, which are then reflected in the - * output file. + * Pointer to a ::WIMStruct to commit to its backing 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()). + * The number of threads to use for compressing data, or 0 to have the + * library automatically choose an appropriate number. * - * @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: + * @return 0 on success; a ::wimlib_error_code value on failure. This function + * may return most error codes returned by wimlib_write() as well as the + * following error codes: * * @retval ::WIMLIB_ERR_ALREADY_LOCKED - * The WIM was going to be modified in-place (with no temporary file), but - * an exclusive advisory lock on the on-disk WIM file could not be acquired - * because another thread or process has mounted an image from the WIM - * read-write or is currently modifying the WIM in-place. + * Another process is currently modifying the WIM file. * @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 is not backed by an on-disk file. In other words, it is a + * ::WIMStruct created by wimlib_create_new_wim() rather than + * 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. + * The temporary file to which the WIM was written could not be renamed to + * the original file. * @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. * - * If a progress function is registered with @p wim, it will receive the + * If a progress function is registered with @p wim, then it will receive the * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END. @@ -3351,14 +3623,14 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads); /** * @ingroup G_wim_information * - * Prints information about one image, or all images, contained in a WIM. + * Print 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 - * WIM. + * The 1-based index of the image for which to print information, or + * ::WIMLIB_ALL_IMAGES to print information about all images. * * @return This function has no return value. No error checking is done when * printing the information. If @p image is invalid, an error message is @@ -3370,20 +3642,18 @@ wimlib_print_available_images(const WIMStruct *wim, int image); /** * @ingroup G_wim_information * - * Deprecated in favor of wimlib_get_wim_info(), which provides the information - * in a way that can be accessed programatically. + * Print the header of the WIM file (intended for debugging only). */ extern void -wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; +wimlib_print_header(const WIMStruct *wim); /** * @ingroup G_nonstandalone_wims * - * Reference resources from other WIM files or split WIM parts. This function + * Reference file data from other WIM files or split WIM parts. This function * can be used on WIMs that are not standalone, such as split or "delta" WIMs, - * to load needed resources (that is, "streams" keyed by SHA1 message digest) - * from other files, before calling a function such as wimlib_extract_image() - * that requires the resources to be present. + * to load additional file data before calling a function such as + * wimlib_extract_image() that requires the file data to be present. * * @param wim * The ::WIMStruct for a WIM that contains metadata resources, but is not @@ -3406,14 +3676,12 @@ wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; * Additional open flags, such as ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY, to * pass to internal calls to wimlib_open_wim() on the reference files. * - * @return 0 on success; nonzero on error. + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_GLOB_HAD_NO_MATCHES * One of the specified globs did not match any paths (only with both * ::WIMLIB_REF_FLAG_GLOB_ENABLE and ::WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH * specified in @p ref_flags). - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate memory. * @retval ::WIMLIB_ERR_READ * I/O or permissions error while processing a file glob. * @@ -3443,19 +3711,13 @@ wimlib_reference_resource_files(WIMStruct *wim, * @param num_resource_wims * Number of entries in @p resource_wims. * @param ref_flags - * Currently ignored (set to 0). - * - * @return 0 on success; nonzero on error. On success, the ::WIMStruct's of the - * @p resource_wims are referenced internally by @p wim and must not be freed - * with wimlib_free() or overwritten with wimlib_overwrite() until @p wim has - * been freed with wimlib_free(), or immediately before freeing @p wim with - * wimlib_free(). + * Reserved; must be 0. * - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p wim was @c NULL, or @p num_resource_wims was nonzero but @p - * resource_wims was @c NULL, or an entry in @p resource_wims was @p NULL. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate memory. + * @return 0 on success; a ::wimlib_error_code value on failure. On success, + * the ::WIMStruct's of the @p resource_wims are referenced internally by @p wim + * and must not be freed with wimlib_free() or overwritten with + * wimlib_overwrite() until @p wim has been freed with wimlib_free(), or + * immediately before freeing @p wim with wimlib_free(). */ extern int wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, @@ -3464,7 +3726,7 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, /** * @ingroup G_modifying_wims * - * Declares that a newly added image is mostly the same as a prior image, but + * Declare that a newly added image is mostly the same as a prior image, but * captured at a later point in time, possibly with some modifications in the * intervening time. This is designed to be used in incremental backups of the * same filesystem or directory tree. @@ -3473,12 +3735,12 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, * image against that of the old image. Any files that are present in both the * newly added image and the old image and have timestamps that indicate they * haven't been modified are deemed not to have been modified and have their - * SHA1 message digest copied from the old image. Because of this and because - * WIM uses single-instance streams, such files need not be read from the - * filesystem when the WIM is being written or overwritten. Note that these - * unchanged files will still be "archived" and will be logically present in the - * new image; the optimization is that they don't need to actually be read from - * the filesystem because the WIM already contains them. + * checksums copied from the old image. Because of this and because WIM uses + * single-instance streams, such files need not be read from the filesystem when + * the WIM is being written or overwritten. Note that these unchanged files + * will still be "archived" and will be logically present in the new image; the + * optimization is that they don't need to actually be read from the filesystem + * because the WIM already contains them. * * This function is provided to optimize incremental backups. The resulting WIM * file will still be the same regardless of whether this function is called. @@ -3492,40 +3754,35 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, * wimlib_overwrite()). * * @param wim - * Pointer to the ::WIMStruct for a WIM. + * Pointer to the ::WIMStruct containing the newly added image. * @param new_image - * 1-based index in the WIM of the newly added image. This image can have - * been added with wimlib_add_image() or wimlib_add_image_multisource(), or - * wimlib_add_empty_image() followed by wimlib_update_image(). + * The 1-based index in @p wim of the newly added image. * @param template_wim - * The ::WIMStruct for the WIM containing the template image. This can be - * the same as @p wim, or it can be a different ::WIMStruct. + * Pointer to the ::WIMStruct containing the template image. This can be, + * but does not have to be, the same ::WIMStruct as @p wim. * @param template_image - * 1-based index in the WIM of a template image that reflects a prior state - * of the directory tree being captured. + * The 1-based index in @p template_wim of the template image. * @param flags * Reserved; must be 0. * - * @return 0 on success; nonzero on error. + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p new_image and/or @p template_image were not a valid image indices in - * the WIM. + * @p new_image does not exist in @p wim or @p template_image does not + * exist in @p template_wim. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND * The specified ::WIMStruct did not actually contain the metadata resource * for the new or template image; for example, it was a non-first part of a * split WIM. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p new_image was equal to @p template_image, or @p new_image specified * an image that had not been modified since opening the WIM. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::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 the template image. + * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which + * indicate failure (for different reasons) to read the metadata resource for + * the template image. */ extern int wimlib_reference_template_image(WIMStruct *wim, int new_image, @@ -3535,7 +3792,7 @@ wimlib_reference_template_image(WIMStruct *wim, int new_image, /** * @ingroup G_general * - * Registers a progress function with a ::WIMStruct. + * Register a progress function with a ::WIMStruct. * * @param wim * The ::WIMStruct for which to register the progress function. @@ -3568,7 +3825,7 @@ wimlib_rename_path(WIMStruct *wim, int image, /** * @ingroup G_wim_information * - * Translates a string specifying the name or number of an image in the WIM into + * Translate a string specifying the name or number of an image in the WIM into * the number of the image. The images are numbered starting at 1. * * @param wim @@ -3591,166 +3848,93 @@ wimlib_rename_path(WIMStruct *wim, int image, * was specified, ::WIMLIB_ALL_IMAGES is returned. Otherwise, * ::WIMLIB_NO_IMAGE is returned. If @p image_name_or_num was @c NULL or * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more - * images in @p wim has no name. + * images in @p wim has no name. (Since a WIM may have multiple unnamed + * images, an unnamed image must be specified by index to eliminate the + * ambiguity.) */ extern int wimlib_resolve_image(WIMStruct *wim, const wimlib_tchar *image_name_or_num); /** - * @ingroup G_modifying_wims - * - * Changes the description of an image in the WIM. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM. - * @param image - * The number of the image for which to change the description. - * @param description - * The new description to give the image. It may be @c NULL, which - * indicates that the image is to be given no description. - * - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not specify a single existing image in @p wim. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate the memory needed to duplicate the @p 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, - const wimlib_tchar *description); - -/** - * @ingroup G_writing_and_overwriting_wims - * - * 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. + * @ingroup G_general * - * 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 - * size of each stream ("file") being compressed. + * Set the file to which the library will print error and warning messages. * - * @param wim - * ::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. + * 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. * - * @return 0 on success; nonzero on error. + * This also enables error messages, as if by a call to + * wimlib_set_print_errors(true). * - * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * @p chunk_size is not a supported chunk size for the currently selected - * output compression type. - */ -extern int -wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); - -/** - * @ingroup G_writing_and_overwriting_wims + * @return 0 on success; a ::wimlib_error_code value on failure. * - * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing - * packed streams (solid blocks). + * @retval ::WIMLIB_ERR_UNSUPPORTED + * wimlib was compiled using the --without-error-messages option. */ extern int -wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size); +wimlib_set_error_file(FILE *fp); /** - * @ingroup G_writing_and_overwriting_wims + * @ingroup G_general * - * Set the compression type of a WIM to use in subsequent calls to - * wimlib_write() or wimlib_overwrite(). + * Set the path to the file to which the library will print error and warning + * messages. The library will open this file for appending. * - * @param wim - * ::WIMStruct for a WIM. - * @param ctype - * The compression type to set (one of ::wimlib_compression_type). If this - * compression type is incompatible with the current output chunk size - * (either the default or as set with wimlib_set_output_chunk_size()), the - * output chunk size is reset to the default for that compression type. + * 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_INVALID_COMPRESSION_TYPE - * @p ctype did not specify a valid compression type. - */ -extern int -wimlib_set_output_compression_type(WIMStruct *wim, int ctype); - -/** - * @ingroup G_writing_and_overwriting_wims + * @return 0 on success; a ::wimlib_error_code value on failure. * - * Similar to wimlib_set_output_compression_type(), but set the compression type - * for writing packed streams (solid blocks). + * @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_output_pack_compression_type(WIMStruct *wim, int ctype); +wimlib_set_error_file_by_name(const wimlib_tchar *path); /** * @ingroup G_modifying_wims * - * Set basic information about a WIM. + * Change the description of a WIM image. * * @param wim - * Pointer to the ::WIMStruct for a WIM. - * @param info - * A struct ::wimlib_wim_info that contains the information to set. Only - * the information explicitly specified in the @p which flags need be - * valid. - * @param which - * Flags that specify which information to set. This is a bitwise OR of - * ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID, - * ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG. + * Pointer to the ::WIMStruct for the WIM. + * @param image + * The 1-based index of the image for which to change the description. + * @param description + * The new description to give the image. It may be @c NULL, which + * indicates that the image is to be given no description. * - * @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 - * index in the WIM. + * @return 0 on success; a ::wimlib_error_code value on failure. + * + * @retval ::WIMLIB_ERR_INVALID_IMAGE + * @p image does not exist in @p wim. */ extern int -wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, - int which); +wimlib_set_image_descripton(WIMStruct *wim, int image, + const wimlib_tchar *description); /** * @ingroup G_modifying_wims * - * Changes what is written in the \ element in the WIM XML data - * (something like "Core" or "Ultimate") + * Change what is stored in the \ element in the WIM XML document + * (usually something like "Core" or "Ultimate") * * @param wim - * Pointer to the ::WIMStruct for a WIM. + * Pointer to the ::WIMStruct for the WIM. * @param image - * The number of the image for which to change the description. + * The 1-based index of the image for which to change the flags. * @param flags * The new \ element to give the image. It may be @c NULL, which * indicates that the image is to be given no \ element. * - * @return 0 on success; nonzero on error. + * @return 0 on success; a ::wimlib_error_code value on failure. + * * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not specify a single existing image in @p wim. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate the memory needed to duplicate the @p flags string. - * @retval ::WIMLIB_ERR_WIM_IS_READONLY - * @p wim is considered read-only because of any of the reasons mentioned - * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. + * @p image does not exist in @p wim. */ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); @@ -3758,27 +3942,23 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** * @ingroup G_modifying_wims * - * Changes the name of an image in the WIM. + * Change the name of a WIM image. * * @param wim - * Pointer to the ::WIMStruct for a WIM. + * Pointer to the ::WIMStruct for the WIM. * @param image - * The number of the image for which to change the name. + * The 1-based index of the image for which to change the name. * @param name * New name to give the new image. If @c NULL or empty, the new image is - * given no name. If nonempty, it must specify a name that does not - * already exist in @p wim. + * given no name. Otherwise, it must specify a name that does not already + * exist in @p wim. + * + * @return 0 on success; a ::wimlib_error_code value on failure. * - * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * There is already an image named @p name in @p wim. + * The WIM already contains an image with the requested name. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not specify a single existing image in @p wim. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate the memory needed to duplicate the @p 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. + * @p image does not exist in @p wim. */ extern int wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); @@ -3790,11 +3970,11 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * * These settings are global and not per-WIM. * - * The default is to use the default @c malloc() and @c free() from the C - * library. + * The default is to use the default @c malloc(), @c free(), and @c realloc() + * from the standard C library. * - * Please note that some external functions, such as those in @c libntfs-3g, may - * use the standard memory allocation functions. + * Note: some external functions, such as those in @c libntfs-3g, may 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 @@ -3808,6 +3988,7 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * A function equivalent to @c realloc() that wimlib will use to reallocate * memory. If @c NULL, the free function is set back to the default @c * realloc() from the C library. + * * @return 0 */ extern int @@ -3816,43 +3997,139 @@ wimlib_set_memory_allocator(void *(*malloc_func)(size_t), void *(*realloc_func)(void *, size_t)); /** - * @ingroup G_general + * @ingroup G_writing_and_overwriting_wims + * + * Set a ::WIMStruct's output compression chunk size. This is the compression + * chunk size that will be used for writing non-solid resources in subsequent + * calls to wimlib_write() or wimlib_overwrite(). A larger compression chunk + * size often results in a better compression ratio, but compression may be + * slower and the speed of random access to data may be reduced. In addition, + * some chunk sizes are not compatible with Microsoft software. + * + * @param wim + * The ::WIMStruct for which to set the output chunk size. + * @param chunk_size + * The chunk size (in bytes) to set. The valid chunk sizes are dependent + * on the compression type. See the documentation for each + * ::wimlib_compression_type constant for more information. As a special + * case, if @p chunk_size is specified as 0, then the chunk size will be + * reset to the default for the currently selected output compression type. * - * Sets whether wimlib is to print error messages to @c stderr when a function - * fails. These error messages may provide information that cannot be - * determined only from the error code that is returned. Not every error will - * result in an error message being printed. + * @return 0 on success; a ::wimlib_error_code value on failure. * - * This setting is global and not per-WIM. + * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE + * @p chunk_size was not 0 or a supported chunk size for the currently + * selected output compression type. + */ +extern int +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 + * solid resources. + */ +extern int +wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Set a ::WIMStruct's output compression type. This is the compression type + * that will be used for writing non-solid resources in subsequent calls to + * wimlib_write() or wimlib_overwrite(). + * + * @param wim + * The ::WIMStruct for which to set the output compression type. + * @param ctype + * The compression type to set. If this compression type is incompatible + * with the current output chunk size, then the output chunk size will be + * reset to the default for the new compression type. + * + * @return 0 on success; a ::wimlib_error_code value on failure. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype did not specify a valid compression type. + */ +extern int +wimlib_set_output_compression_type(WIMStruct *wim, + enum wimlib_compression_type ctype); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Similar to wimlib_set_output_compression_type(), but set the compression type + * for writing solid resources. This cannot be ::WIMLIB_COMPRESSION_TYPE_NONE. + */ +extern int +wimlib_set_output_pack_compression_type(WIMStruct *wim, + enum wimlib_compression_type ctype); + +/** + * @ingroup G_general + * + * Set whether wimlib can print error and warning messages to the error file, + * which defaults to standard error. Error and warning messages may provide + * information that cannot be determined only from returned error codes. * * By default, error messages are not printed. * + * This setting applies globally (it is not per-WIM). + * * This can be called before wimlib_global_init(). * * @param show_messages - * @c true if error messages are to be printed; @c false if error messages - * are not to be printed. + * @c true if messages are to be printed; @c false if messages are not to + * be printed. + * + * @return 0 on success; a ::wimlib_error_code value on failure. * - * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_UNSUPPORTED - * @p show_messages was @c true, but wimlib was compiled with the @c - * --without-error-messages option. Therefore, error messages cannot be - * shown. + * wimlib was compiled using the --without-error-messages option. */ extern int wimlib_set_print_errors(bool show_messages); +/** + * @ingroup G_modifying_wims + * + * Set basic information about a WIM. + * + * @param wim + * Pointer to the ::WIMStruct for a WIM. + * @param info + * Pointer to a ::wimlib_wim_info structure that contains the information + * to set. Only the information explicitly specified in the @p which flags + * need be valid. + * @param which + * Flags that specify which information to set. This is a bitwise OR of + * ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID, + * ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG. + * + * @return 0 on success; a ::wimlib_error_code value on failure. + * + * @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 + * index in the WIM. + */ +extern int +wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, + int which); + /** * @ingroup G_nonstandalone_wims * - * Splits a WIM into multiple parts. + * Split a WIM into multiple parts. * * @param wim * The ::WIMStruct for the WIM to split. * @param swm_name - * Name of the SWM file to create. This will be the name of the first - * part. The other parts will have the same name with 2, 3, 4, ..., etc. - * appended before the suffix. + * Name of the split WIM (SWM) file to create. This will be the name of + * the first part. The other parts will, by default, have the same name + * with 2, 3, 4, ..., etc. appended before the suffix. However, the exact + * names can be customized using the progress function. * @param part_size * The maximum size per part, in bytes. Unfortunately, it is not * guaranteed that this will really be the maximum size per part, because @@ -3864,20 +4141,18 @@ wimlib_set_print_errors(bool show_messages); * flags will be used to write each split WIM part. Specify 0 here to get * the default behavior. * - * @return 0 on success; nonzero on error. This function may return most error - * codes that can be returned by wimlib_write() as well as the following error - * codes: + * @return 0 on success; a ::wimlib_error_code value on failure. This function + * may return most error codes that can be returned by wimlib_write() as well as + * the following error codes: * * @retval ::WIMLIB_ERR_INVALID_PARAM * @p swm_name was not a nonempty string, or @p part_size was 0. + * @retval ::WIMLIB_ERR_UNSUPPORTED + * The WIM contains solid resources. Splitting a WIM containing solid + * resources is not supported. * - * 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 + * If a progress function is registered with @p wim, then for each split WIM + * part that is written it will receive the messages * ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. */ @@ -3887,10 +4162,50 @@ wimlib_split(WIMStruct *wim, uint64_t part_size, int write_flags); +/** + * @ingroup G_general + * + * Perform verification checks on a WIM file. + * + * This function is intended for safety checking and/or debugging. If used on a + * well-formed WIM file, it should always succeed. + * + * @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. + * + * @return 0 if the WIM file was successfully verified; a ::wimlib_error_code + * value if it failed verification or another error occurred. + * + * @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 + * File data stored in the WIM file is corrupt. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * The data for a file in an image could not be found. See @ref + * G_nonstandalone_wims. + * + * If a progress function is registered with @p wim, then 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 * - * Unmounts a WIM image that was mounted using wimlib_mount_image(). + * Unmount a WIM image that was mounted using wimlib_mount_image(). * * When unmounting a read-write mounted image, the default behavior is to * discard changes to the image. Use ::WIMLIB_UNMOUNT_FLAG_COMMIT to cause the @@ -3901,7 +4216,7 @@ wimlib_split(WIMStruct *wim, * @param unmount_flags * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG. * - * @return 0 on success; nonzero on error. The possible error codes include: + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT * There is no WIM image mounted on the specified directory. @@ -3914,9 +4229,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 @@ -3944,10 +4257,9 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * Update a WIM image by adding, deleting, and/or renaming files or directories. * * @param wim - * Pointer to the ::WIMStruct for the WIM file to update. + * Pointer to the ::WIMStruct containing the image to update. * @param image - * The 1-based index of the image in the WIM to update. It cannot be - * ::WIMLIB_ALL_IMAGES. + * The 1-based index of the image to update. * @param cmds * An array of ::wimlib_update_command's that specify the update operations * to perform. @@ -3956,25 +4268,24 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * @param update_flags * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0. * - * @return 0 on success; nonzero on error. On failure, all update commands will - * be rolled back, and no visible changes shall have been made to @p wim. - * Possible error codes include: + * @return 0 on success; a ::wimlib_error_code value on failure. On failure, + * all update commands will be rolled back, and no visible changes will have + * been made to @p wim. * + * @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. + * The contents of a capture configuration file were invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image did not specify a single, existing image in @p wim. + * @p image did not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_OVERLAY * Attempted to perform an add command that conflicted with previously * existing files in the WIM when an overlay was attempted. * @retval ::WIMLIB_ERR_INVALID_PARAM - * An unknown operation type was specified in the update commands; or, - * attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set - * in the @p add_flags, but the same image had previously already been - * added from an NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and - * ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add - * command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were + * An unknown operation type was specified in the update commands; or, both + * ::WIMLIB_ADD_FLAG_RPFIX and ::WIMLIB_ADD_FLAG_NORPFIX were specified in + * the @p add_flags for one add command; or ::WIMLIB_ADD_FLAG_RPFIX were * specified in the @p add_flags for an add command in which @p * wim_target_path was not the root directory of the WIM image. * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA @@ -3984,8 +4295,6 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * A delete command without ::WIMLIB_DELETE_FLAG_RECURSIVE specified was * for a WIM path that corresponded to a directory; or, a rename command * attempted to rename a directory to a non-directory. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_NOTDIR * A rename command attempted to rename a directory to a non-directory; or, * an add command was executed that attempted to set the root of the WIM @@ -4011,12 +4320,11 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * @retval ::WIMLIB_ERR_READLINK * While executing an add command, failed to read the target of a symbolic * link or junction point. - * @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED - * (Windows only) Failed to perform a reparse point fixup because of - * problems with the data of a reparse point. * @retval ::WIMLIB_ERR_STAT * While executing an add command, failed to get attributes for a file or * directory. + * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG + * A capture configuration file could not be read. * @retval ::WIMLIB_ERR_UNSUPPORTED * ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update * command, but wimlib was configured with the @c --without-ntfs-3g flag; @@ -4028,17 +4336,12 @@ 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, - * ::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 updated. + * ::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 updated. */ extern int wimlib_update_image(WIMStruct *wim, @@ -4050,11 +4353,11 @@ wimlib_update_image(WIMStruct *wim, /** * @ingroup G_writing_and_overwriting_wims * - * Writes a WIM to a file. + * Persist a ::WIMStruct to a new on-disk WIM file. * - * This brings in resources from any external locations, such as directory trees + * This brings in file data from any external locations, such as directory trees * or NTFS volumes scanned with wimlib_add_image(), or other WIM files via - * wimlib_export_image(), and incorporates them into a new on-disk WIM file. + * wimlib_export_image(), and incorporates it into a new on-disk WIM file. * * By default, the new WIM file is written as stand-alone. Using the * ::WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS flag, a "delta" WIM can be written @@ -4062,65 +4365,47 @@ wimlib_update_image(WIMStruct *wim, * wimlib_split() for that. * * @param wim - * Pointer to the ::WIMStruct for a WIM. There may have been in-memory - * changes made to it, which are then reflected in the output file. + * Pointer to the ::WIMStruct being persisted. * @param path - * The path to the file to write the WIM to. + * The path to the on-disk file to write. * @param image * Normally, specify ::WIMLIB_ALL_IMAGES here. This indicates that all * images are to be included in the new on-disk WIM file. If for some - * reason you only want to include a single image, specify the index of - * that image instead. + * reason you only want to include a single image, specify the 1-based + * index of that image instead. * @param write_flags - * Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG. + * Bitwise OR of 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). + * The number of threads to use for compressing data, or 0 to have the + * library automatically choose an appropriate number. * - * @return 0 on success; nonzero on error. + * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not specify a single existing image in @p wim, and is not - * ::WIMLIB_ALL_IMAGES. + * @p image did not exist in @p wim. * @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, stored in another WIM, which needed to be written was corrupt; + * or a file that had previously been scanned for inclusion in the WIM was + * concurrently modified. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p path was @c NULL. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. + * @p path was not a nonempty string, or invalid flags were passed. * @retval ::WIMLIB_ERR_OPEN - * Failed to open @p path for writing, or some file resources in @p wim - * refer to files in the outside filesystem, and one of these files could - * not be opened for reading. + * Failed to open the output WIM file for writing, or failed to open a file + * whose data needed to be included in the WIM. * @retval ::WIMLIB_ERR_READ - * An error occurred when trying to read data from the WIM file associated - * with @p wim, or some file resources in @p wim refer to files in the - * outside filesystem, and a read error occurred when reading one of these - * files. + * Failed to read data that needed to be included in the WIM. * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND - * A stream that needed to be written could not be found in the stream - * lookup table of @p wim. This error can occur if, for example, @p wim is - * part of a split WIM but needed resources from the other split WIM parts - * were not referenced with wimlib_reference_resources() or - * wimlib_reference_resource_files() before the call to wimlib_write(). + * A file data blob that needed to be written could not be found in the + * blob lookup table of @p wim. See @ref G_nonstandalone_wims. * @retval ::WIMLIB_ERR_WRITE * An error occurred when trying to write data to the new WIM file. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::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. + * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which + * indicate failure (for different reasons) to read the data from a WIM file. * - * If a progress function is registered with @p wim, it will receive the + * If a progress function is registered with @p wim, then it will receive the * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END. @@ -4135,18 +4420,18 @@ 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. * - * Returns 0 on success; nonzero on failure. The possible error codes include - * those that can be returned by wimlib_write() as well as the following: + * @return 0 on success; a ::wimlib_error_code value on failure. The possible + * error codes include those that can be returned by wimlib_write() as well as + * the following: * * @retval ::WIMLIB_ERR_INVALID_PARAM * @p fd was not seekable, but ::WIMLIB_WRITE_FLAG_PIPABLE was not @@ -4162,157 +4447,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; the suggested default. */ -#define WIMLIB_LZX_ALGORITHM_FAST 0 - - /** Slower LZX compression algorithm that provides a better compression - * ratio. */ -#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 only outputs - * 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; - - /** Maximum number of potentially good matches to - * consider for each position. Suggested value: 3. */ - uint32_t max_matches_per_pos; - - uint32_t slow_reserved2[2]; - - /** 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; - - /** Maximum number of potentially good matches to consider at each - * position. Suggested value: 3. */ - uint32_t max_matches_per_pos; - - /** 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; @@ -4320,85 +4467,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. * - * @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. + * 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. * - * @return 0 on success; nonzero on error. + * 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 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; a ::wimlib_error_code value on failure. * * @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. + * Return the approximate number of bytes needed to allocate a compressor with + * 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. + * @return 0 on success; a ::wimlib_error_code value on failure. * * @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 @@ -4407,8 +4604,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, @@ -4419,71 +4616,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. + * @return 0 on success; a ::wimlib_error_code value on failure. * * @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. @@ -4492,11 +4669,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. + * @return 0 on success; nonzero on failure. + * + * 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, @@ -4507,7 +4695,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);