X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=9c043c1ba5d31e2d112c4ba8997ec481508bc832;hp=9bd9ac105431748fa83322eaf8a8b32b9973ed2d;hb=4c532e2a9f1a40e1c1a6ed44a50025cfbfab6e4f;hpb=f3794f3cb3fb5d90e0e712008e524baf71818fce diff --git a/include/wimlib.h b/include/wimlib.h index 9bd9ac10..9c043c1b 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2012, 2013 Eric Biggers + * Copyright (C) 2012, 2013, 2014 Eric Biggers * * This file is part of wimlib, a library for working with WIM files. * @@ -31,28 +31,45 @@ /** * @mainpage * - * @section sec_intro Introduction - * - * This is the documentation for the library interface of wimlib 1.5.3, a C + * This is the documentation for the library interface of wimlib 1.7.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 sec_basic_wim_handling_concepts Basic WIM handling concepts * @@ -88,6 +105,10 @@ * you can make multiple changes to a WIM and commit them all to the underlying * file in only one overwrite operation, which is more efficient. * + * Note: before calling any other function declared in wimlib.h, + * wimlib_global_init() can (and in some cases, must) be called. See its + * documentation for more details. + * * @section sec_cleaning_up Cleaning up * * After you are done with any ::WIMStruct, you can call wimlib_free() to free @@ -170,7 +191,7 @@ * documented in the man page 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 + * - wimlib does not provide a clone of the @b PEImg tool, or the @b DISM * functionality other than that already present in @b ImageX, that allows you * to make certain Windows-specific modifications to a Windows PE image, such * as adding a driver or Windows component. Such a tool could be implemented @@ -251,27 +272,22 @@ * * @brief Extract files, directories, and images from a WIM. * - * wimlib_extract_image() extracts, or "applies", an image from a WIM - * (represented, as usual, by a ::WIMStruct). This normally extracts the image - * to a directory, but when supported by the build of the library there is also - * a special NTFS volume extraction mode (entered when - * ::WIMLIB_EXTRACT_FLAG_NTFS is specified) that allows extracting a WIM image - * directly to an unmounted NTFS volume. Various other flags allow further - * customization of image extraction. - * - * Another function, wimlib_extract_files(), is also provided. It can extract - * certain files or directories from a WIM image, instead of a full image. + * wimlib_extract_image() extracts, or "applies", an image from a WIM, + * represented by a ::WIMStruct. This normally extracts the image to a + * directory, but when supported by the build of the library there is also a + * special NTFS volume extraction mode (entered when ::WIMLIB_EXTRACT_FLAG_NTFS + * is specified) that allows extracting a WIM image directly to an unmounted + * NTFS volume. Various other flags allow further customization of image + * extraction. * - * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a set - * of paths from a WIM image in a manner that may be easier to use than - * wimlib_extract_files(), and also can wildcard characters. + * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a list + * of (possibly wildcard) paths from a WIM image. * - * wimlib_extract_image_from_pipe() allows an image to be extracted from a - * pipable WIM sent over a pipe; see @ref subsec_pipable_wims. + * wimlib_extract_image_from_pipe() extracts an image from a pipable WIM sent + * over a pipe; see @ref subsec_pipable_wims. * - * Note that some details of how image extraction/application 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 documented more fully in the + * manual pages for wimlib-imagex apply and wimlib-imagex extract. */ /** @defgroup G_mounting_wim_images Mounting WIM images @@ -288,17 +304,28 @@ * image read-write is an alternative to calling wimlib_update_image(). */ -/** @defgroup G_progress Progress Messages +/** + * @defgroup G_progress Progress Messages * * @brief Track the progress of long WIM operations. * - * When operating on large archives, operations such as extraction will - * naturally take a while to complete. Because of this and to improve the - * potential user-friendliness of library clients, a number of functions take a - * pointer to a progress function of type ::wimlib_progress_func_t. This - * function will be called periodically during the WIM operation(s) to report on - * the progress of the operation (for example, how many bytes have been written - * so far). + * Library users can provide a progress function which will be called + * periodically during operations such as extracting a WIM image or writing a + * WIM image. A ::WIMStruct can have a progress function of type + * ::wimlib_progress_func_t associated with it by calling + * wimlib_register_progress_function() or by opening the ::WIMStruct using + * wimlib_open_wim_with_progress(). Once this is done, the progress function + * will be called automatically during many operations, such as + * wimlib_extract_image() and wimlib_write(). + * + * Some functions that do not operate directly on a user-provided ::WIMStruct, + * such as wimlib_join(), also take the progress function directly using an + * extended version of the function, such as wimlib_join_with_progress(). + * + * In wimlib v1.7.0 and later, progress functions are no longer just + * unidirectional. You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause + * the current operation to be aborted. wimlib v1.7.0 also added the third + * argument to ::wimlib_progress_func_t, which is a user-supplied context. */ /** @defgroup G_writing_and_overwriting_wims Writing and Overwriting WIMs @@ -306,17 +333,17 @@ * @brief Write and overwrite on-disk WIM files. * * As described in @ref sec_basic_wim_handling_concepts, these functions are - * critical to the design of the library as they allow new or modified WIMs to - * actually be written to on-disk files. Generally, wimlib_write() is the - * function you need to call to write a new WIM file, and wimlib_overwrite() is - * the function you need to call to persistently update an existing WIM file. + * fundamental to the design of the library as they allow new or modified + * ::WIMStruct's to actually be written to on-disk files. Call wimlib_write() + * to write a new WIM file, or wimlib_overwrite() to persistently update an + * existing WIM file. */ /** @defgroup G_nonstandalone_wims Creating and handling non-standalone WIMs * * @brief Create and handle non-standalone WIMs, such as split and delta WIMs. * - * Normally, ::WIMStruct represents a WIM file, but there's a bit more to it + * Normally, a ::WIMStruct represents a WIM file, but there's a bit more to it * than that. Normally, WIM files are "standalone". However, WIM files can * also be arranged in non-standalone ways, such as a set of on-disk files that * together form a single "split WIM" or "delta WIM". Such arrangements are @@ -324,7 +351,7 @@ * 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_files(). This is done by + * with wimlib_extract_image() or wimlib_extract_paths(). This is done by * calling wimlib_reference_resource_files() or wimlib_reference_resources(). * * wimlib_write() can create delta WIMs as well as standalone WIMs, but a @@ -340,26 +367,28 @@ #include #include -/** @ingroup G_general +#ifdef __GNUC__ +# define _wimlib_deprecated __attribute__((deprecated)) +#else +# define _wimlib_deprecated +#endif + +/** @addtogroup G_general * @{ */ /** Major version of the library (for example, the 1 in 1.2.5). */ #define WIMLIB_MAJOR_VERSION 1 /** Minor version of the library (for example, the 2 in 1.2.5). */ -#define WIMLIB_MINOR_VERSION 5 +#define WIMLIB_MINOR_VERSION 7 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 3 +#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 @@ -388,48 +417,74 @@ 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 -#ifdef __GNUC__ -# define _wimlib_deprecated __attribute__((deprecated)) -#else -# define _wimlib_deprecated -#endif +/** Use this to specify the root directory of the WIM image. */ +#define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING +/** Use this to test if the specified path refers to the root directory of the + * WIM image. */ +#define WIMLIB_IS_WIM_ROOT_PATH(path) \ + ((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \ + (path)[1] == 0) + +/** Length of a Globally Unique Identifier (GUID) */ #define WIMLIB_GUID_LEN 16 /** - * Specifies the compression type of a WIM file. + * Specifies a compression format. Pass one of these values to + * wimlib_create_new_wim(), wimlib_create_compressor(), or + * wimlib_create_decompressor(). + * + * A WIM file has one default compression type and chunk size. Normally, each + * resource is compressed with this compression type. However, resources may be + * stored as uncompressed. In addition, a WIM with the new version number of + * 3584, or "ESD file", might contain solid blocks with different compression + * types. */ enum wimlib_compression_type { - /** An invalid compression type. */ - WIMLIB_COMPRESSION_TYPE_INVALID = -1, - - /** The WIM does not include any compressed resources. */ + /** No compression. */ WIMLIB_COMPRESSION_TYPE_NONE = 0, - /** Compressed resources in the WIM use LZX compression. */ - WIMLIB_COMPRESSION_TYPE_LZX = 1, - - /** Compressed resources in the WIM use XPRESS compression. */ - WIMLIB_COMPRESSION_TYPE_XPRESS = 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 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^26, inclusively. */ + WIMLIB_COMPRESSION_TYPE_XPRESS = 1, + + /** 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_COMPRESSION_TYPE_LZX = 2, + + /** 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_COMPRESSION_TYPE_LZMS = 3, }; /** @} */ -/** @ingroup G_progress +/** @addtogroup G_progress * @{ */ /** Possible values of the first parameter to the user-supplied @@ -437,123 +492,161 @@ enum wimlib_compression_type { enum wimlib_progress_msg { /** A WIM image is about to be extracted. @p info will point to - * ::wimlib_progress_info.extract. */ + * ::wimlib_progress_info.extract. This message is received once per + * image for calls to wimlib_extract_image() and + * wimlib_extract_image_from_pipe(). */ WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0, - /** One or more file or directory trees within a WIM image (not the full - * image) is about to be extracted. @p info will point to - * ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, + /** One or more file or directory trees within a WIM image is about to + * be extracted. @p info will point to ::wimlib_progress_info.extract. + * This message is received only once per wimlib_extract_paths() and + * wimlib_extract_pathlist(), since wimlib combines all paths into a + * single extraction operation for optimization purposes. */ + WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1, - /** The directory structure of the WIM image is about to be extracted. - * @p info will point to ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN, - - /** The directory structure of the WIM image has been successfully - * extracted. @p info will point to ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - - /** The WIM image's files resources are currently being extracted. @p - * info will point to ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + /** 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. */ + WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS = 4, /** Starting to read a new part of a split pipable WIM over the pipe. * @p info will point to ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN, - - /** All the WIM files and directories have been extracted, and - * timestamps are about to be applied. @p info will point to - * ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS, - - /** A WIM image has been successfully extracted. @p info will point to - * ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, - - /** A file or directory tree within a WIM image (not the full image) has - * been successfully extracted. @p info will point to - * ::wimlib_progress_info.extract. */ - WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, - - /** The directory or NTFS volume is about to be scanned to build a tree - * of WIM dentries in-memory. @p info will point to - * ::wimlib_progress_info.scan. */ - WIMLIB_PROGRESS_MSG_SCAN_BEGIN, - - /** A directory or file is being scanned. @p info will point to + 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 + * ::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. */ + WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END = 8, + + /** The directory or NTFS volume is about to be scanned for metadata. + * @p info will point to ::wimlib_progress_info.scan. This message is + * received once per call to wimlib_add_image(), or once per capture + * source passed to wimlib_add_image_multisource(), or once per add + * command passed to wimlib_update_image(). */ + WIMLIB_PROGRESS_MSG_SCAN_BEGIN = 9, + + /** A directory or file has been scanned. @p info will point to * ::wimlib_progress_info.scan, and its @p cur_path member will be - * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE - * is passed to wimlib_add_image(). */ - WIMLIB_PROGRESS_MSG_SCAN_DENTRY, - - /** The directory or NTFS volume has been successfully scanned, and a - * tree of WIM dentries has been built in-memory. @p info will point to - * ::wimlib_progress_info.scan. */ - WIMLIB_PROGRESS_MSG_SCAN_END, - - /** - * File resources are currently being written to the WIM. - * @p info will point to ::wimlib_progress_info.write_streams. */ - WIMLIB_PROGRESS_MSG_WRITE_STREAMS, - - /** - * The metadata resource for each image is about to be written to the - * WIM. @p info will not be valid. */ - WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, - - /** - * The metadata resource for each image has successfully been writen to - * the WIM. @p info will not be valid. */ - WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, - - /** - * The temporary file has successfully been renamed to the original WIM - * file. Only happens when wimlib_overwrite() is called and the - * overwrite is not done in-place. - * @p info will point to ::wimlib_progress_info.rename. */ - WIMLIB_PROGRESS_MSG_RENAME, - - /** The contents of the WIM are being checked against the integrity - * table. Only happens when wimlib_open_wim() is called with the - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. @p info will point to - * ::wimlib_progress_info.integrity. */ - WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY, + * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE has + * 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. */ + 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(). */ + 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. + */ + 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. */ + WIMLIB_PROGRESS_MSG_RENAME = 15, + + /** The contents of the WIM file are being checked against the integrity + * table. @p info will point to ::wimlib_progress_info.integrity. This + * message is only received (and may be received many times) when + * wimlib_open_wim_with_progress() is called with the + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. */ + WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY = 16, /** An integrity table is being calculated for the WIM being written. - * Only happens when wimlib_write() or wimlib_overwrite() is called with - * the ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY flag. @p info will point to - * ::wimlib_progress_info.integrity. */ - WIMLIB_PROGRESS_MSG_CALC_INTEGRITY, - - /** Reserved. (Previously used for WIMLIB_PROGRESS_MSG_JOIN_STREAMS, - * but in wimlib v1.5.0 this was removed to simplify the code and now - * you'll get ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages instead.) */ - WIMLIB_PROGRESS_MSG_RESERVED, + * @p info will point to ::wimlib_progress_info.integrity. This message + * is only received (and may be received many times) when a WIM file is + * being written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ + WIMLIB_PROGRESS_MSG_CALC_INTEGRITY = 17, /** A wimlib_split() operation is in progress, and a new split part is * about to be started. @p info will point to - * ::wimlib_progress_info.split. */ - WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART, + * ::wimlib_progress_info.split. */ + WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART = 19, /** A wimlib_split() operation is in progress, and a split part has been - * finished. @p info will point to ::wimlib_progress_info.split. */ - WIMLIB_PROGRESS_MSG_SPLIT_END_PART, - - /** - * A WIM update command is just about to be executed; @p info will point - * to ::wimlib_progress_info.update. + * 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. */ + WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND = 21, + + /** A WIM update command has just 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. */ + WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND = 22, + + /** A file in the WIM image is being replaced as a result of a + * ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified. + * @p info will point to ::wimlib_progress_info.replace. This is only + * received when ::WIMLIB_ADD_FLAG_VERBOSE is also specified in the add + * 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 @c \\Windows\\System32\\WimBootCompress.ini in the + * WIM image. @p info will point to + * ::wimlib_progress_info.wimboot_exclude. */ - WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND, + 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, +}; + +/** Valid return values from user-provided progress functions + * (::wimlib_progress_func_t). + * + * (Note: if an invalid value is returned, ::WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS + * will be issued.) + */ +enum wimlib_progress_status { - /** - * A WIM update command has just been executed; @p info will point to - * ::wimlib_progress_info.update. + /** The operation should be continued. This is the normal return value. */ - WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND, + WIMLIB_PROGRESS_STATUS_CONTINUE = 0, + /** The operation should be aborted. This will cause the current + * operation to fail with ::WIMLIB_ERR_ABORTED_BY_PROGRESS. */ + 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 @@ -563,148 +656,258 @@ 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 messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. */ + /** 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 { - /** Number of bytes that are going to be written for all the - * streams combined. This is the amount in uncompressed data. - * (The actual number of bytes will be less if the data is being - * written compressed.) */ + /** 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. */ uint64_t total_bytes; - /** Number of streams that are going to be written. */ + /** 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. */ uint64_t total_streams; - /** Number of uncompressed bytes that have been written so far. - * Will be 0 initially, and equal to @p total_bytes at the end. - * */ + /** 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. */ uint64_t completed_bytes; - /** Number of streams that have been written. Will be 0 - * initially, and equal to @p total_streams at the end. */ + /** 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. */ uint64_t completed_streams; - /** Number of threads that are being used to compress resources - * (if applicable). */ - unsigned num_threads; + /** Number of threads that are being used to compress streams, + * or 1 if streams are being written uncompressed. */ + uint32_t num_threads; - /** The compression type being used to write the streams; either - * ::WIMLIB_COMPRESSION_TYPE_NONE, - * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or - * ::WIMLIB_COMPRESSION_TYPE_LZX. */ - int compression_type; + /** The compression type being used to write the streams, 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). */ - unsigned total_parts; + * written (may be 0 if irrelevant). */ + uint32_t total_parts; - /** Number of split WIM parts from which streams have been - * written (may be 0 if irrelevant). */ - unsigned completed_parts; + /** This is currently broken and will always be 0. */ + uint32_t completed_parts; } write_streams; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and - * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ + /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN, + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY, and + * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ struct wimlib_progress_info_scan { - /** Directory or NTFS volume that is being scanned. */ + /** 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 + * being scanned. */ const wimlib_tchar *source; - /** Path to the file or directory that is about to be scanned, - * relative to the root of the image capture or the NTFS volume. - * */ + /** Path to the file (or directory) that has been scanned, valid + * on ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. When capturing an NTFS + * volume with ::WIMLIB_ADD_FLAG_NTFS, this path will be + * relative to the root of the NTFS volume. */ const wimlib_tchar *cur_path; + /** Dentry scan status, valid on + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. */ enum { - /** File or directory looks okay and will be captured. */ + /** The file looks okay and will be captured. */ WIMLIB_SCAN_DENTRY_OK = 0, - /** File or directory is being excluded from capture due - * to the capture configuration file, or being an - * absolute symbolic link that points outside of the - * capture directory without ::WIMLIB_ADD_FLAG_NORPFIX. - */ + /** File is being excluded from capture due to the + * capture configuration. */ WIMLIB_SCAN_DENTRY_EXCLUDED, - /** File or directory 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 + * unsupported (e.g. an encrypted or device file). */ WIMLIB_SCAN_DENTRY_UNSUPPORTED, + + /** 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 + * being adjusted. (Reparse point fixups can be + * 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; - /** Target path in the WIM. Only valid on messages - * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and - * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ - const wimlib_tchar *wim_target_path; + union { + /** Target path in the WIM image. Only valid on + * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and + * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ + const wimlib_tchar *wim_target_path; + + /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status + * 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. */ uint64_t num_dirs_scanned; /** Number of non-directories scanned so far, excluding any - * unsupported/excluded files. */ + * 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. */ uint64_t num_nondirs_scanned; /** Number of bytes of file data that have been detected so far. - * 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. */ + * + * 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. */ uint64_t num_bytes_scanned; } scan; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, - * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN, - * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, and - * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */ + /** Valid on messages + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + * ::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 + * ::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. + */ struct wimlib_progress_info_extract { - /** Number of the image being extracted (1-based). */ - int image; + /** Number of the image from which files are being extracted + * (1-based). */ + uint32_t image; - /** Flags passed to to wimlib_extract_image() */ - int extract_flags; + /** Extraction flags being used. */ + uint32_t extract_flags; - /** Full path to the WIM file being extracted. */ + /** Full path to the WIM file from which files are being + * extracted, or @c NULL if the WIMStruct has no associated + * on-disk file. */ const wimlib_tchar *wimfile_name; - /** Name of the image being extracted. */ + /** Name of the image from which files are being extracted, or + * the empty string if the image is unnamed. */ const wimlib_tchar *image_name; - /** Directory or NTFS volume to which the image is being - * extracted. */ + /** Path to the directory or NTFS volume to which the files are + * being extracted. */ const wimlib_tchar *target; /** Reserved. */ - const wimlib_tchar *cur_path; + const wimlib_tchar *reserved; /** Number of bytes of uncompressed data that will be extracted. - * Takes into account hard links (they are not counted for each - * link.) */ + * 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. */ uint64_t total_bytes; - /** Number of bytes that have been written so far. Will be 0 - * initially, and equal to @p total_bytes at the end. */ + /** 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. */ uint64_t completed_bytes; - /** Number of streams that will be extracted. This may more or - * less than the number of "files" to be extracted due to - * special cases (hard links, symbolic links, and alternate data - * streams.) */ - uint64_t num_streams; + /** 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 total_streams; - /** Path to the root dentry within the WIM for the tree that is - * being extracted. Will be the empty string when extracting a - * full image, or when extracting a set of paths using - * wimlib_extract_paths() or wimlib_extract_pathlist(). */ - const wimlib_tchar *extract_root_wim_source_path; + /** Number of (not necessarily unique) streams that have been + * extracted so far. */ + uint64_t completed_streams; /** Currently only used for * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ - - unsigned part_number; + uint32_t part_number; /** Currently only used for * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ - unsigned total_parts; + uint32_t total_parts; /** Currently only used for * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ @@ -787,25 +990,96 @@ union wimlib_progress_info { /** Name of the split WIM part that is about to be started * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been - * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */ - const wimlib_tchar *part_name; + * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). + * As of wimlib v1.7.0, the library user may change this when + * receiving ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART in order to + * cause the next split WIM part to be written to a different + * location. */ + wimlib_tchar *part_name; } split; + + /** Valid on messages ::WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM */ + struct wimlib_progress_info_replace { + /** Path to the file in the WIM image that is being replaced */ + const wimlib_tchar *path_in_wim; + } replace; + + /** Valid on messages ::WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE */ + struct wimlib_progress_info_wimboot_exclude { + /** Path to the file in the WIM image */ + const wimlib_tchar *path_in_wim; + + /** Path to which the file is being extracted */ + const wimlib_tchar *extraction_path; + } wimboot_exclude; + + /** Valid on messages ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN. */ + struct wimlib_progress_info_unmount { + /** Path to directory being unmounted */ + const wimlib_tchar *mountpoint; + + /** Path to WIM file being unmounted */ + const wimlib_tchar *mounted_wim; + + /** 1-based index of image being unmounted. */ + uint32_t mounted_image; + + /** Flags that were passed to wimlib_mount_image() when the + * mountpoint was set up. */ + uint32_t mount_flags; + + /** 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; }; -/** A user-supplied function that will be called periodically during certain WIM - * operations. The first argument will be the type of operation that is being - * performed or is about to be started or has been completed. The second - * argument will be a pointer to one of a number of structures depending on the - * first argument. It may be @c NULL for some message types. +/** + * A user-supplied function that will be called periodically during certain WIM + * operations. + * + * The first argument will be the type of operation that is being performed or + * is about to be started or has been completed. + * + * The second argument will be a pointer to one of a number of structures + * depending on the first argument. It may be @c NULL for some message types. + * Note that although this argument is not @c const, users should not modify it + * except in explicitly documented cases. + * + * The third argument will be a user-supplied value that was provided when + * registering or specifying the progress function. * - * The return value of the progress function is currently ignored, but it may do - * something in the future. (Set it to 0 for now.) + * This function must return one of the ::wimlib_progress_status values. By + * default, you should return ::WIMLIB_PROGRESS_STATUS_CONTINUE (0). */ -typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, - const union wimlib_progress_info *info); +typedef enum wimlib_progress_status + (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, + union wimlib_progress_info *info, + void *progctx); /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** An array of these structures is passed to wimlib_add_image_multisource() to @@ -815,55 +1089,14 @@ struct wimlib_capture_source { * filesystem to be included in the WIM image. */ wimlib_tchar *fs_source_path; - /** Destination path in the WIM image. Leading and trailing slashes are - * ignored. The empty string or @c NULL means the root directory of the - * WIM image. */ + /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to + * specify the root directory of the WIM image. */ wimlib_tchar *wim_target_path; /** Reserved; set to 0. */ long reserved; }; -/** Structure that specifies a list of path patterns. */ -struct wimlib_pattern_list { - /** Array of patterns. The patterns may be modified by library code, - * but the @p pats pointer itself will not. See the man page for - * wimlib-imagex capture for more information about allowed - * patterns. */ - wimlib_tchar **pats; - - /** Number of patterns in the @p pats array. */ - size_t num_pats; - - /** Ignored; may be used by the calling code. */ - size_t num_allocated_pats; -}; - -/** A structure that contains lists of wildcards that match paths to treat - * specially when capturing a WIM image. */ -struct wimlib_capture_config { - /** Paths matching any pattern this list are excluded from being - * captured, except if the same path appears in @p - * exclusion_exception_pats. */ - struct wimlib_pattern_list exclusion_pats; - - /** Paths matching any pattern in this list are never excluded from - * being captured. */ - struct wimlib_pattern_list exclusion_exception_pats; - - /** Reserved for future capture configuration options. */ - struct wimlib_pattern_list reserved1; - - /** Reserved for future capture configuration options. */ - struct wimlib_pattern_list reserved2; - - /** Library internal use only. */ - wimlib_tchar *_prefix; - - /** Library internal use only. */ - size_t _prefix_num_tchars; -}; - /** 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 @@ -891,8 +1124,11 @@ struct wimlib_capture_config { #define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 /** @} */ -/** @ingroup G_wim_information - * @{ */ + +/** @addtogroup G_wim_information + * { */ + +/** @{ */ /** General information about a WIM file. */ struct wimlib_wim_info { @@ -1024,7 +1260,7 @@ struct wimlib_resource_entry { uint64_t reserved[2]; }; -/** A stream of a file in the WIM. */ +/** Information about a stream of a particular file in the WIM. */ struct wimlib_stream_entry { /** Name of the stream, or NULL if the stream is unnamed. */ const wimlib_tchar *stream_name; @@ -1092,6 +1328,7 @@ struct wimlib_dir_entry { #define WIMLIB_REPARSE_TAG_DFS 0x8000000A #define WIMLIB_REPARSE_TAG_DFSR 0x80000012 #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 @@ -1117,7 +1354,14 @@ struct wimlib_dir_entry { /** Time this file was last accessed. */ struct timespec last_access_time; - uint64_t reserved[16]; + + /* UNIX data (wimlib extension), only valid if unix_mode != 0 */ + uint32_t unix_uid; + uint32_t unix_gid; + uint32_t unix_mode; + 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 @@ -1159,40 +1403,40 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ -/** Directly capture a NTFS volume rather than a generic directory. This flag +/** 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. */ #define WIMLIB_ADD_FLAG_NTFS 0x00000001 -/** Follow symlinks; archive and dump the files they point to. Cannot be used - * with ::WIMLIB_ADD_FLAG_NTFS. */ +/** Follow symlinks; archive and dump the files they point to. Currently only + * supported on UNIX-like systems. */ #define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002 /** Call the progress function with the message - * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to - * be scanned, or when a directory or file is being excluded from capture. */ + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been + * scanned. */ #define WIMLIB_ADD_FLAG_VERBOSE 0x00000004 -/** Mark the image being added as the bootable image of the WIM. */ +/** Mark the image being added as the bootable image of the WIM. Not valid for + * wimlib_update_image(). */ #define WIMLIB_ADD_FLAG_BOOT 0x00000008 -/** Store the UNIX owner, group, and mode. This is done by adding a special - * alternate data stream to each regular file, symbolic link, and directory to - * contain this information. Please note that this flag is for convenience - * only; Microsoft's @a imagex.exe will not understand this special information. - * This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */ +/** 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 + * --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 Win32 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 Win32 native builds. The default - * behavior without this flag is to first try omitting the SACL from the + * 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 @@ -1206,8 +1450,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** 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. + * current root. * * 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. @@ -1220,24 +1463,18 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_ADD_FLAG_NORPFIX 0x00000200 /** Do not automatically exclude unsupported files or directories from capture; - * e.g. encrypted directories in NTFS-3g capture mode, or device files and FIFOs - * on UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when + * 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. */ #define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 -/** Automatically select a capture configuration appropriate for capturing - * filesystems containing Windows operating systems. When this flag is - * specified, the corresponding @p config parameter or member must be @c NULL. - * - * Currently, selecting this capture configuration will cause the following - * files and directories to be excluded from capture: +/** + * Automatically select a capture configuration appropriate for capturing + * filesystems containing Windows operating systems. For example, + * "pagefile.sys" and "System Volume Information" will be excluded. * - * - "\$ntfs.log" - * - "\hiberfil.sys" - * - "\pagefile.sys" - * - "\System Volume Information" - * - "\RECYCLER" - * - "\Windows\CSC" + * When this flag is specified, the corresponding @p config parameter or member + * must be @c NULL. * * 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 @@ -1245,6 +1482,36 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800 +/** + * 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. + * + * Note: this will not by itself change the compression type. Before writing + * the WIM file, it's recommended to also do: + * + * \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). + */ +#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000 + +/** + * If the add command involves adding a non-directory file to a location at + * which there already exists a nondirectory file in the WIM image, issue + * ::WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. This only has an + * effect when updating an existing image with wimlib_update_image(). + * This was the default behavior in wimlib v1.6.2 and earlier. + */ +#define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000 + #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 @@ -1258,9 +1525,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \ WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE #define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG +#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT WIMLIB_ADD_FLAG_WIMBOOT + /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** Do not issue an error if the path to delete does not exist. */ @@ -1271,7 +1540,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 * @{ */ /** @@ -1290,66 +1559,76 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Give the exported image(s) no descriptions. */ #define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004 +/** This advises the library that the program is finished with the source + * WIMStruct and will not attempt to access it after the call to + * wimlib_export_image(), with the exception of the call to wimlib_free(). */ +#define WIMLIB_EXPORT_FLAG_GIFT 0x00000008 + +/** + * 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 @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); + * wimlib_set_output_chunk_size(wim, 4096); + * wimlib_add_tree(wim, image, L"myconfig.ini", + * L"\\Windows\\System32\\WimBootCompress.ini", 0); + * \endcode + */ +#define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010 + /** @} */ -/** @ingroup G_extracting_wims +/** @addtogroup G_extracting_wims * @{ */ -/** Extract the image directly to a NTFS volume rather than a generic directory. +/** Extract the image directly to an NTFS volume rather than a generic directory. * This mode is only available if wimlib was compiled with libntfs-3g support; * if not, ::WIMLIB_ERR_UNSUPPORTED will be returned. In this mode, the - * extraction target will be interpreted as the path to a NTFS volume image (as + * extraction target will be interpreted as the path to an NTFS volume image (as * a regular file or block device) rather than a directory. It will be opened * using libntfs-3g, and the image will be extracted to the NTFS filesystem's * root directory. Note: this flag cannot be used when wimlib_extract_image() - * is called with ::WIMLIB_ALL_IMAGES as the @p image. */ + * is called with ::WIMLIB_ALL_IMAGES as the @p image, nor can it be used with + * wimlib_extract_paths() when passed multiple paths. */ #define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001 -/** When identical files are extracted from the WIM, always hard link them - * together. */ -#define WIMLIB_EXTRACT_FLAG_HARDLINK 0x00000002 - -/** When identical files are extracted from the WIM, always symlink them - * together. */ -#define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004 - -/** This flag no longer does anything but is reserved for future use. */ -#define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008 - -/** Read the WIM file sequentially while extracting the image. As of wimlib - * v1.6.0 this is the default behavior, and this flag no longer does anything. - */ -#define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010 - -/** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA. Only - * valid on UNIX-like platforms, and when ::WIMLIB_EXTRACT_FLAG_NTFS was not - * specified. */ +/** UNIX-like systems only: Extract special UNIX data captured with + * ::WIMLIB_ADD_FLAG_UNIX_DATA. This flag cannot be combined with + * ::WIMLIB_EXTRACT_FLAG_NTFS. */ #define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020 -/** Do not extract security descriptors. */ +/** Do not extract security descriptors. This flag cannot be combined with + * ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS. */ #define WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040 /** Fail immediately if the full security descriptor of any file or directory * cannot be set exactly as specified in the WIM file. On Windows, the default - * behavior without this flag is to fall back to setting the security descriptor - * with the SACL omitted, then only the default inherited security descriptor, - * if we do not have permission to set the desired one. */ + * behavior without this flag when wimlib does not have permission to set the + * correct security descriptor is to fall back to setting the security + * descriptor with the SACL omitted, then with the DACL omitted, then with the + * owner omitted, then not at all. This flag cannot be combined with + * ::WIMLIB_EXTRACT_FLAG_NO_ACLS. */ #define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080 /** This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX. This forces * 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 if WIM_HDR_FLAG_RP_FIX is set in the WIM - * header. This flag may only be specified when extracting a full image (not a - * file or directory tree within one). */ + * 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. */ #define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100 /** Force reparse-point fixups on extraction off, regardless of the state of the - * WIM_HDR_FLAG_RP_FIX flag in the WIM header. */ + * WIM_HDR_FLAG_RP_FIX flag in the WIM header. This flag cannot be combined + * with ::WIMLIB_EXTRACT_FLAG_RPFIX. */ #define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200 -/** Extract the specified file to standard output. This is only valid in an - * extraction command that specifies the extraction of a regular file in the WIM - * image. */ +/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Extract the + * paths, each of which must name a regular file, to standard output. */ #define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400 /** Instead of ignoring files and directories with names that cannot be @@ -1370,27 +1649,25 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Do not ignore failure to set short names on extracted files. */ #define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000 -/** Do not ignore failure to extract symbolic links (and junction points, on - * Windows) due to permissions problems. By default, such failures are ignored - * since the default configuration of Windows only allows the Administrator to - * create symbolic links. */ +/** 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. */ #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). */ #define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 -/** Perform the extraction ordered by the tree of files to extract rather than - * how the underlying streams are arranged in the WIM file. For regular WIM - * files this may decrease or increase performance, depending on various - * factors. For WIM files containing packed streams this will decrease - * performance. */ -#define WIMLIB_EXTRACT_FLAG_FILE_ORDER 0x00020000 - /** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the - * paths in the WIM as case-insensitive globs which may contain the characters - * '?' and '*'. The '?' character matches any character, whereas the '*' - * character matches zero or more characters in the same path component. */ + * paths to extract as wildcard patterns ("globs") which may contain the + * 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. */ #define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000 /** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error @@ -1398,8 +1675,22 @@ 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. */ +#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. + */ +#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. */ +#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 + /** @} */ -/** @ingroup G_mounting_wim_images +/** @addtogroup G_mounting_wim_images * @{ */ /** Mount the WIM image read-write rather than the default of read-only. */ @@ -1408,72 +1699,90 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Enable FUSE debugging by passing the @c -d flag to @c fuse_main().*/ #define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002 -/** Do not allow accessing alternate data streams in the mounted WIM image. */ +/** Do not allow accessing named data streams in the mounted WIM image. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE 0x00000004 -/** Access alternate data streams in the mounted WIM image through extended file - * attributes. This is the default mode. */ +/** Access named data streams in the mounted WIM image through extended file + * attributes named "user.X", where X is the name of a data stream. This is the + * default mode. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR 0x00000008 -/** Access alternate data streams in the mounted WIM image by specifying the - * file name, a colon, then the alternate file stream name. */ +/** Access named data streams in the mounted WIM image by specifying the file + * name, a colon, then the name of the data stream. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010 -/** Use UNIX file owners, groups, and modes if available in the WIM (see - * ::WIMLIB_ADD_FLAG_UNIX_DATA). */ +/** Use UNIX metadata if available in the WIM image. See + * ::WIMLIB_ADD_FLAG_UNIX_DATA. */ #define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020 -/** Allow other users to see the mounted filesystem. (this passes the @c - * allow_other option to FUSE mount) */ +/** Allow other users to see the mounted filesystem. This passes the @c + * allow_other option to the FUSE mount. */ #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 /** @} */ -/** @ingroup G_creating_and_opening_wims +/** @addtogroup G_creating_and_opening_wims * @{ */ /** Verify the WIM contents against the WIM's integrity table, if present. This * causes the raw data of the WIM file, divided into 10 MB chunks, to be * checksummed and checked against the SHA1 message digests specified in the - * integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any - * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the - * integrity table is invalid). */ + * integrity table. If there are any mismatches, ::WIMLIB_ERR_INTEGRITY is + * issued. If the WIM file does not contain an integrity table, this flag has + * no effect. */ #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001 -/** Issue an error if the WIM is part of a split WIM. Software can provide - * this flag for convenience if it explicitly does not want to support split - * WIMs. */ +/** Issue an error (::WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split + * WIM. Software can provide this flag for convenience if it explicitly does + * not want to support split WIMs. */ #define WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002 -/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it - * is not. A WIM is considered writable only if it is writable at the - * filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its - * header, and is not part of a spanned set. It is not required to provide this - * flag before attempting to make changes to the WIM, but with this flag you get - * an error sooner rather than later. */ +/** Check if the WIM is writable and issue an error + * (::WIMLIB_ERR_WIM_IS_READONLY) if it is not. A WIM is considered writable + * only if it is writable at the filesystem level, does not have the + * WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned + * set. It is not required to provide this flag before attempting to make + * changes to the WIM, but with this flag you get an error sooner rather than + * later. */ #define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004 /** @} */ -/** @ingroup G_mounting_wim_images +/** @addtogroup G_mounting_wim_images * @{ */ -/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ +/** Provide ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image. + * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ #define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001 -/** Unless this flag is given, changes to a read-write mounted WIM are - * discarded. Ignored for read-only mounts. */ +/** Commit changes to the read-write mounted WIM image. + * If this flag is not specified, changes will be discarded. */ #define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002 -/** See ::WIMLIB_WRITE_FLAG_REBUILD. */ +/** Provide ::WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image. + * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ #define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004 -/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */ +/** Provide ::WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image. + * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ #define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008 -/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */ -#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010 +/** + * In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM + * image, forces all file descriptors to the open WIM image to be closed before + * committing it. + * + * Without ::WIMLIB_UNMOUNT_FLAG_COMMIT or with a read-only mounted WIM image, + * this flag has no effect. + */ +#define WIMLIB_UNMOUNT_FLAG_FORCE 0x00000010 + +/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted + * WIM image, causes the modified image to be committed to the WIM file as a + * new, unnamed image appended to the archive. The original image in the WIM + * file will be unmodified. */ +#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020 /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and @@ -1481,101 +1790,190 @@ 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 * @{ */ -/** Include an integrity table in the WIM. +/** + * Include an integrity table in the resulting WIM file. * - * For WIMs created with wimlib_open_wim(), the default behavior is to include - * an integrity table if and only if one was present before. For WIMs created - * with wimlib_create_new_wim(), the default behavior is to not include an - * integrity table. */ + * For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to + * include an integrity table if and only if one was present before. For + * ::WIMStruct's created with wimlib_create_new_wim(), the default behavior is + * to not include an integrity table. + */ #define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY 0x00000001 -/** Do not include an integrity table in the new WIM file. This is the default - * behavior, unless the WIM already included an integrity table. */ +/** + * Do not include an integrity table in the resulting WIM file. This is the + * default behavior, unless the ::WIMStruct was created by opening a WIM with an + * integrity table. + */ #define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY 0x00000002 -/** Write the WIM as "pipable". After writing a WIM with this flag specified, +/** + * 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. - * - * For WIMs created with wimlib_open_wim(), the default behavior is to write the - * WIM as pipable if and only if it was pipable before. For WIMs created with - * wimlib_create_new_wim(), the default behavior is to write the WIM as - * non-pipable. */ + * 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 + * ::WIMStruct's created with wimlib_create_new_wim(), the default behavior is + * to write the WIM as non-pipable. + */ #define WIMLIB_WRITE_FLAG_PIPABLE 0x00000004 -/** Do not write the WIM as "pipable". This is the default behavior, unless the - * WIM was pipable already. */ +/** + * Do not write the WIM as "pipable". This is the default behavior, unless the + * ::WIMStruct was created by opening a pipable WIM. + */ #define WIMLIB_WRITE_FLAG_NOT_PIPABLE 0x00000008 -/** Recompress all resources, even if they could otherwise be copied from a - * different WIM with the same compression type (in the case of - * wimlib_export_image() being called previously). This flag is also valid in - * the @p wim_write_flags of wimlib_join(), in which case all resources included - * in the joined WIM file will be recompressed. */ +/** + * 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()). + * + * ::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.7.0, it usually compresses slightly better than the competing + * Microsoft implementation and is almost as fast. + * + * ::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 + * 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 + * ::WIMLIB_WRITE_FLAG_RECOMPRESS with ::WIMLIB_WRITE_FLAG_REBUILD. + */ #define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000010 -/** Call fsync() just before the WIM file is closed. */ +/** + * Immediately before closing the WIM file, sync its data to disk. + * + * wimlib_overwrite() will set this flag automatically if it decides to + * overwrite the WIM file via a temporary file instead of in-place. + */ #define WIMLIB_WRITE_FLAG_FSYNC 0x00000020 -/** wimlib_overwrite() only: Re-build the entire WIM file rather than appending - * data to it if possible. */ +/** + * For wimlib_overwrite(), rebuild the entire WIM file, even if it otherwise + * could be updated merely by appending to it. + * + * When rebuilding the WIM file, stream reference counts will be recomputed, and + * any streams with 0 reference count (e.g. from deleted files or images) will + * not be included in the resulting WIM file. + * + * 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. + * + * wimlib_write() ignores this flag. + */ #define WIMLIB_WRITE_FLAG_REBUILD 0x00000040 -/** wimlib_overwrite() only: Specifying this flag overrides the default - * behavior of wimlib_overwrite() after one or more calls to - * wimlib_delete_image(), which is to rebuild the entire WIM. With this flag, - * only minimal changes to correctly remove the image from the WIM will be - * taken. In particular, all streams will be left alone, even if they are no - * longer referenced. This is probably not what you want, because almost no - * space will be saved by deleting an image in this way. */ +/** + * 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. + * + * wimlib_write() ignores this flag. + */ #define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080 -/** wimlib_overwrite() only: Allow overwriting the WIM even if the readonly - * flag is set in the WIM header. This can be used in combination with - * wimlib_set_wim_info() with the ::WIMLIB_CHANGE_READONLY_FLAG flag to actually - * set the readonly flag on the on-disk WIM file. */ +/** + * 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 + * ::WIMLIB_CHANGE_READONLY_FLAG flag to actually set the readonly flag on the + * on-disk WIM file. + * + * wimlib_write() ignores this flag. + */ #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 -/** Do not include non-metadata resources 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 wimlib_reference_resources(). */ +/** + * 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 + * wimlib_reference_resources(). + */ #define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200 -/** Asserts 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. - * - * This flag can be passed to wimlib_write() and wimlib_write_to_fd(), but is - * already implied for wimlib_overwrite(). */ +/** + * 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. + */ #define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 -#define WIMLIB_WRITE_FLAG_RESERVED 0x00000800 +/** + * For wimlib_write(), retain the WIM's GUID instead of generating a new one. + * + * wimlib_overwrite() sets this by default, since the WIM remains, logically, + * the same file. + */ +#define WIMLIB_WRITE_FLAG_RETAIN_GUID 0x00000800 /** * When writing streams in the resulting WIM file, pack multiple streams into a - * single WIM resource instead of compressing them independently. This tends to - * produce a better compression ratio at the cost of less random access. - * However, WIMs created with this flag are only compatible with wimlib v1.6.0 - * or later and WIMGAPI Windows 8 or later, seemingly for Windows Setup only and - * not including ImageX and Dism. WIMs created with this flag must use - * version number 3584 in their header instead of 68864. - * - * If this flag is passed to wimlib_overwrite() and the WIM did not previously - * contain packed streams, the WIM's version number will be changed to 3584 and - * the new streams will be written packed. Use ::WIMLIB_WRITE_FLAG_REBUILD to - * force the WIM to be fully rebuilt. */ + * 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. + * + * 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. + * + * Currently, new solid blocks 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 + * 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 + * into it and the WIM's main compression type is LZMS. + */ #define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000 +/** + * 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 + /** @} */ -/** @ingroup G_general +/** @addtogroup G_general * @{ */ /** Assume that strings are represented in UTF-8, even if this is not the @@ -1615,23 +2013,24 @@ 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 * @{ */ -/** wimlib_reference_resource_files() only: Enable shell-style filename - * globbing. */ +/** For wimlib_reference_resource_files(), enable shell-style filename globbing. + * Ignored by wimlib_reference_resources(). */ #define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 -/** wimlib_reference_resource_files() only: Issue an error +/** For wimlib_reference_resource_files(), issue an error * (::WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files. The * default behavior without this flag is to issue no error at that point, but * then attempt to open the glob as a literal path, which of course will fail * anyway if no file exists at that path. No effect if - * ::WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. */ + * ::WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. Ignored by + * wimlib_reference_resources(). */ #define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** The specific type of update to perform. */ @@ -1649,19 +2048,16 @@ enum wimlib_update_op { /** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ struct wimlib_add_command { - /** Filesystem path to the file or directory tree to - * add. */ + /** Filesystem path to the file or directory tree to add. */ wimlib_tchar *fs_source_path; - /** Path, specified from the root of the WIM image, at - * which to add the file or directory tree within the - * WIM image. */ + + /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to + * specify the root directory of the WIM image. */ wimlib_tchar *wim_target_path; - /** Configuration for excluded files. @c NULL means - * exclude no files (use no configuration), unless - * ::WIMLIB_ADD_FLAG_WINCONFIG is specified in @p - * add_flags. */ - struct wimlib_capture_config *config; + /** Path to capture configuration file to use, or @c NULL for default. + */ + wimlib_tchar *config_file; /** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */ int add_flags; @@ -1669,25 +2065,27 @@ struct wimlib_add_command { /** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */ struct wimlib_delete_command { - /** Path, specified from the root of the WIM image, for - * the file or directory tree within the WIM image to be - * deleted. */ + + /** Path, specified from the root of the WIM image, for the file or + * directory tree within the WIM image to be deleted. */ wimlib_tchar *wim_path; - /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ + + /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ int delete_flags; }; /** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */ struct wimlib_rename_command { - /** Path, specified from the root of the WIM image, for - * the source file or directory tree within the WIM - * image. */ + + /** Path, specified from the root of the WIM image, for the source file + * or directory tree within the WIM image. */ wimlib_tchar *wim_source_path; - /** Path, specified from the root of the WIM image, for - * the destination file or directory tree within the WIM - * image. */ + + /** Path, specified from the root of the WIM image, for the destination + * file or directory tree within the WIM image. */ wimlib_tchar *wim_target_path; - /** Reserved; set to 0. */ + + /** Reserved; set to 0. */ int rename_flags; }; @@ -1705,27 +2103,7 @@ struct wimlib_update_command { }; /** @} */ -/** @ingroup G_extracting_wims - * @{ */ - -/** Specification of a file or directory tree to extract from a WIM image. Used - * in calls to wimlib_extract_files(). */ -struct wimlib_extract_command { - /** Path to file or directory tree within the WIM image to extract. It - * must be provided as an absolute path from the root of the WIM image. - * The path separators may be either forward slashes or backslashes. */ - wimlib_tchar *wim_source_path; - - /** Filesystem path to extract the file or directory tree to. */ - wimlib_tchar *fs_dest_path; - - /** Bitwise or of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */ - int extract_flags; -}; - - -/** @} */ -/** @ingroup G_general +/** @addtogroup G_general * @{ */ /** @@ -1735,80 +2113,80 @@ struct wimlib_extract_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_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, }; @@ -1818,6 +2196,8 @@ enum wimlib_error_code { /** Used to specify all images in the WIM. */ #define WIMLIB_ALL_IMAGES (-1) +/** @} */ + /** * @ingroup G_modifying_wims * @@ -1874,8 +2254,7 @@ wimlib_add_empty_image(WIMStruct *wim, * any) until wimlib_write() or wimlib_overwrite() is called. * * @param wim - * Pointer to the ::WIMStruct for a WIM file to which the image will be - * added. + * Pointer to the ::WIMStruct to which to add the image. * @param source * A path to a directory or unmounted NTFS volume that will be captured as * a WIM image. @@ -1883,18 +2262,17 @@ wimlib_add_empty_image(WIMStruct *wim, * 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 config - * Capture configuration that specifies files, directories, or path globs - * to exclude from being captured. If @c NULL, a dummy configuration where - * no paths are treated specially is used. + * @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 + * 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. - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. The progress messages that will be - * received are ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN, - * ::WIMLIB_PROGRESS_MSG_SCAN_END, and, if ::WIMLIB_ADD_FLAG_VERBOSE was - * included in @p add_flags, also ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. * * @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 @@ -1905,14 +2283,18 @@ wimlib_add_empty_image(WIMStruct *wim, * returned by wimlib_add_empty_image() may be returned, as well as any error * 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 + * 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. */ extern int wimlib_add_image(WIMStruct *wim, const wimlib_tchar *source, const wimlib_tchar *name, - const struct wimlib_capture_config *config, - int add_flags, - wimlib_progress_func_t progress_func); + const wimlib_tchar *config_file, + int add_flags); /** * @ingroup G_modifying_wims @@ -1939,9 +2321,22 @@ wimlib_add_image_multisource(WIMStruct *wim, const struct wimlib_capture_source *sources, size_t num_sources, const wimlib_tchar *name, - const struct wimlib_capture_config *config, - int add_flags, - wimlib_progress_func_t progress_func); + const wimlib_tchar *config_file, + int add_flags); + +/** + * @ingroup G_modifying_wims + * + * Add the file or directory tree at @p fs_source_path on the filesystem to the + * location @p wim_target_path within the specified @p image of the @p wim. + * + * This just builds an appropriate ::wimlib_add_command and passes it to + * wimlib_update_image(). + */ +extern int +wimlib_add_tree(WIMStruct *wim, int image, + const wimlib_tchar *fs_source_path, + const wimlib_tchar *wim_target_path, int add_flags); /** * @ingroup G_creating_and_opening_wims @@ -1952,18 +2347,16 @@ wimlib_add_image_multisource(WIMStruct *wim, * images. No on-disk file is created until wimlib_write() is called. * * @param ctype - * The type of compression to be used in the new WIM file. Must be - * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, or - * ::WIMLIB_COMPRESSION_TYPE_XPRESS. + * The type of compression to be used in the new WIM file, as one of the + * ::wimlib_compression_type constants. * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the new WIM file is - * written to the memory location pointed to by this paramater. The + * written to the memory location pointed to by this parameter. The * ::WIMStruct must be freed using using wimlib_free() when finished with * it. * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * @p ctype was not ::WIMLIB_COMPRESSION_TYPE_NONE, - * ::WIMLIB_COMPRESSION_TYPE_LZX, or ::WIMLIB_COMPRESSION_TYPE_XPRESS. + * @p ctype was not a supported compression type. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. */ @@ -2011,6 +2404,18 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); extern int wimlib_delete_image(WIMStruct *wim, int image); +/** + * @ingroup G_modifying_wims + * + * Delete the @p path from the specified @p image of the @p wim. + * + * This just builds an appropriate ::wimlib_delete_command and passes it to + * wimlib_update_image(). + */ +extern int +wimlib_delete_path(WIMStruct *wim, int image, + const wimlib_tchar *path, int delete_flags); + /** * @ingroup G_modifying_wims * @@ -2018,13 +2423,9 @@ wimlib_delete_image(WIMStruct *wim, int image); * * The destination image is made to share the same dentry tree and security data * structure as the source image. This places some restrictions on additional - * functions that may be called. wimlib_mount_image() may not be called on - * either the source image or the destination image without an intervening call - * to a function that un-shares the images, such as wimlib_free() on @p - * dest_wim, or wimlib_delete_image() on either the source or destination image. - * Furthermore, you may not call wimlib_free() on @p src_wim before calling - * wimlib_write() or wimlib_overwrite() on @p dest_wim because @p dest_wim will - * have references back to @p src_wim. + * functions that may be called. For example, you may not call wimlib_free() on + * @p src_wim before calling wimlib_write() or wimlib_overwrite() on @p dest_wim + * because @p dest_wim will have references back to @p src_wim. * * If this function fails, all changes to @p dest_wim are rolled back. * @@ -2058,10 +2459,6 @@ wimlib_delete_image(WIMStruct *wim, int image); * parameter is overridden by ::WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS. * @param export_flags * Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG. - * @param progress_func - * Currently ignored, but reserved for a function that will be called with - * information about the operation. Use NULL if no additional information - * is desired. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION @@ -2103,82 +2500,14 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, WIMStruct *dest_wim, const wimlib_tchar *dest_name, const wimlib_tchar *dest_description, - int export_flags, - wimlib_progress_func_t progress_func); + int export_flags); /** * @ingroup G_extracting_wims * - * Extract zero or more files or directory trees from a WIM image. - * - * This generalizes the single-image extraction functionality of - * wimlib_extract_image() to allow extracting only the specified subsets of the + * Extracts an image, or all images, from a WIM to a directory or NTFS volume * image. * - * @param wim - * The WIM from which to extract the files, 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 1-based number of the image in @p wim from which the files or - * directory trees are to be extracted. It cannot be ::WIMLIB_ALL_IMAGES. - * - * @param cmds - * An array of ::wimlib_extract_command structures that specifies the - * extractions to perform. - * - * @param num_cmds - * Number of commands in the @p cmds array. - * - * @param default_extract_flags - * Default extraction flags; the behavior shall be as if these flags had - * been specified in the ::wimlib_extract_command.extract_flags member in - * each extraction command, in combination with any flags already present. - * - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. - * - * @return 0 on success; nonzero on error. The possible error codes include - * most of those documented as returned by wimlib_extract_image() as well as the - * following additional error codes: - * - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image was ::WIMLIB_ALL_IMAGES (or was not otherwise a valid image in - * the WIM file). - * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST - * The ::wimlib_extract_command.wim_source_path member in one of the - * extract commands did not exist in the WIM. - * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE - * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified for an extraction command - * in which ::wimlib_extract_command.wim_source_path existed but was not a - * regular file or directory. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK was - * specified for some commands but not all; or - * ::wimlib_extract_command.fs_dest_path was @c NULL or the empty string - * for one or more commands; or ::WIMLIB_EXTRACT_FLAG_RPFIX was specified - * for a command in which ::wimlib_extract_command.wim_source_path did not - * specify the root directory of the WIM image. - */ -extern int -wimlib_extract_files(WIMStruct *wim, - int image, - const struct wimlib_extract_command *cmds, - size_t num_cmds, - int default_extract_flags, - wimlib_progress_func_t progress_func); - -/** - * @ingroup G_extracting_wims - * - * Extracts an image, or all images, from a WIM to a directory or directly to a - * NTFS volume image. - * * 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 @@ -2186,12 +2515,6 @@ wimlib_extract_files(WIMStruct *wim, * special "NTFS volume extraction mode" entered by providing * ::WIMLIB_EXTRACT_FLAG_NTFS. * - * All extracted data is SHA1-summed, and ::WIMLIB_ERR_INVALID_RESOURCE_HASH is - * returned if any resulting SHA1 message digests do not match the values - * provided in the WIM file. Therefore, if this function is successful, you can - * be fairly sure that any compressed data in the WIM was uncompressed - * correctly. - * * @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 @@ -2200,51 +2523,50 @@ wimlib_extract_files(WIMStruct *wim, * referenced using wimlib_reference_resources() or * wimlib_reference_resource_files(). * @param image - * The image to extract. Can be the number of an image, 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 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. * @param target - * Directory to extract the WIM image(s) to (created if it does not already - * exist); or, with ::WIMLIB_EXTRACT_FLAG_NTFS in @p extract_flags, the - * path to the unmounted NTFS volume to extract the image to. + * 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. * @param extract_flags - * Bitwise OR of the flags prefixed with WIMLIB_EXTRACT_FLAG. - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress a resource to be extracted. + * Failed to decompress data contained in the WIM. + * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE + * The metadata for one of the images to extract was invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM - * Both ::WIMLIB_EXTRACT_FLAG_HARDLINK and ::WIMLIB_EXTRACT_FLAG_SYMLINK - * were specified in @p extract_flags; or both - * ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS and ::WIMLIB_EXTRACT_FLAG_NO_ACLS were - * specified in @p extract_flags; or both ::WIMLIB_EXTRACT_FLAG_RPFIX and - * ::WIMLIB_EXTRACT_FLAG_NORPFIX were specified in @p extract_flags; or - * ::WIMLIB_EXTRACT_FLAG_RESUME was specified in @p extract_flags; or if - * ::WIMLIB_EXTRACT_FLAG_NTFS was specified in @p extract_flags and - * @p image was ::WIMLIB_ALL_IMAGES. + * 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. * @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 file. + * The SHA1 message digest of an extracted stream did not match the SHA1 + * message digest given in the WIM. * @retval ::WIMLIB_ERR_LINK - * Failed to create a symbolic link or a hard link. + * Failed to create a symbolic link or a hard link. + * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND + * The metadata resource for one of the images to extract was not found. + * This can happen if @p wim represents a non-first part of a split WIM. * @retval ::WIMLIB_ERR_MKDIR - * Failed create a directory. + * Failed create a directory. * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. + * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_OPEN - * Could not create a file, or failed to open an already-extracted file. + * Could not create a file, or failed to open an already-extracted file. * @retval ::WIMLIB_ERR_READ - * Failed to read data from the WIM file associated with @p wim. + * Failed to read data from the WIM. * @retval ::WIMLIB_ERR_READLINK * Failed to determine the target of a symbolic link in the WIM. * @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED * Failed to fix the target of an absolute symbolic link (e.g. if the - * target would have exceeded the maximum allowed length). (Only if - * reparse data was supported by the extraction mode and - * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS was specified in @p extract_flags.) + * target would have exceeded the maximum allowed length). (Only if + * reparse data was supported by the extraction mode and + * ::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 @@ -2265,8 +2587,7 @@ wimlib_extract_files(WIMStruct *wim, * Failed to set timestamps on a file (only if * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS was specified in @p extract_flags). * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Unexpected end-of-file occurred when reading data from the WIM file - * associated with @p wim. + * Unexpected end-of-file occurred when reading data from the WIM. * @retval ::WIMLIB_ERR_UNSUPPORTED * A requested extraction flag, or the data or metadata that must be * extracted to support it, is unsupported in the build and configuration @@ -2274,37 +2595,34 @@ wimlib_extract_files(WIMStruct *wim, * volume. Flags affected by this include ::WIMLIB_EXTRACT_FLAG_NTFS, * ::WIMLIB_EXTRACT_FLAG_UNIX_DATA, ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS, * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES, - * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS, - * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS, ::WIMLIB_EXTRACT_FLAG_SYMLINK, - * and ::WIMLIB_EXTRACT_FLAG_HARDLINK. For example, if + * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS, and + * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS. For example, if * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES is specified in @p - * extract_flags, - * ::WIMLIB_ERR_UNSUPPORTED will be returned if the WIM image contains one - * or more files with short names, but extracting short names is not - * supported --- on Windows, this occurs if the target volume does not - * support short names, while on non-Windows, this occurs if + * extract_flags, ::WIMLIB_ERR_UNSUPPORTED will be returned if the WIM + * image contains one or more files with short names, but extracting short + * names is not supported --- on Windows, this occurs if the target volume + * does not support short names, while on non-Windows, this occurs if * ::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. * @retval ::WIMLIB_ERR_WRITE * Failed to write data to a file being extracted. * - * 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 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 + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */ extern int wimlib_extract_image(WIMStruct *wim, int image, - const wimlib_tchar *target, - int extract_flags, - wimlib_progress_func_t progress_func); + const wimlib_tchar *target, int extract_flags); /** * @ingroup G_extracting_wims * - * Since wimlib v1.5.0: Extract one or more images from a pipe on which a - * pipable WIM is being sent. + * Since wimlib v1.5.0: 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. @@ -2328,18 +2646,11 @@ wimlib_extract_image(WIMStruct *wim, int image, * @param target * Same as the corresponding parameter to wimlib_extract_image(). * @param extract_flags - * Same as the corresponding parameter to wimlib_extract_image(), except - * for the following exceptions: ::WIMLIB_EXTRACT_FLAG_SEQUENTIAL is - * always implied, since data is always read from @p pipe_fd sequentially - * in this mode; also, ::WIMLIB_EXTRACT_FLAG_TO_STDOUT is invalid and will - * result in ::WIMLIB_ERR_INVALID_PARAM being returned. - * @param progress_func - * Same as the corresponding parameter to wimlib_extract_image(), except - * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN messages will also be - * received. + * 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() as well as the following: + * 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. @@ -2349,33 +2660,122 @@ wimlib_extract_image(WIMStruct *wim, int image, extern int wimlib_extract_image_from_pipe(int pipe_fd, const wimlib_tchar *image_num_or_name, - const wimlib_tchar *target, int extract_flags, - wimlib_progress_func_t progress_func); + const wimlib_tchar *target, int extract_flags); + +/* + * @ingroup G_extracting_wims + * + * Same as wimlib_extract_image_from_pipe(), but allows specifying a progress + * function. The progress function will be used while extracting the WIM image + * and will receive the normal extraction progress messages, such as + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, in addition to + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. + */ +extern int +wimlib_extract_image_from_pipe_with_progress(int pipe_fd, + const wimlib_tchar *image_num_or_name, + const wimlib_tchar *target, + int extract_flags, + wimlib_progress_func_t progfunc, + void *progctx); /** - * Similar to wimlib_extract_paths(), but the paths to extract from the WIM - * image specified in the UTF-8 text file @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. + * @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 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. + * + * 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 (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT, + * ::WIMLIB_ERR_READ). */ extern int wimlib_extract_pathlist(WIMStruct *wim, int image, const wimlib_tchar *target, const wimlib_tchar *path_list_file, - int extract_flags, - wimlib_progress_func_t progress_func); + int extract_flags); /** - * Similar to wimlib_extract_files(), but the files or directories to extract - * from the WIM image are specified as an array of paths. Each path will be - * extracted to a corresponding location in @p target based on its location in - * the WIM image. - * - * With ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified in @p extract_flags, this - * function additionally allows paths to be globs using the wildcard characters - * '*' and '?'. + * @ingroup G_extracting_wims + * + * Since wimlib v1.6.0: 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". + * + * Symbolic links will not be dereferenced when paths in the WIM image are + * interpreted. + * + * @param wim + * WIM from which to extract the paths, 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 + * 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 + * 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(). + *
+ * By default, the characters @c * and @c ? are interpreted literally. + * This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p + * extract_flags. + *
+ * By default, if any paths to extract do not exist, the error code + * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is returned. This behavior changes if + * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified in @p extract_flags. + * @param num_paths + * Number of paths specified in @p paths. + * @param target + * Directory to which to extract the paths; or with + * ::WIMLIB_EXTRACT_FLAG_NTFS specified in @p extract_flags, the path to an + * unmounted NTFS volume to which to extract the paths. Unlike the @p + * paths being extracted, the @p target must be native path. On UNIX-like + * systems it may not contain backslashes, for example. + * @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: + * + * @retval ::WIMLIB_ERR_INVALID_IMAGE + * @p image was ::WIMLIB_ALL_IMAGES or was otherwise not a valid single + * image in the WIM. + * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST + * One of the paths to extract did not exist in the WIM image. This error + * code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not + * specified in @p extract_flags, or if both + * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS and ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB + * were specified in @p extract_flags. + * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE + * ::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. */ extern int wimlib_extract_paths(WIMStruct *wim, @@ -2383,8 +2783,7 @@ wimlib_extract_paths(WIMStruct *wim, const wimlib_tchar *target, const wimlib_tchar * const *paths, size_t num_paths, - int extract_flags, - wimlib_progress_func_t progress_func); + int extract_flags); /** * @ingroup G_wim_information @@ -2395,8 +2794,8 @@ wimlib_extract_paths(WIMStruct *wim, * See wimlib_get_xml_data() to read the XML data into memory instead. * * @param wim - * Pointer to the ::WIMStruct for a WIM file, which does not necessarily - * have to be standalone (e.g. it could be part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param fp * @c stdout, or a FILE* opened for writing, to extract the data to. * @@ -2404,9 +2803,11 @@ wimlib_extract_paths(WIMStruct *wim, * @retval ::WIMLIB_ERR_INVALID_PARAM * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(). * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_READ + * Error reading the XML data from the WIM file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Failed to read the XML data from the WIM. + * Error reading the XML data from the WIM file. * @retval ::WIMLIB_ERR_WRITE * Failed to completely write the XML data to @p fp. */ @@ -2420,7 +2821,7 @@ wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); * with it. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct to free. * * @return This function has no return value. */ @@ -2433,12 +2834,11 @@ wimlib_free(WIMStruct *wim); * Converts a ::wimlib_compression_type value into a string. * * @param ctype - * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, - * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or another value. + * The ::wimlib_compression_type value to convert. * * @return - * A statically allocated string: "None", "LZX", "XPRESS", or "Invalid", - * respectively. + * A statically allocated string naming the compression algorithm, + * such as "None", "LZX", "XPRESS", or "Invalid". */ extern const wimlib_tchar * wimlib_get_compression_type_string(int ctype); @@ -2464,8 +2864,8 @@ wimlib_get_error_string(enum wimlib_error_code code); * Returns the description of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param image * The number of the image, numbered starting at 1. * @@ -2485,8 +2885,8 @@ wimlib_get_image_description(const WIMStruct *wim, int image); * Returns the name of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param image * The number of the image, numbered starting at 1. * @@ -2500,6 +2900,19 @@ wimlib_get_image_description(const WIMStruct *wim, int image); extern const wimlib_tchar * 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 + * 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 + * corresponding header file. + */ +extern uint32_t +wimlib_get_version(void); /** * @ingroup G_wim_information @@ -2507,8 +2920,8 @@ wimlib_get_image_name(const WIMStruct *wim, int image); * 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. @@ -2528,8 +2941,8 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); * instead. * * @param wim - * Pointer to the ::WIMStruct for a WIM file, which does not necessarily - * have to be standalone (e.g. it could be part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param buf_ret * On success, a pointer to an allocated buffer containing the raw UTF16-LE * XML data is written to this location. @@ -2554,7 +2967,8 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); * 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 - * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. + * ::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. @@ -2585,7 +2999,8 @@ wimlib_global_cleanup(void); * Determines if an image name is already used by some image in the WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param name * The name to check. * @@ -2668,8 +3083,8 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, * explicitly referenced. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * * @param flags * Reserved; set to 0. @@ -2708,9 +3123,6 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * be used to write the joined WIM. * @param output_path * The path to write the joined WIM file to. - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. * * @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 @@ -2733,89 +3145,101 @@ wimlib_join(const wimlib_tchar * const *swms, unsigned num_swms, const wimlib_tchar *output_path, int swm_open_flags, - int wim_write_flags, - wimlib_progress_func_t progress_func); + int wim_write_flags); + +/** + * @ingroup G_nonstandalone_wims + * + * Same as wimlib_join(), but allows specifying a progress function. The + * progress function will receive the write progress messages, such as + * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, while writing the joined WIM. In + * addition, if ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p + * swm_open_flags, the progress function will receive a series of + * ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages when each of the split WIM + * parts is opened. + */ +extern int +wimlib_join_with_progress(const wimlib_tchar * const *swms, + unsigned num_swms, + const wimlib_tchar *output_path, + int swm_open_flags, + int wim_write_flags, + wimlib_progress_func_t progfunc, + void *progctx); /** * @ingroup G_mounting_wim_images * - * Mounts an image in a WIM file on a directory read-only or read-write. - * - * As this is implemented using FUSE (Filesystme in UserSpacE), this is not - * supported if wimlib was configured with @c --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 occur occurs. If the - * mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), modifications - * to the WIM are staged in a temporary directory. - * - * 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. - * - * wimlib_mount_image() cannot be used on an image that was exported with - * wimlib_export_image() while the dentry trees for both images are still in - * memory. In addition, wimlib_mount_image() may not be used to mount an image - * that already has modifications pending (e.g. an image added with - * wimlib_add_image()). + * Mounts 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. * @param image - * The number of the image to mount, indexed starting from it. It must be - * an existing, single image. + * The 1-based index of the image to mount. * @param dir - * The path to an existing empty directory to mount the image on. + * The path to an existing empty directory on which to mount the WIM image. * @param mount_flags - * Bitwise OR of the flags prefixed with WIMLIB_MOUNT_FLAG. + * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use + * ::WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a + * read-only mount. * @param staging_dir - * If non-NULL, the name of a directory in which the staging directory 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. + * If non-NULL, the name of a directory in which a temporary directory for + * 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. * - * @return 0 on success; nonzero on error. + * @return 0 on success; nonzero on error. The possible error codes include: * * @retval ::WIMLIB_ERR_ALREADY_LOCKED - * A read-write mount was requested, but an 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. + * An image from the WIM file is already mounted read-write, or another + * process is currently appending data to the WIM file. * @retval ::WIMLIB_ERR_FUSE - * A non-zero status was returned by @c fuse_main(). + * 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. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p image is shared among multiple ::WIMStruct's as a result of a call to - * wimlib_export_image(), or @p image has been added with - * wimlib_add_image(). + * @p wim was @c NULL; or @p dir was NULL or the 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 * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the * staging directory could not be created. - * @retval ::WIMLIB_ERR_NOTDIR - * Could not determine the current working directory. - * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND - * One of the dentries in the image referenced a stream not present in the - * WIM's lookup table (or in any of the lookup tables of the split WIM - * parts). * @retval ::WIMLIB_ERR_WIM_IS_READONLY - * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but @p - * wim is considered read-only because of any of the reasons mentioned in - * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. + * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but 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. * @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 with @c - * --without-fuse. + * because the platform is UNIX-like and wimlib was compiled using + * --without-fuse. * * 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. + * + * 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; + * ::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. + * + * To unmount the image, call wimlib_unmount_image(). This may be done in a + * different process. */ extern int wimlib_mount_image(WIMStruct *wim, @@ -2835,75 +3259,86 @@ wimlib_mount_image(WIMStruct *wim, * @param open_flags * Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG. * - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. Currently, the only messages sent - * will be ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY, and only if - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags. - * * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the opened WIM file * is written to the memory location pointed to by this parameter. The - * ::WIMStruct can be freed using using wimlib_free() when finished with + * ::WIMStruct must be freed using using wimlib_free() when finished with * it. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_IMAGE_COUNT - * The WIM is not the non-first part of a split WIM, and the number of - * metadata resources found in the WIM did not match the image count given - * in the WIM header, or the number of <IMAGE> elements in the XML - * data for the WIM did not match the image count given in the WIM header. + * The number of metadata resources found in the WIM did not match the + * image count specified in the WIM header, or the number of <IMAGE> + * elements in the XML data of the WIM did not match the image count + * specified in the WIM header. * @retval ::WIMLIB_ERR_INTEGRITY - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p - * wim_file contains an integrity table, but the SHA1 message digest for a - * chunk of the WIM does not match the corresponding message digest given - * in the integrity table. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and + * the WIM contained an integrity table, but the SHA1 message digest for a + * chunk of the WIM did not match the corresponding value in the integrity + * table. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * Resources in @p wim_file are compressed, but the chunk size was invalid - * for the WIM's compression format. + * 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 indicating LZX or XPRESS compression 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 contained duplicate entries that are not - * for metadata resources, or it contained an entry with a SHA1 message - * digest of all 0's. + * The lookup table of the WIM was invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p wim_ret was @c NULL. * @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 file for reading. * @retval ::WIMLIB_ERR_READ - * Failed to read data from @p wim_file. + * Failed to read data from the 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 file. * @retval ::WIMLIB_ERR_UNKNOWN_VERSION - * A number other than 0x10d00 is written in the version field of the WIM - * header of @p wim_file. (May be a pre-Vista WIM.) + * 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.) * @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, int open_flags, - WIMStruct **wim_ret, - wimlib_progress_func_t progress_func); + WIMStruct **wim_ret); + +/** + * @ingroup G_creating_and_opening_wims + * + * 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, as if by an automatic call to + * wimlib_register_progress_function(). In addition, if + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, the + * progress function will receive ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY + * messages while checking the WIM's integrity. + */ +extern int +wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, + int open_flags, + WIMStruct **wim_ret, + wimlib_progress_func_t progfunc, + void *progctx); /** * @ingroup G_writing_and_overwriting_wims @@ -2916,10 +3351,8 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * rebuild. In this mode, the new WIM is written to a temporary file and then * renamed to the original file after it is has been completely written. The * temporary file is made in the same directory as the original WIM file. A - * full rebuild may take a while, but can be used even if images have been - * modified or deleted, will produce a WIM with no holes, and has little chance - * of unintentional data loss because the temporary WIM is fsync()ed before - * being renamed to the original WIM. + * full rebuild may take a while, but it will save space by producing a WIM with + * no "holes". * * The second way to overwrite a WIM is by appending to the end of it and * overwriting the header. This can be much faster than a full rebuild, but the @@ -2938,13 +3371,6 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * ::WIMLIB_WRITE_FLAG_SOFT_DELETE to request the in-place overwrite even if * images have been deleted from the WIM. * - * In the temporary-file overwrite mode, no changes are made to the WIM on - * failure, and the temporary file is deleted if possible. Abnormal termination - * of the program will result in the temporary file being orphaned. In the - * direct append mode, the WIM is truncated to the original length on failure; - * and while abnormal termination of the program will result in extra data - * appended to the original WIM, it should still be a valid WIM. - * * If this function completes successfully, no more functions should be called * on @p wim other than wimlib_free(). You must use wimlib_open_wim() to read * the WIM file anew. @@ -2957,9 +3383,6 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. * @param num_threads * Number of threads to use for compression (see wimlib_write()). - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. * * @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: @@ -2970,8 +3393,8 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * because another thread or process has mounted an image from the WIM * read-write or is currently modifying the WIM in-place. * @retval ::WIMLIB_ERR_NO_FILENAME - * @p wim corresponds to a WIM created with wimlib_create_new_wim() rather - * than a WIM read with wimlib_open_wim(). + * @p wim corresponds to a ::WIMStruct created with wimlib_create_new_wim() + * rather than a WIM read with wimlib_open_wim(). * @retval ::WIMLIB_ERR_RENAME * The temporary file that the WIM was written to could not be renamed to * the original filename of @p wim. @@ -2979,10 +3402,14 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * 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 + * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END. */ extern int -wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads, - wimlib_progress_func_t progress_func); +wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads); /** * @ingroup G_wim_information @@ -2990,7 +3417,8 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads, * Prints information about one image, or all images, contained in a WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param image * The image about which to print information. Can be the number of an * image, or ::WIMLIB_ALL_IMAGES to print information about all images in the @@ -3012,15 +3440,6 @@ wimlib_print_available_images(const WIMStruct *wim, int image); extern void wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; -/** - * @ingroup G_wim_information - * - * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the - * information in a way that can be accessed programatically. - */ -extern int -wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; - /** * @ingroup G_nonstandalone_wims * @@ -3050,8 +3469,6 @@ wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; * @param open_flags * Additional open flags, such as ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY, to * pass to internal calls to wimlib_open_wim() on the reference files. - * @param progress_func - * Passed to internal calls to wimlib_open_wim() on the reference files. * * @return 0 on success; nonzero on error. * @@ -3072,8 +3489,7 @@ wimlib_reference_resource_files(WIMStruct *wim, const wimlib_tchar * const *resource_wimfiles_or_globs, unsigned count, int ref_flags, - int open_flags, - wimlib_progress_func_t progress_func); + int open_flags); /** * @ingroup G_nonstandalone_wims @@ -3153,10 +3569,6 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, * of the directory tree being captured. * @param flags * Reserved; must be 0. - * @param progress_func - * Currently ignored, but reserved for a function that will be called with - * information about the operation. Use NULL if no additional information - * is desired. * * @return 0 on success; nonzero on error. * @@ -3182,7 +3594,40 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, extern int wimlib_reference_template_image(WIMStruct *wim, int new_image, WIMStruct *template_wim, int template_image, - int flags, wimlib_progress_func_t progress_func); + int flags); + +/** + * @ingroup G_general + * + * Registers a progress function with a ::WIMStruct. + * + * @param wim + * The ::WIMStruct for which to register the progress function. + * @param progfunc + * Pointer to the progress function to register. If the WIM already has a + * progress function registered, it will be replaced with this one. If @p + * NULL, the current progress function (if any) will be unregistered. + * @param progctx + * The value which will be passed as the third argument to calls to @p + * progfunc. + */ +extern void +wimlib_register_progress_function(WIMStruct *wim, + wimlib_progress_func_t progfunc, + void *progctx); + +/** + * @ingroup G_modifying_wims + * + * Rename the @p source_path to the @p dest_path in the specified @p image of + * the @p wim. + * + * This just builds an appropriate ::wimlib_rename_command and passes it to + * wimlib_update_image(). + */ +extern int +wimlib_rename_path(WIMStruct *wim, int image, + const wimlib_tchar *source_path, const wimlib_tchar *dest_path); /** * @ingroup G_wim_information @@ -3249,30 +3694,25 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * Set the compression chunk size of a WIM to use in subsequent calls to * wimlib_write() or wimlib_overwrite(). * - * A compression chunk size will result in a greater compression ratio, but the - * speed of random access to the WIM will be reduced, and the effect of an - * increased compression chunk size is limited by the size of each file being - * compressed. - * - * WARNING: Microsoft's software is seemingly incompatible with LZX chunk - * sizes other than 32768. Chunk sizes other than 32768 (for any format) are - * also incompatible with wimlib v1.5.3 and earlier. + * 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. * * @param wim * ::WIMStruct for a WIM. - * @param out_chunk_size + * @param chunk_size * The chunk size (in bytes) to set. The valid chunk sizes are dependent - * on the compression format. The XPRESS compression format supports chunk - * sizes that are powers of 2 with exponents between 15 and 26 inclusively, - * whereas the LZX compression format supports chunk sizes that are powers - * of 2 with exponents between 15 and 21 inclusively. As a special case, - * if @p out_chunk_size is specified as 0, the chunk size is set to the + * on the compression format. See the documentation for each + * ::wimlib_compression_type constant for more information. As a special + * case, if @p chunk_size is specified as 0, the chunk size is set to the * default for the currently selected output compression type. * * @return 0 on success; nonzero on error. * * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * @p ctype is not a supported 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); @@ -3281,7 +3721,7 @@ wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); * @ingroup G_writing_and_overwriting_wims * * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing - * packed streams. + * packed streams (solid blocks). */ extern int wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size); @@ -3312,7 +3752,7 @@ wimlib_set_output_compression_type(WIMStruct *wim, int ctype); * @ingroup G_writing_and_overwriting_wims * * Similar to wimlib_set_output_compression_type(), but set the compression type - * for writing packed streams. + * for writing packed streams (solid blocks). */ extern int wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype); @@ -3414,7 +3854,7 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * library. * * Please note that some external functions, such as those in @c libntfs-3g, may - * use the standard memory allocation functions. + * use the standard memory allocation functions regardless of this setting. * * @param malloc_func * A function equivalent to @c malloc() that wimlib will use to allocate @@ -3483,11 +3923,6 @@ wimlib_set_print_errors(bool show_messages); * Bitwise OR of relevant flags prefixed with @c WIMLIB_WRITE_FLAG. These * flags will be used to write each split WIM part. Specify 0 here to get * the default behavior. - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation - * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and - * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). * * @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 @@ -3496,86 +3931,67 @@ wimlib_set_print_errors(bool show_messages); * @retval ::WIMLIB_ERR_INVALID_PARAM * @p swm_name was not a nonempty string, or @p part_size was 0. * - * Note: the WIM's uncompressed and compressed resources are not checksummed - * when they are copied from the joined WIM to the split WIM parts, nor are - * compressed resources re-compressed (unless explicitly requested with - * ::WIMLIB_WRITE_FLAG_RECOMPRESS). + * If a progress function is registered with @p wim, for each split WIM part + * that is written it will receive the messages + * ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and + * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. */ extern int wimlib_split(WIMStruct *wim, const wimlib_tchar *swm_name, uint64_t part_size, - int write_flags, - wimlib_progress_func_t progress_func); + int write_flags); /** * @ingroup G_mounting_wim_images * * Unmounts a WIM image that was mounted using wimlib_mount_image(). * - * The image to unmount is specified by the path to the mountpoint, not the - * original ::WIMStruct passed to wimlib_mount_image(), which should not be - * touched and also may have been allocated in a different process. - * - * To unmount the image, the process calling this function communicates with the - * process that is managing the mounted WIM image. This function blocks until it - * is known whether the unmount succeeded or failed. In the case of a - * read-write mounted WIM, the unmount is not considered to have succeeded until - * all changes have been saved to the underlying WIM file. + * 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 + * WIM image to be committed. * * @param dir - * The directory that the WIM image was mounted on. + * The directory the WIM image was mounted on. * @param unmount_flags - * Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY, - * ::WIMLIB_UNMOUNT_FLAG_COMMIT, ::WIMLIB_UNMOUNT_FLAG_REBUILD, and/or - * ::WIMLIB_UNMOUNT_FLAG_RECOMPRESS. None of these flags affect read-only - * mounts. - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. Currently, only - * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS will be sent. + * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG. * - * @return 0 on success; nonzero on error. + * @return 0 on success; nonzero on error. The possible error codes include: * - * @retval ::WIMLIB_ERR_DELETE_STAGING_DIR - * The filesystem daemon was unable to remove the staging directory and the - * temporary files that it contains. - * @retval ::WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED - * The filesystem daemon appears to have terminated before sending an exit - * status. - * @retval ::WIMLIB_ERR_FORK - * Could not @c fork() the process. - * @retval ::WIMLIB_ERR_FUSERMOUNT - * The @b fusermount program could not be executed or exited with a failure - * status. + * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT + * There is no WIM image mounted on the specified directory. + * @retval ::WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY + * The read-write mounted WIM image cannot be committed because there are + * file descriptors open to it, and ::WIMLIB_UNMOUNT_FLAG_FORCE was not + * specified. * @retval ::WIMLIB_ERR_MQUEUE - * Could not open a POSIX message queue to communicate with the filesystem - * daemon servicing the mounted filesystem, could not send a message - * through the queue, or could not receive a message through the queue. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_OPEN - * The filesystem daemon could not open a temporary file for writing the - * new WIM. - * @retval ::WIMLIB_ERR_READ - * A read error occurred when the filesystem daemon tried to a file from - * the staging directory - * @retval ::WIMLIB_ERR_RENAME - * The filesystem daemon failed to rename the newly written WIM file to the - * original WIM file. + * Could not create a POSIX message queue. + * @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 with @c + * because the platform is UNIX-like and wimlib was compiled using @c * --without-fuse. - * @retval ::WIMLIB_ERR_WRITE - * A write error occurred when the filesystem daemon was writing to the new - * WIM file, or the filesystem daemon was unable to flush changes that had - * been made to files in the staging directory. + * + * 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 + * this function if you want changes to be committed. + */ +extern int +wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags); + +/** + * @ingroup G_mounting_wim_images + * + * Same as wimlib_unmount_image(), but allows specifying a progress function. + * If changes are committed from a read-write mount, the progress function will + * receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages. */ extern int -wimlib_unmount_image(const wimlib_tchar *dir, - int unmount_flags, - wimlib_progress_func_t progress_func); +wimlib_unmount_image_with_progress(const wimlib_tchar *dir, + int unmount_flags, + wimlib_progress_func_t progfunc, + void *progctx); /** * @ingroup G_modifying_wims @@ -3594,13 +4010,10 @@ wimlib_unmount_image(const wimlib_tchar *dir, * Number of commands in @p cmds. * @param update_flags * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0. - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. * - * @return 0 on success; nonzero on error. On failure, some but not all of the - * update commands may have been executed. No individual update command will - * have been partially executed. Possible error codes include: + * @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: * * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG * The capture configuration structure specified for an add command was @@ -3614,7 +4027,7 @@ wimlib_unmount_image(const wimlib_tchar *dir, * 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 a NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and + * 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 * specified in the @p add_flags for an add command in which @p @@ -3687,8 +4100,7 @@ wimlib_update_image(WIMStruct *wim, int image, const struct wimlib_update_command *cmds, size_t num_cmds, - int update_flags, - wimlib_progress_func_t progress_func); + int update_flags); /** * @ingroup G_writing_and_overwriting_wims @@ -3724,12 +4136,6 @@ wimlib_update_image(WIMStruct *wim, * 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). - * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. The possible messages are - * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, - * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, and - * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. * * @return 0 on success; nonzero on error. * @@ -3768,14 +4174,18 @@ wimlib_update_image(WIMStruct *wim, * ::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. + * + * If a progress function is registered with @p wim, it will receive the + * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END. */ extern int wimlib_write(WIMStruct *wim, const wimlib_tchar *path, int image, int write_flags, - unsigned num_threads, - wimlib_progress_func_t progress_func); + unsigned num_threads); /** * @ingroup G_writing_and_overwriting_wims @@ -3802,8 +4212,7 @@ wimlib_write_to_fd(WIMStruct *wim, int fd, int image, int write_flags, - unsigned num_threads, - wimlib_progress_func_t progress_func); + unsigned num_threads); /** * @defgroup G_compression Compression and decompression functions @@ -3817,10 +4226,7 @@ wimlib_write_to_fd(WIMStruct *wim, * decompressors currently support sliding windows, and there also exist * slightly different variants of these formats that are not supported * unmodified. - */ - -/** - * @ingroup G_compression + * * @{ */ @@ -3846,11 +4252,11 @@ struct wimlib_lzx_compressor_params { struct wimlib_compressor_params_header hdr; /** Relatively fast LZX compression algorithm with a decent compression - * ratio; the suggested default. */ + * ratio. */ #define WIMLIB_LZX_ALGORITHM_FAST 0 /** Slower LZX compression algorithm that provides a better compression - * ratio. */ + * ratio. This is the default. */ #define WIMLIB_LZX_ALGORITHM_SLOW 1 /** Algorithm to use to perform the compression: either @@ -3869,20 +4275,21 @@ struct wimlib_lzx_compressor_params { uint32_t fast_reserved1[10]; } fast; - /** Parameters for the slow algorithm. */ + /** 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. If set 0, the compressor can only output * matches of length 3 or greater. Suggested value: 1 */ uint32_t use_len2_matches : 1; uint32_t slow_reserved1 : 31; - /** Matches with length (in bytes) longer than this - * value are immediately taken without spending time on - * minimum-cost measurements. Suggested value: 32. */ - uint32_t num_fast_bytes; + /** 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 @@ -3899,11 +4306,10 @@ struct wimlib_lzx_compressor_params { * 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; + /* Note: max_matches_per_pos has been removed and no + * longer has any effect. */ - uint32_t slow_reserved2[2]; + uint32_t slow_reserved2[3]; /** Assumed cost of a main symbol with zero frequency. * Must be at least 1 and no more than 16. Suggested @@ -3925,6 +4331,43 @@ struct wimlib_lzx_compressor_params { } alg_params; }; +/** LZMS compression parameters that can optionally be passed to + * wimlib_create_compressor() with the compression type + * ::WIMLIB_COMPRESSION_TYPE_LZMS. */ +struct wimlib_lzms_compressor_params { + /** hdr.size Must be set to the size of this structure, in bytes. */ + struct wimlib_compressor_params_header hdr; + + /** Minimum match length to output. This must be at least 2. Suggested + * value: 2 */ + uint32_t min_match_length; + + /** Maximum match length to output. This must be at least @p + * min_match_length. Suggested value: @p UINT32_MAX. */ + uint32_t max_match_length; + + /** Matches with length (in bytes) greater than or equal to this value + * are immediately taken without spending time on minimum-cost + * measurements. The minimum of @p max_match_length and @p + * nice_match_length may not exceed 65536. Suggested value: 32. */ + uint32_t nice_match_length; + + /** Maximum depth to search for matches at each position. Suggested + * value: 50. */ + uint32_t max_search_depth; + + /* Note: max_matches_per_pos has been removed and no longer has any + * effect. */ + + uint32_t reserved1; + + /** Length of the array for the near-optimal LZ parsing algorithm. This + * must be at least 1. Suggested value: 1024. */ + uint32_t optim_array_length; + + uint64_t reserved2[4]; +}; + /** Opaque compressor handle. */ struct wimlib_compressor; @@ -3933,7 +4376,7 @@ struct wimlib_decompressor; /** * Set the default compression parameters for the specified compression type. - * This will affect both explicit and wimlib-internal calls to + * This will affect both explicit and library-internal calls to * wimlib_create_compressor(). * * @param ctype @@ -3946,6 +4389,8 @@ struct wimlib_decompressor; * * @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). @@ -3954,9 +4399,22 @@ extern int wimlib_set_default_compressor_params(enum wimlib_compression_type ctype, const struct wimlib_compressor_params_header *params); +/** + * 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. + */ +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); + /** * 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. @@ -3967,8 +4425,9 @@ wimlib_set_default_compressor_params(enum wimlib_compression_type ctype, * @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. + * may be specified here. For LZMS, a pointer to + * ::wimlib_lzms_compressor_params may be specified here. If left @c NULL, + * the default parameters are used. * @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 @@ -4024,7 +4483,7 @@ 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 + * This will affect both explicit and library-internal calls to * wimlib_create_decompressor(). * * @param ctype @@ -4047,7 +4506,8 @@ wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype, /** * Allocate a decompressor for the specified compression type using the - * specified parameters. + * specified 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 decompressor. @@ -4111,55 +4571,9 @@ extern void wimlib_free_decompressor(struct wimlib_decompressor *decompressor); -struct wimlib_lzx_params_old; -struct wimlib_lzx_context_old; - -/** Deprecated; do not use. */ -extern int -wimlib_lzx_set_default_params(const struct wimlib_lzx_params_old *params) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern int -wimlib_lzx_alloc_context(const struct wimlib_lzx_params_old *params, - struct wimlib_lzx_context_old **ctx_pp) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern void -wimlib_lzx_free_context(struct wimlib_lzx_context_old *ctx) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern unsigned -wimlib_lzx_compress2(const void *udata, unsigned ulen, void *cdata, - struct wimlib_lzx_context_old *ctx) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern unsigned -wimlib_lzx_compress(const void *udata, unsigned ulen, void *cdata) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern unsigned -wimlib_xpress_compress(const void *udata, unsigned ulen, void *cdata) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern int -wimlib_lzx_decompress(const void *cdata, unsigned clen, - void *udata, unsigned ulen) - _wimlib_deprecated; - -/** Deprecated; do not use. */ -extern int -wimlib_xpress_decompress(const void *cdata, unsigned clen, - void *udata, unsigned ulen) - _wimlib_deprecated; - -/** @} */ - +/** + * @} + */ #ifdef __cplusplus