X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=037f67d6327b1ec61ab49ccaa4acc321d26df466;hp=eb8a33ba27fe05f10b01afa5dc1baccf7874c00b;hb=5db11cb8825229c4bc3f61c37ac86e4d6561f61a;hpb=9db1bdc721081a2dead6a60cba77dfb9bdad5ceb diff --git a/include/wimlib.h b/include/wimlib.h index eb8a33ba..037f67d6 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -1,15 +1,16 @@ -/* - * wimlib.h - * - * External header for wimlib. +/** + * @file wimlib.h + * @brief External header for wimlib. * * This file contains extensive comments for generating documentation with * Doxygen. The built HTML documentation can be viewed at - * http://wimlib.sourceforge.net. + * http://wimlib.sourceforge.net. Make sure to see the Modules page to make more sense of the declarations + * in this header. */ /* - * Copyright (C) 2012, 2013 Eric Biggers + * Copyright (C) 2012, 2013, 2014 Eric Biggers * * This file is part of wimlib, a library for working with WIM files. * @@ -27,76 +28,118 @@ * along with wimlib; if not, see http://www.gnu.org/licenses/. */ -/** \mainpage +/** + * @mainpage * - * \section intro Introduction + * @section sec_intro Introduction * - * This is the documentation for the library interface of wimlib 1.5.0, a C + * This is the documentation for the library interface of wimlib 1.6.3, 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. * - * \section starting Getting Started + * @section sec_installing_and_compiling Installing and Compiling * * 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. To use - * wimlib in a program after installing it, include @c wimlib.h and link your - * program with @c -lwim. + * please see the README for more information about installing it. + * + * To use wimlib in your program after installing it, include wimlib.h and link + * your program with @c -lwim. + * + * As of wimlib 1.5.0, wimlib.h is also compatible with C++. + * + * 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_basic_wim_handling_concepts Basic WIM handling concepts + * + * wimlib wraps up a WIM file in an opaque ::WIMStruct structure. There are + * two ways to create such a structure: wimlib_open_wim(), which opens a WIM + * file and creates a ::WIMStruct representing it, and wimlib_create_new_wim(), + * which creates a new ::WIMStruct that initially contains no images and does + * not yet have a backing on-disk file. See @ref G_creating_and_opening_wims + * for more details. + * + * A WIM file, represented by a ::WIMStruct, contains zero or more images. + * Images can be extracted (or "applied") using wimlib_extract_image(), added + * (or "captured" or "appended") using wimlib_add_image(), deleted using + * wimlib_delete_image(), exported using wimlib_export_image(), and updated or + * modified using wimlib_update_image(). However, changes made to a WIM + * represented by a ::WIMStruct have no persistent effect until the WIM is + * actually written to an on-disk file. This can be done using wimlib_write(), + * but if the WIM was originally opened using wimlib_open_wim(), then + * wimlib_overwrite() can be used instead. See @ref G_extracting_wims, @ref + * G_modifying_wims, and @ref G_writing_and_overwriting_wims for more details. + * + * Note that with this ::WIMStruct abstraction, performing many tasks on WIM + * files is a multi-step process. For example, to add, or "append" an image to + * an existing stand-alone WIM file in a way similar to wimlib-imagex + * append, you must call the following functions: + * + * 1. wimlib_open_wim() + * 2. wimlib_add_image() + * 3. wimlib_overwrite() + * + * This design is very much on purpose as it makes the library more useful in + * general by allowing functions to be composed in different ways. For example, + * you can make multiple changes to a WIM and commit them all to the underlying + * file in only one overwrite operation, which is more efficient. + * + * @section sec_cleaning_up Cleaning up + * + * After you are done with any ::WIMStruct, you can call wimlib_free() to free + * all resources associated with it. Also, when you are completely done with + * using wimlib in your program, you can call wimlib_global_cleanup() to free + * any other resources allocated by the library. + * + * @section sec_error_handling Error Handling + * + * Most functions in wimlib return 0 on success and a positive error code on + * failure. Use wimlib_get_error_string() to get a string that describes an + * error code. wimlib also can print error messages to standard error itself + * when an error happens, and these may be more informative than the error code; + * to enable this, call wimlib_set_print_errors(). Please note that this is for + * convenience only, and some errors can occur without a message being printed. + * Currently, error messages and strings (as well as all documentation, for that + * matter) are only available in English. + * + * @section sec_encodings Locales and character encodings * - * wimlib wraps up a WIM file in an opaque ::WIMStruct structure. A ::WIMStruct - * may represent either a stand-alone WIM or one part of a split WIM. + * To support Windows as well as UNIX-like systems, wimlib's API typically takes + * and returns strings of ::wimlib_tchar, which are in a platform-dependent + * encoding. * - * All functions in wimlib's public API are prefixed with @c wimlib. Most - * return 0 on success and a positive error code on failure. Use - * wimlib_get_error_string() to get a string that describes an error code. - * wimlib also can print error messages itself when an error happens, and these - * may be more informative than the error code; to enable this, call - * wimlib_set_print_errors(). Please note that this is for convenience only, - * and some errors can occur without a message being printed. + * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t", + * and the encoding is UTF-16LE. * - * First before calling any other functions, you should call - * wimlib_global_init() to initialize the library. + * On UNIX-like systems, each ::wimlib_tchar is 1 byte and is simply a "char", + * and the encoding is the locale-dependent multibyte encoding. I recommend you + * set your locale to a UTF-8 capable locale to avoid any issues. Also, by + * default, wimlib on UNIX will assume the locale is UTF-8 capable unless you + * call wimlib_global_init() after having set your desired locale. * - * To open an existing WIM, use wimlib_open_wim(). + * @section sec_advanced Additional information and features * - * To create a new WIM that initially contains no images, use - * wimlib_create_new_wim(). * - * To add an image to a WIM file from a directory tree on your filesystem, call - * wimlib_add_image(). This can be done with a ::WIMStruct gotten from - * wimlib_open_wim() or from wimlib_create_new_wim(). On UNIX-like systems, - * wimlib_add_image() can also capture a WIM image directly from a block device - * containing a NTFS filesystem. + * @subsection subsec_mounting_wim_images Mounting WIM images * - * To extract an image from a WIM file, call wimlib_extract_image(). This can - * be done either to a directory, or, on UNIX-like systems, directly to a block - * device containing a NTFS filesystem. + * See @ref G_mounting_wim_images. * - * To extract individual files or directories from a WIM image, rather than a - * full image, call wimlib_extract_files(). + * @subsection subsec_progress_functions Progress Messages * - * To programatically make changes to a WIM image without mounting it, call - * wimlib_update_image(). + * See @ref G_progress. * - * On UNIX-like systems supporting FUSE (such as Linux), wimlib supports - * mounting WIM files either read-only or read-write. Mounting is done using - * wimlib_mount_image() and unmounting is done using wimlib_unmount_image(). - * Mounting can be done without root privileges because it is implemented using - * FUSE (Filesystem in Userspace). If wimlib is compiled with the - * --without-fuse flag, these functions will be available but will - * fail with ::WIMLIB_ERR_UNSUPPORTED. - * - * After creating or modifying a WIM file, you can write it to a file using - * wimlib_write(). Alternatively, if the WIM was originally read from a file - * (using wimlib_open_wim() rather than wimlib_create_new_wim()), you can use - * wimlib_overwrite() to overwrite the original file. Still alternatively, you - * can write a WIM directly to a file descriptor by calling wimlib_write_to_fd() - * instead. + * @subsection subsec_non_standalone_wims Non-standalone WIMs * - * wimlib supports a special "pipable" WIM format (which unfortunately is @b not - * compatible with Microsoft's software). To create a pipable WIM, call + * See @ref G_nonstandalone_wims. + * + * @subsection subsec_pipable_wims Pipable WIMs + * + * wimlib supports a special "pipable" WIM format which unfortunately is @b not + * compatible with Microsoft's software. To create a pipable WIM, call * wimlib_write(), wimlib_write_to_fd(), or wimlib_overwrite() with * ::WIMLIB_WRITE_FLAG_PIPABLE specified. Pipable WIMs are pipable in both * directions, so wimlib_write_to_fd() can be used to write a pipable WIM to a @@ -105,24 +148,14 @@ * s using a seekable file descriptor using the regular function calls (e.g. * wimlib_open_wim(), wimlib_extract_image()). * - * Please note: merely by calling wimlib_add_image() or many of the other - * functions in this library that operate on ::WIMStruct's, you are @b not - * modifying the WIM file on disk. Changes are not saved until you explicitly - * call wimlib_write() or wimlib_overwrite(). - * - * After you are done with the WIM file, use wimlib_free() to free all memory - * associated with a ::WIMStruct and close all files associated with it. - * - * When you are completely done with using wimlib in your program, you should - * call wimlib_global_cleanup(). + * See the documentation for the --pipable flag of wimlib-imagex + * capture for more information about pipable WIMs. * - * 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). + * @subsection subsec_thread_safety Thread Safety * - * wimlib is thread-safe as long as different ::WIMStruct's are used, except for - * the following exceptions: + * wimlib is thread-safe, with the following exceptions: + * - Different threads cannot operate on the same ::WIMStruct at the same time; + * they must use different ::WIMStruct's. * - You must call wimlib_global_init() in one thread before calling any other * functions. * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally. @@ -131,35 +164,166 @@ * does so for the first time. This includes changing the working directory * to the root directory. * - * \section encodings Locales and character encodings - * - * To support Windows as well as UNIX-like systems, wimlib's API typically takes - * and returns strings of ::wimlib_tchar, which are in a platform-dependent - * encoding. - * - * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t", - * and the encoding is UTF-16LE. - * - * On UNIX-like systems, each ::wimlib_tchar is 1 byte and is simply a "char", - * and the encoding is the locale-dependent multibyte encoding. I recommend you - * set your locale to a UTF-8 capable locale to avoid any issues. Also, by - * default, wimlib on UNIX will assume the locale is UTF-8 capable unless you - * call wimlib_global_init() after having set your desired locale. - * - * \section Limitations + * @subsection subsec_limitations Limitations * * This section documents some technical limitations of wimlib not already * documented in the man page for @b wimlib-imagex. * * - The old WIM format from Vista pre-releases is not supported. - * - Compressed resource chunk sizes other than 32768 are not supported. This - * doesn't seem to be a real problem because the chunk size always seems to be - * this value. * - 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 possibly could be - * implemented on top of wimlib. + * as adding a driver or Windows component. Such a tool could be implemented + * on top of wimlib. + * + * @subsection more_info More information + * + * You are advised to read the README as well as the manual pages for + * wimlib-imagex, since not all relevant information is repeated here in + * the API documentation. + */ + +/** @defgroup G_general General + * + * @brief Declarations and structures shared across the library. + */ + +/** @defgroup G_creating_and_opening_wims Creating and Opening WIMs + * + * @brief Create new WIMs and open existing WIMs. + */ + +/** @defgroup G_wim_information Retrieving WIM information and directory listings + * + * @brief Retrieve information about a WIM or WIM image. + */ + +/** @defgroup G_modifying_wims Modifying WIMs + * + * @brief Make changes to a WIM. + * + * @section sec_adding_images Capturing and adding WIM images + * + * As described in @ref sec_basic_wim_handling_concepts, capturing a new WIM or + * appending an image to an existing WIM is a multi-step process, but at its + * core is wimlib_add_image() or an equivalent function. Normally, + * wimlib_add_image() takes an on-disk directory tree and logically adds it to a + * ::WIMStruct as a new image. However, when supported by the build of the + * library, there is also a special NTFS volume capture mode (entered when + * ::WIMLIB_ADD_FLAG_NTFS is specified) that allows adding the image directly + * from an unmounted NTFS volume. + * + * Another function, wimlib_add_image_multisource() is also provided. It + * generalizes wimlib_add_image() to allow combining multiple files or directory + * trees into a single WIM image in a configurable way. + * + * For maximum customization of WIM image creation, it is also possible to add a + * completely empty WIM image with wimlib_add_empty_image(), then update it with + * wimlib_update_image(). (This is in fact what wimlib_add_image() and + * wimlib_add_image_multisource() do internally.) + * + * Note that some details of how image addition/capture works are documented + * more fully in the manual page for wimlib-imagex capture. + * + * @section sec_deleting_images Deleting WIM images + * + * wimlib_delete_image() can delete an image from a ::WIMStruct. But as usual, + * wimlib_write() or wimlib_overwrite() must be called to cause the changes to + * be made persistent in an on-disk WIM file. + * + * @section sec_exporting_images Exporting WIM images + * + * wimlib_export_image() can copy, or "export", an image from one WIM to + * another. + * + * @section sec_other_modifications Other modifications + * + * wimlib_update_image() can add, delete, and rename files in a WIM image. + * + * wimlib_set_image_name(), wimlib_set_image_descripton(), and + * wimlib_set_image_flags() can change other image metadata. + * + * wimlib_set_wim_info() can change information about the WIM file itself, such + * as the boot index. + */ + +/** @defgroup G_extracting_wims Extracting WIMs + * + * @brief Extract files, directories, and images from a WIM. + * + * 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 list + * of (possibly wildcard) paths from a WIM image. + * + * wimlib_extract_image_from_pipe() extracts an image from a pipable WIM sent + * over a pipe; see @ref subsec_pipable_wims. + * + * Some details of how WIM extraction works are documented more fully in the + * manual pages for wimlib-imagex apply and wimlib-imagex extract. + */ + +/** @defgroup G_mounting_wim_images Mounting WIM images + * + * @brief Mount and unmount WIM images. + * + * On UNIX-like systems supporting FUSE (such as Linux), wimlib supports + * mounting images from WIM files either read-only or read-write. To mount an + * image, call wimlib_mount_image(). To unmount an image, call + * wimlib_unmount_image(). Mounting can be done without root privileges because + * it is implemented using FUSE (Filesystem in Userspace). If wimlib is + * compiled with the --without-fuse flag, these functions will be + * available but will fail with ::WIMLIB_ERR_UNSUPPORTED. Note that mounting an + * image read-write is an alternative to calling wimlib_update_image(). + */ + +/** @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). + */ + +/** @defgroup G_writing_and_overwriting_wims Writing and Overwriting WIMs + * + * @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. + */ + +/** @defgroup G_nonstandalone_wims Creating and handling non-standalone WIMs + * + * @brief Create and handle non-standalone WIMs, such as split and delta WIMs. + * + * Normally, ::WIMStruct represents a WIM file, but there's a bit more to it + * than that. Normally, WIM files are "standalone". However, WIM files can + * also be arranged in non-standalone ways, such as a set of on-disk files that + * together form a single "split WIM" or "delta WIM". Such arrangements are + * fully supported by wimlib. However, as a result, in such cases a ::WIMStruct + * created from one of these on-disk files initially only partially represents + * the full WIM and needs to, in effect, be logically combined with other + * ::WIMStruct's before performing certain operations, such as extracting files + * with wimlib_extract_image() or wimlib_extract_paths(). This is done by + * calling wimlib_reference_resource_files() or wimlib_reference_resources(). + * + * wimlib_write() can create delta WIMs as well as standalone WIMs, but a + * specialized function (wimlib_split()) is needed to create a split WIM. */ #ifndef _WIMLIB_H @@ -171,14 +335,25 @@ #include #include -/** Major version of the library (for example, the 1 in 1.2.5). */ +/** @ingroup 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 6 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 0 +#define WIMLIB_PATCH_VERSION 3 + +#ifdef __cplusplus +extern "C" { +#endif + +/** @} */ +/** @ingroup G_general + * @{ */ /** * Opaque structure that represents a WIM file. This is an in-memory structure @@ -192,6 +367,8 @@ * * Use wimlib_write() or wimlib_overwrite() to actually write an on-disk WIM * file from a ::WIMStruct. + * + * See @ref sec_basic_wim_handling_concepts for more information. */ #ifndef WIMLIB_WIMSTRUCT_DECLARED typedef struct WIMStruct WIMStruct; @@ -201,7 +378,7 @@ typedef struct WIMStruct WIMStruct; #ifdef __WIN32__ typedef wchar_t wimlib_tchar; #else -/** See \ref encodings */ +/** See @ref sec_encodings */ typedef char wimlib_tchar; #endif @@ -215,6 +392,15 @@ typedef char wimlib_tchar; # define WIMLIB_WIM_PATH_SEPARATOR_STRING "/" #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) + #ifdef __GNUC__ # define _wimlib_deprecated __attribute__((deprecated)) #else @@ -233,132 +419,175 @@ enum wimlib_compression_type { /** The WIM does not include any compressed resources. */ WIMLIB_COMPRESSION_TYPE_NONE = 0, + /** Compressed resources in the WIM use XPRESS compression. */ + WIMLIB_COMPRESSION_TYPE_XPRESS = 1, + /** Compressed resources in the WIM use LZX compression. */ - WIMLIB_COMPRESSION_TYPE_LZX = 1, + WIMLIB_COMPRESSION_TYPE_LZX = 2, - /** 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). */ + WIMLIB_COMPRESSION_TYPE_LZMS = 3, }; +/** @} */ +/** @ingroup G_progress + * @{ */ + /** Possible values of the first parameter to the user-supplied * ::wimlib_progress_func_t progress function */ 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, - /** A file or directory tree within a WIM image (not the full image) is - * about to be extracted. @p info will point to - * ::wimlib_progress_info.extract. */ + /** 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, - /** The directory structure of the WIM image is about to be extracted. - * @p info will point to ::wimlib_progress_info.extract. */ + /** The directory structure and other preliminary metadata is about to + * be extracted. @p info will point to ::wimlib_progress_info.extract. + * This message is received once after either + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN or + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */ 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. */ + /** Confirms that the directory structure and other preliminary metadata + * has been successfully extracted. @p info will point to + * ::wimlib_progress_info.extract. This message is paired with a + * preceding ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN message. + */ 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. */ + /** 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, /** 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. */ + /** All data for WIM files and directories have been extracted, and + * final metadata such as timestamps is about to be extracted. @p info + * will point to ::wimlib_progress_info.extract. This message is + * received once before ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END or + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END. */ WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS, - /** A WIM image has been successfully extracted. @p info will point to - * ::wimlib_progress_info.extract. */ + /** 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, - /** 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. */ + /** 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, - /** 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. */ + /** 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, - /** A directory or file is being scanned. @p info will point to + /** 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(). */ + * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE has + * been specified. */ 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. */ + /** 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, - /** - * File resources are currently being written to the WIM. - * @p info will point to ::wimlib_progress_info.write_streams. */ + /** 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, - /** - * The metadata resource for each image is about to be written to the - * WIM. @p info will not be valid. */ + /** Per-image metadata is about to be written to the WIM file. @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. */ + /** 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, - /** - * 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_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, - /** 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. */ + /** 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() is called with the + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. */ WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY, /** 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. */ + * @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, - /** 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.) */ + /** Reserved. */ WIMLIB_PROGRESS_MSG_RESERVED, /** 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_info.split. */ WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART, /** A wimlib_split() operation is in progress, and a split part has been - * finished. @p info will point to ::wimlib_progress_info.split. */ + * 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. - */ + /** 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, - /** - * A WIM update command has just been executed; @p info will point to - * ::wimlib_progress_info.update. - */ + /** 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, + /** 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, + + /** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and + * a file is being extracted normally (not as a WIMBoot "pointer file") + * due to it matching a pattern in the [PrepopulateList] section of the + * configuration file \Windows\System32\WimBootCompress.ini in the WIM + * image. @info will point to ::wimlib_progress_info.wimboot_exclude. + */ + WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE, }; /** A pointer to this union is passed to the user-supplied @@ -371,129 +600,254 @@ 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 a 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 a 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. */ + /** 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 + * point and it is being excluded from capture because + * it points outside of the capture directory and + * reparse-point fixups are enabled. (Reparse point + * fixups can be disabled by using the flag + * ::WIMLIB_ADD_FLAG_NORPFIX.) */ + WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, } 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_EXCLUDED_SYMLINK, this is + * the target of the absolute symbolic link or junction + * point. */ + 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. + * + * 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. + * + * 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, + /** 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_DIR_STRUCTURE_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, and - * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */ + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, and + * ::WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS. + * + * 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.) */ + /** Number of (not necessarily unique) streams that will be + * extracted. This may be more or less than the number of + * "files" to be extracted due to hard links as well as + * potentially multiple streams per file (named data streams). + * A "stream" may be the default contents of a file, a named + * data stream, or a reparse data buffer. */ uint64_t num_streams; - /** 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. */ - const wimlib_tchar *extract_root_wim_source_path; + /** Reserved. */ + const wimlib_tchar *reserved_2; /** 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. */ @@ -579,6 +933,21 @@ union wimlib_progress_info { * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */ const 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; }; /** A user-supplied function that will be called periodically during certain WIM @@ -593,6 +962,10 @@ union wimlib_progress_info { typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, const union wimlib_progress_info *info); +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ + /** An array of these structures is passed to wimlib_add_image_multisource() to * specify the sources from which to create a WIM image. */ struct wimlib_capture_source { @@ -600,55 +973,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 @@ -675,6 +1007,10 @@ struct wimlib_capture_config { * reparse-point fixups by default when capturing or applying WIM images. */ #define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 +/** @} */ +/** @ingroup G_wim_information + * @{ */ + /** General information about a WIM file. */ struct wimlib_wim_info { @@ -695,12 +1031,12 @@ struct wimlib_wim_info { /** Chunk size used for compression. */ uint32_t chunk_size; - /** 1-based index of this part within a split WIM, or 1 if the WIM is - * standalone. */ + /** For split WIMs, the 1-based index of this part within the split WIM; + * otherwise 1. */ uint16_t part_number; - /** Total number of parts in the split WIM, or 1 if the WIM is - * standalone. */ + /** For split WIMs, the total number of parts in the split WIM; + * otherwise 1. */ uint16_t total_parts; /** One of the ::wimlib_compression_type values that specifies the @@ -745,41 +1081,64 @@ struct wimlib_wim_info { uint32_t reserved[9]; }; -/** Information about a unique resource in the WIM file. - */ +/** Information about a unique stream in the WIM file. (A stream is the same + * thing as a "resource", except in the case of packed resources.) */ struct wimlib_resource_entry { - /** Uncompressed size of the resource in bytes. */ + /** Uncompressed size of the stream in bytes. */ uint64_t uncompressed_size; - /** Compressed size of the resource in bytes. This will be the same as - * @p uncompressed_size if the resource is uncompressed. */ + /** Compressed size of the stream in bytes. This will be the same as @p + * uncompressed_size if the stream is uncompressed. Or, if @p + * is_packed_streams is 1, this will be 0. */ uint64_t compressed_size; - /** Offset, in bytes, of this resource from the start of the WIM file. + /** Offset, in bytes, of this stream from the start of the WIM file. Or + * if @p packed is 1, then this is actually the offset at which this + * stream begins in the uncompressed contents of the packed resource. */ uint64_t offset; - /** SHA1 message digest of the resource's uncompressed contents. */ + /** SHA1 message digest of the stream's uncompressed contents. */ uint8_t sha1_hash[20]; - /** Which part number of the split WIM this resource is in. This should + /** Which part number of the split WIM this stream is in. This should * be the same as the part number provided by wimlib_get_wim_info(). */ uint32_t part_number; - /** Number of times this resource is referenced over all WIM images. */ + /** Number of times this stream is referenced over all WIM images. */ uint32_t reference_count; - /** 1 if this resource is compressed. */ + /** 1 if this stream is compressed. */ uint32_t is_compressed : 1; - /** 1 if this resource is a metadata resource rather than a file - * resource. */ + /** 1 if this stream is a metadata resource rather than a file resource. + * */ uint32_t is_metadata : 1; uint32_t is_free : 1; uint32_t is_spanned : 1; - uint32_t reserved_flags : 28; - uint64_t reserved[4]; + + /** 1 if this stream was not found in the lookup table of the + * ::WIMStruct. This normally implies a missing call to + * wimlib_reference_resource_files() or wimlib_reference_resources(). + * */ + uint32_t is_missing : 1; + + /** 1 if this stream is located in a packed resource which may contain + * other streams (all compressed together) as well. */ + uint32_t packed : 1; + + uint32_t reserved_flags : 26; + + /** If @p packed is 1, then this will specify the offset of the packed + * resource in the WIM. */ + uint64_t raw_resource_offset_in_wim; + + /** If @p is_packed_streams is 1, then this will specify the compressed + * size of the packed resource in the WIM. */ + uint64_t raw_resource_compressed_size; + + uint64_t reserved[2]; }; /** A stream of a file in the WIM. */ @@ -850,6 +1209,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 @@ -908,43 +1268,50 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * itself; only its children (in the case of a non-empty directory) */ #define WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002 +/** Return ::WIMLIB_ERR_RESOURCE_NOT_FOUND if any resources needed to fill in + * the ::wimlib_resource_entry's for the iteration cannot be found in the lookup + * table of the ::WIMStruct. The default behavior without this flag is to fill + * in the SHA1 message digest of the ::wimlib_resource_entry and set the @ref + * wimlib_resource_entry::is_missing "is_missing" flag. */ +#define WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED 0x00000004 -/***************************** - * WIMLIB_ADD_FLAG_* - *****************************/ +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ /** Directly capture a 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. */ + * ::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. */ -#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 + * only; Microsoft's implementation will not understand this special + * 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 @@ -971,6 +1338,56 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * documentation for ::WIMLIB_ADD_FLAG_RPFIX. */ #define WIMLIB_ADD_FLAG_NORPFIX 0x00000200 +/** Do not automatically exclude unsupported files or directories from capture; + * e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on + * UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when + * such a file is encountered. */ +#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 + +/** + * Automatically select a capture configuration appropriate for capturing + * filesystems containing Windows operating systems. For example, + * "pagefile.sys" and "System Volume Information" will be excluded. + * + * 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 + * no files are excluded from capture. + */ +#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 @@ -981,10 +1398,15 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE #define WIMLIB_ADD_IMAGE_FLAG_RPFIX WIMLIB_ADD_FLAG_RPFIX #define WIMLIB_ADD_IMAGE_FLAG_NORPFIX WIMLIB_ADD_FLAG_NORPFIX +#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 + -/****************************** - * WIMLIB_DELETE_FLAG_* - ******************************/ +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ /** Do not issue an error if the path to delete does not exist. */ #define WIMLIB_DELETE_FLAG_FORCE 0x00000001 @@ -993,16 +1415,29 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * issued if the path to delete is a directory. */ #define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002 -/****************************** - * WIMLIB_EXPORT_FLAG_* - ******************************/ +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ -/** See documentation for wimlib_export_image(). */ +/** + * If a single image is being exported, mark it bootable in the destination WIM. + * Alternatively, if ::WIMLIB_ALL_IMAGES is specified as the image to export, + * the image in the source WIM (if any) that is marked as bootable is also + * marked as bootable in the destination WIM. + */ #define WIMLIB_EXPORT_FLAG_BOOT 0x00000001 -/****************************** - * WIMLIB_EXTRACT_FLAG_* - ******************************/ +/** Give the exported image(s) no names. Avoids problems with image name + * collisions. + */ +#define WIMLIB_EXPORT_FLAG_NO_NAMES 0x00000002 + +/** Give the exported image(s) no descriptions. */ +#define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004 + +/** @} */ +/** @ingroup G_extracting_wims + * @{ */ /** Extract the image directly to a NTFS volume rather than a generic directory. * This mode is only available if wimlib was compiled with libntfs-3g support; @@ -1015,48 +1450,57 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001 /** When identical files are extracted from the WIM, always hard link them - * together. */ + * together. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_SYMLINK. + */ #define WIMLIB_EXTRACT_FLAG_HARDLINK 0x00000002 /** When identical files are extracted from the WIM, always symlink them - * together. */ + * together. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_HARDLINK. + */ #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. */ +/** 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. - * Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */ +/** 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. */ #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. */ +/** Extract the paths, each of which must name a regular file, to standard + * output. Not valid for wimlib_extract_image() and + * wimlib_extract_image_from_pipe(). */ #define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400 /** Instead of ignoring files and directories with names that cannot be @@ -1083,13 +1527,50 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * create symbolic links. */ #define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000 -/** TODO */ +/** 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 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 + * (::WIMLIB_ERR_PATH_DOES_NOT_EXIST) rather than a warning to be issued when + * 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 -/****************************** - * WIMLIB_MOUNT_FLAG_* - ******************************/ +/** @} */ +/** @ingroup G_mounting_wim_images + * @{ */ /** Mount the WIM image read-write rather than the default of read-only. */ #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 @@ -1116,60 +1597,67 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * allow_other option to FUSE mount) */ #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 -/****************************** - * WIMLIB_OPEN_FLAG_* - ******************************/ +/** @} */ +/** @ingroup 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. */ + * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the + * integrity table is invalid). */ #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001 -/** Do not issue an error if the WIM is part of a split WIM. */ -#define WIMLIB_OPEN_FLAG_SPLIT_OK 0x00000002 +/** 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. */ +#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 to make changes to the WIM, but with this flag you get the error sooner - * rather than later. */ + * 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 -/****************************** - * WIMLIB_UNMOUNT_FLAG_* - ******************************/ +/** @} */ +/** @ingroup G_mounting_wim_images + * @{ */ -/** Include an integrity table in the WIM after it's been unmounted. Ignored - * for read-only mounts. */ +/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ #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. */ + * discarded. Ignored for read-only mounts. */ #define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002 -/** See ::WIMLIB_WRITE_FLAG_REBUILD */ +/** See ::WIMLIB_WRITE_FLAG_REBUILD. */ #define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004 /** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */ #define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008 -/** Do a "lazy" unmount (detach filesystem immediately, even if busy) */ +/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */ #define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010 -/****************************** - * WIMLIB_UPDATE_FLAG_* - ******************************/ +/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted + * image, causes the modified image to be committed as a new, unnamed image + * appended to the archive. The original image will be unmodified. */ +#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020 + +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ /** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and - * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */ + * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */ #define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001 -/****************************** - * WIMLIB_WRITE_FLAG_* - ******************************/ +/** @} */ +/** @ingroup G_writing_and_overwriting_wims + * @{ */ /** Include an integrity table in the WIM. * @@ -1219,7 +1707,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * 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. */ + * space will be saved by deleting an image in this way. */ #define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080 /** wimlib_overwrite() only: Allow overwriting the WIM even if the readonly @@ -1228,12 +1716,46 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * set the readonly flag on the on-disk WIM file. */ #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 -/****************************** - * WIMLIB_INIT_FLAG_* - ******************************/ +/** 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(). */ +#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(). */ +#define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 + +#define WIMLIB_WRITE_FLAG_RESERVED 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. */ +#define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000 + +/** @} */ +/** @ingroup G_general + * @{ */ /** Assume that strings are represented in UTF-8, even if this is not the - * locale's character encoding. Not used on Windows. */ + * locale's character encoding. This flag is ignored on Windows, where wimlib + * always uses UTF-16LE. */ #define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 /** Windows-only: do not attempt to acquire additional privileges (currently @@ -1245,78 +1767,122 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * actually require additional privileges or not. */ #define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002 -/** Specification of an update to perform on a WIM image. */ -struct wimlib_update_command { +/** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, + * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed + * to read all possible data and metadata for a capture operation could not be + * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES. + */ +#define WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES 0x00000004 + +/** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, + * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed + * to restore all possible data and metadata for an apply operation could not be + * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES. + */ +#define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008 + +/** Default to interpreting WIM paths case sensitively (default on UNIX-like + * systems). */ +#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010 + +/** Default to interpreting WIM paths case insensitively (default on Windows). + * This does not apply to mounted images. */ +#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020 + +/** @} */ +/** @ingroup G_nonstandalone_wims + * @{ */ + +/** For wimlib_reference_resource_files(), enable shell-style filename globbing. + * Ignored by wimlib_reference_resources(). */ +#define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 + +/** 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. Ignored by + * wimlib_reference_resources(). */ +#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 + +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ + +/** The specific type of update to perform. */ +enum wimlib_update_op { + /** Add a new file or directory tree to the WIM image in a + * certain location. */ + WIMLIB_UPDATE_OP_ADD = 0, + + /** Delete a file or directory tree from the WIM image. */ + WIMLIB_UPDATE_OP_DELETE, + + /** Rename a file or directory tree in the WIM image. */ + WIMLIB_UPDATE_OP_RENAME, +}; - /** The specific type of update to perform. */ - enum wimlib_update_op { - /** Add a new file or directory tree to the WIM image in a - * certain location. */ - WIMLIB_UPDATE_OP_ADD = 0, +/** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ +struct wimlib_add_command { + /** Filesystem path to the file or directory tree to add. */ + wimlib_tchar *fs_source_path; - /** Delete a file or directory tree from the WIM image. */ - WIMLIB_UPDATE_OP_DELETE, + /** 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; - /** Rename a file or directory tree in the WIM image. */ - WIMLIB_UPDATE_OP_RENAME, - } op; - union { - /** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ - struct wimlib_add_command { - /** 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. */ - wimlib_tchar *wim_target_path; - - /** Configuration for excluded files. @c NULL means - * exclude no files. */ - struct wimlib_capture_config *config; - - /** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */ - int add_flags; - } add; - /** 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. */ - wimlib_tchar *wim_path; - /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ - int delete_flags; - } delete; - /** 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. */ - 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. */ - wimlib_tchar *wim_target_path; - /** Reserved; set to 0. */ - int rename_flags; - } rename; - }; + /** 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; +}; + +/** 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. */ + wimlib_tchar *wim_path; + + /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ + int delete_flags; }; -/** Specification of a file or directory tree to extract from a WIM image. */ -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. */ +/** 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. */ wimlib_tchar *wim_source_path; - /** Filesystem path to extract the file or directory tree to. */ - wimlib_tchar *fs_dest_path; + /** 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. */ + int rename_flags; +}; + +/** Specification of an update to perform on a WIM image. */ +struct wimlib_update_command { + + enum wimlib_update_op op; - /** Bitwise or of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */ - int extract_flags; + union { + struct wimlib_add_command add; + struct wimlib_delete_command delete_; /* Underscore is for C++ + compatibility. */ + struct wimlib_rename_command rename; + }; }; +/** @} */ +/** @ingroup G_general + * @{ */ + /** * Possible values of the error code returned by many functions in wimlib. * @@ -1332,9 +1898,11 @@ enum wimlib_error_code { 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, @@ -1351,13 +1919,14 @@ enum wimlib_error_code { WIMLIB_ERR_INVALID_PIPABLE_WIM, WIMLIB_ERR_INVALID_REPARSE_DATA, WIMLIB_ERR_INVALID_RESOURCE_HASH, - WIMLIB_ERR_INVALID_SECURITY_DATA, 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, @@ -1384,17 +1953,19 @@ enum wimlib_error_code { WIMLIB_ERR_SET_SHORT_NAME, WIMLIB_ERR_SET_TIMESTAMPS, WIMLIB_ERR_SPLIT_INVALID, - WIMLIB_ERR_SPLIT_UNSUPPORTED, WIMLIB_ERR_STAT, WIMLIB_ERR_TIMEOUT, WIMLIB_ERR_UNEXPECTED_END_OF_FILE, WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE, WIMLIB_ERR_UNKNOWN_VERSION, WIMLIB_ERR_UNSUPPORTED, + WIMLIB_ERR_UNSUPPORTED_FILE, WIMLIB_ERR_VOLUME_LACKS_FEATURES, WIMLIB_ERR_WIM_IS_READONLY, WIMLIB_ERR_WRITE, WIMLIB_ERR_XML, + WIMLIB_ERR_WIM_IS_ENCRYPTED, + WIMLIB_ERR_WIMBOOT, }; @@ -1404,7 +1975,11 @@ enum wimlib_error_code { /** Used to specify all images in the WIM. */ #define WIMLIB_ALL_IMAGES (-1) +/** @} */ + /** + * @ingroup G_modifying_wims + * * Appends an empty image to a WIM file. This empty image will initially * contain no files or directories, although if written without further * modifications, a root directory will be created automatically for it. After @@ -1441,6 +2016,8 @@ wimlib_add_empty_image(WIMStruct *wim, int *new_idx_ret); /** + * @ingroup G_modifying_wims + * * Adds an image to a WIM file from an on-disk directory tree or NTFS volume. * * The directory tree or NTFS volume is scanned immediately to load the dentry @@ -1465,10 +2042,15 @@ 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 @@ -1492,11 +2074,14 @@ extern int wimlib_add_image(WIMStruct *wim, const wimlib_tchar *source, const wimlib_tchar *name, - const struct wimlib_capture_config *config, + const wimlib_tchar *config_file, int add_flags, wimlib_progress_func_t progress_func); -/** This function is equivalent to wimlib_add_image() except it allows for +/** + * @ingroup G_modifying_wims + * + * This function is equivalent to wimlib_add_image() except it allows for * multiple sources to be combined into a single WIM image. This is done by * specifying the @p sources and @p num_sources parameters instead of the @p * source parameter of wimlib_add_image(). The rest of the parameters are the @@ -1518,20 +2103,21 @@ 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, + const wimlib_tchar *config_file, int add_flags, wimlib_progress_func_t progress_func); /** + * @ingroup G_creating_and_opening_wims + * * Creates a ::WIMStruct for a new WIM file. * * This only creates an in-memory structure for a WIM that initially contains no * images. No on-disk file is created until wimlib_write() is called. * * @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 @@ -1539,8 +2125,7 @@ wimlib_add_image_multisource(WIMStruct *wim, * 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. */ @@ -1548,6 +2133,8 @@ extern int wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); /** + * @ingroup G_modifying_wims + * * Deletes an image, or all images, from a WIM file. * * All streams referenced by the image(s) being deleted are removed from the @@ -1577,15 +2164,18 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); * flag. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, - * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM, - * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which - * indicate failure (for different reasons) to read the metadata resource for an - * image that needed to be deleted. + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be deleted. */ extern int wimlib_delete_image(WIMStruct *wim, int image); /** + * @ingroup G_modifying_wims + * * Exports an image, or all the images, from a WIM file, into another WIM file. * * The destination image is made to share the same dentry tree and security data @@ -1604,79 +2194,71 @@ wimlib_delete_image(WIMStruct *wim, int image); * dest_wim (if any) until wimlib_write() or wimlib_overwrite() is called. * * @param src_wim - * Pointer to the ::WIMStruct for a stand-alone WIM or part 1 of a split - * WIM that contains the image(s) being exported. + * The WIM from which to export the images, 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 src_image - * The image to export from @p src_wim. Can be the number of an image, or - * ::WIMLIB_ALL_IMAGES to export all images. + * The image to export from @p src_wim, as either a 1-based image index to + * export a single image, or ::WIMLIB_ALL_IMAGES to export all images. * @param dest_wim - * Pointer to the ::WIMStruct for a WIM file that will receive the images - * being exported. + * Pointer to the ::WIMStruct for a WIM that will receive the images being + * exported. * @param dest_name - * The name to give the exported image in the new WIM file. If left @c - * NULL, the name from @p src_wim is used. This parameter must be left @c - * NULL if @p src_image is ::WIMLIB_ALL_IMAGES and @p src_wim contains more - * than one image; in that case, the names are all taken from the @p - * src_wim. (This is allowed even if one or more images being exported has - * no name.) + * For single-image exports, the name to give the exported image in @p + * dest_wim. If left @c NULL, the name from @p src_wim is used. For + * ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c NULL; in + * that case, the names are all taken from @p src_wim. This parameter is + * overridden by ::WIMLIB_EXPORT_FLAG_NO_NAMES. * @param dest_description - * The description to give the exported image in the new WIM file. If left - * @c NULL, the description from the @p src_wim is used. This parameter must - * be left @c NULL if @p src_image is ::WIMLIB_ALL_IMAGES and @p src_wim contains - * more than one image; in that case, the descriptions are all taken from - * @p src_wim. (This is allowed even if one or more images being exported - * has no description.) + * For single-image exports, the description to give the exported image in + * the new WIM file. If left @c NULL, the description from @p src_wim is + * used. For ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c + * NULL; in that case, the description are all taken from @p src_wim. This + * parameter is overridden by ::WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS. * @param export_flags - * ::WIMLIB_EXPORT_FLAG_BOOT if the image being exported is to be made - * bootable, or 0 if which image is marked as bootable in the destination - * WIM is to be left unchanged. If @p src_image is ::WIMLIB_ALL_IMAGES and - * there are multiple images in @p src_wim, specifying - * ::WIMLIB_EXPORT_FLAG_BOOT is valid only if one of the exported images is - * currently marked as bootable in @p src_wim; if that is the case, then - * that image is marked as bootable in the destination WIM. - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. + * Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG. * @param progress_func - * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * 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 * One or more of the names being given to an exported image was already in * use in the destination WIM. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p src_image does not exist in @p src_wim. + * @p src_image does not exist in @p src_wim and was not + * ::WIMLIB_ALL_IMAGES. * @retval ::WIMLIB_ERR_INVALID_PARAM - * ::WIMLIB_EXPORT_FLAG_BOOT was specified in @p flags, @p src_image was - * ::WIMLIB_ALL_IMAGES, @p src_wim contains multiple images, and no images in - * @p src_wim are marked as bootable; or @p dest_name and/or @p - * dest_description were non-NULL, @p src_image was - * ::WIMLIB_ALL_IMAGES, and @p src_wim contains multiple images. + * @p src_wim and/or @p dest_wim were @c NULL; or @p src_image was + * ::WIMLIB_ALL_IMAGES but @p dest_name and/or @p dest_description were not + * @c NULL. + * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND + * Either @p src_wim or @p dest_wim did not contain metadata resources; for + * example, one of them was a non-first part of a split WIM. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_SPLIT_INVALID - * The source WIM is a split WIM, but the parts specified do not form a - * complete split WIM because they do not include all the parts of the - * split WIM, there are duplicate parts, or not all the parts are in fact - * from the same split WIM. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * A resource that needed to be exported could not be found in either the + * source or destination WIMs. This error can occur if, for example, @p + * src_wim is part of a split WIM but needed resources from the other split + * WIM parts were not referenced with wimlib_reference_resources() or + * wimlib_reference_resource_files() before the call to + * wimlib_export_image(). * @retval ::WIMLIB_ERR_WIM_IS_READONLY * @p dest_wim is considered read-only because of any of the reasons * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS * flag. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, - * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM, - * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which - * indicate failure (for different reasons) to read the metadata resource for an - * image in @p src_wim that needed to be exported. + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image in @p src_wim + * that needed to be exported. */ extern int wimlib_export_image(WIMStruct *src_wim, int src_image, @@ -1684,89 +2266,15 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, const wimlib_tchar *dest_name, const wimlib_tchar *dest_description, int export_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, wimlib_progress_func_t progress_func); + /** - * Extract zero or more files or directory trees from a WIM image. + * @ingroup G_extracting_wims * - * 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 - * Pointer to the ::WIMStruct for a standalone WIM file, or part 1 of a - * split WIM. - * - * @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 additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. - * - * @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, - WIMStruct **additional_swms, - unsigned num_additional_swms, - wimlib_progress_func_t progress_func); - -/** - * Extracts an image, or all images, from a standalone or split WIM file 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 @@ -1774,75 +2282,63 @@ 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 - * Pointer to the ::WIMStruct for a standalone WIM file, or part 1 of a - * split WIM. + * The WIM from which to extract the image(s), specified as a pointer to + * the ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 + * of a split WIM. In the case of a WIM file that is not standalone, this + * ::WIMStruct must have had any needed external resources previously + * referenced using wimlib_reference_resources() or + * wimlib_reference_resource_files(). * @param image - * The image to extract. 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 additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. - * + * Bitwise OR of 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. + * If non-NULL, a function that will be called periodically with the + * progress of the current operation. The main message to look for is + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS; however, there are others as + * well. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress a resource to be extracted, or failed to decompress - * a needed metadata resource. - * @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. + * Failed to decompress data contained in the WIM. * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE - * The metadata resource for an image being extracted was invalid. + * The metadata for one of the images to extract was invalid. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The extraction flags were invalid; more details may be found in the + * documentation for the specific extraction flags that were specified. Or + * @p target was @c NULL or the empty string, or @p wim was @c NULL. * @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 @@ -1862,14 +2358,8 @@ wimlib_extract_files(WIMStruct *wim, * @retval ::WIMLIB_ERR_SET_TIMESTAMPS * Failed to set timestamps on a file (only if * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS was specified in @p extract_flags). - * @retval ::WIMLIB_ERR_SPLIT_INVALID - * The WIM is a split WIM, but the parts specified do not form a complete - * split WIM because they do not include all the parts of the original WIM, - * there are duplicate parts, or not all the parts have the same GUID and - * compression type. * @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 @@ -1881,12 +2371,14 @@ wimlib_extract_files(WIMStruct *wim, * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS, ::WIMLIB_EXTRACT_FLAG_SYMLINK, * and ::WIMLIB_EXTRACT_FLAG_HARDLINK. 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. */ @@ -1894,13 +2386,13 @@ extern int wimlib_extract_image(WIMStruct *wim, int image, const wimlib_tchar *target, int extract_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, wimlib_progress_func_t progress_func); /** - * Since wimlib v1.5.0: Extract one or more images from a pipe on which a - * pipable WIM is being sent. + * @ingroup G_extracting_wims + * + * 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. @@ -1920,22 +2412,21 @@ wimlib_extract_image(WIMStruct *wim, int image, * wimlib_resolve_image() uses. However, unlike wimlib_extract_image(), * only a single image (not all images) can be specified. Alternatively, * specify @p NULL here to use the first image in the WIM if it contains - * exactly one image but otherwise return @p WIMLIB_ERR_INVALID_IMAGE. + * exactly one image but otherwise return ::WIMLIB_ERR_INVALID_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 + * that ::WIMLIB_EXTRACT_FLAG_FILE_ORDER cannot be specified 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. + * received by the progress function. * * @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. @@ -1949,12 +2440,126 @@ wimlib_extract_image_from_pipe(int pipe_fd, wimlib_progress_func_t progress_func); /** - * Extracts the XML data of a WIM file to a file stream. Every WIM file - * includes a string of XML that describes the images contained in the WIM. - * This function works on standalone WIMs as well as split WIM parts. + * @ingroup G_extracting_wims + * + * Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to + * extract from the WIM image are specified in the UTF-8 text file named by @p + * 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 (::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT, + * ::WIMLIB_ERR_READ, ::WIMLIB_ERR_NOMEM, or ::WIMLIB_ERR_INVALID_UTF8_STRING). + */ +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); + +/** + * @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 - * Pointer to the ::WIMStruct for a WIM file. + * 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. + * @param progress_func + * If non-NULL, a function that will be called periodically with the + * progress of the current operation. The main message to look for is + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS; however, there are others as + * well. Note: 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. + * + * @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. + */ +extern int +wimlib_extract_paths(WIMStruct *wim, + int image, + const wimlib_tchar *target, + const wimlib_tchar * const *paths, + size_t num_paths, + int extract_flags, + wimlib_progress_func_t progress_func); + +/** + * @ingroup G_wim_information + * + * Extracts the XML data of a WIM file to a file stream. Every WIM file + * includes a string of XML that describes the images contained in the WIM. + * + * See wimlib_get_xml_data() to read the XML data into memory instead. + * + * @param wim + * Pointer to the ::WIMStruct for a WIM file, which does not necessarily + * have to be standalone (e.g. it could be part of a split WIM). * @param fp * @c stdout, or a FILE* opened for writing, to extract the data to. * @@ -1972,6 +2577,8 @@ extern int wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); /** + * @ingroup G_general + * * Frees all memory allocated for a WIMStruct and closes all files associated * with it. * @@ -1984,20 +2591,23 @@ extern void wimlib_free(WIMStruct *wim); /** + * @ingroup G_general + * * 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); /** + * @ingroup G_general + * * Converts an error code into a string describing it. * * @param code @@ -2011,11 +2621,13 @@ extern const wimlib_tchar * wimlib_get_error_string(enum wimlib_error_code code); /** + * @ingroup G_wim_information + * * Returns the description of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or a split WIM part. + * 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). * @param image * The number of the image, numbered starting at 1. * @@ -2030,11 +2642,13 @@ extern const wimlib_tchar * wimlib_get_image_description(const WIMStruct *wim, int image); /** + * @ingroup G_wim_information + * * Returns the name of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or a split WIM part. + * 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). * @param image * The number of the image, numbered starting at 1. * @@ -2048,13 +2662,28 @@ 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 + * * Get basic information about a WIM file. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be for either a - * standalone WIM or part of a split 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). * @param info * A ::wimlib_wim_info structure that will be filled in with information * about the WIM file. @@ -2065,21 +2694,61 @@ extern int wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); /** + * @ingroup G_wim_information + * + * Read the XML data of a WIM file into an in-memory buffer. Every WIM file + * includes a string of XML that describes the images contained in the WIM. + * + * See wimlib_extract_xml_data() to extract the XML data to a file stream + * 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). + * @param buf_ret + * On success, a pointer to an allocated buffer containing the raw UTF16-LE + * XML data is written to this location. + * @param bufsize_ret + * The size of the XML data in bytes is written to this location. + * + * @return 0 on success; nonzero on error. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(), or + * @p buf_ret or @p bufsize_ret was @c NULL. + * @retval ::WIMLIB_ERR_NOMEM + * @retval ::WIMLIB_ERR_READ + * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE + * Failed to read the XML data from the WIM. + */ +extern int +wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); + +/** + * @ingroup G_general + * * Initialization function for wimlib. Call before using any other wimlib - * function except wimlib_set_print_errors(). (However, currently this is not - * strictly necessary and it will be called automatically if not done manually, - * but you should not rely on this behavior.) + * 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. This function does nothing if called again + * after it has already successfully run. * * @param init_flags - * Bitwise OR of ::WIMLIB_INIT_FLAG_ASSUME_UTF8 and/or - * ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES. + * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. * - * @return 0; other error codes may be returned in future releases. + * @return 0 on success; nonzero on failure. Currently, only the following + * error code is defined: + * + * @retval ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES + * ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES and/or + * ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES were specified in @p + * init_flags, but the corresponding privileges could not be acquired. */ extern int wimlib_global_init(int init_flags); /** + * @ingroup G_general + * * Cleanup function for wimlib. You are not required to call this function, but * it will release any global resources allocated by the library. */ @@ -2087,6 +2756,8 @@ extern void wimlib_global_cleanup(void); /** + * @ingroup G_wim_information + * * Determines if an image name is already used by some image in the WIM. * * @param wim @@ -2103,14 +2774,22 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); /** + * @ingroup G_wim_information + * * Iterate through a file or directory tree in the WIM image. By specifying * appropriate flags and a callback function, you can get the attributes of a * file in the WIM, get a directory listing, or even get a listing of the entire * WIM image. * * @param wim - * Pointer to the ::WIMStruct for a standalone WIM file, or part 1 of a - * split WIM. + * The WIM containing the image(s) over which to iterate, specified as a + * pointer to the ::WIMStruct for a standalone WIM file, a delta WIM file, + * or part 1 of a split WIM. In the case of a WIM file that is not + * standalone, this ::WIMStruct should have had any needed external + * resources previously referenced using wimlib_reference_resources() or + * wimlib_reference_resource_files(). If not, see + * ::WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED for information about + * the behavior when resources are missing. * * @param image * The 1-based number of the image in @p wim that contains the files or @@ -2121,8 +2800,7 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * Path in the WIM image at which to do the iteration. * * @param flags - * Bitwise OR of ::WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE and/or - * ::WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN. + * Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG. * * @param cb * A callback function that will receive each directory entry. @@ -2141,10 +2819,11 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * Failed to allocate memory needed to create a ::wimlib_dir_entry. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, - * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM, - * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which - * indicate failure (for different reasons) to read the metadata resource for an - * image over which iteration needed to be done. + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image over which + * iteration needed to be done. */ extern int wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, @@ -2152,14 +2831,21 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, wimlib_iterate_dir_tree_callback_t cb, void *user_ctx); /** + * @ingroup G_wim_information + * * Iterate through the lookup table of a WIM file. This can be used to directly - * get a listing of the unique resources contained in a WIM file. Both file - * resources and metadata resources are included. + * get a listing of the unique resources contained in a WIM file over all + * images. Both file resources and metadata resources are included. However, + * only resources actually included in the file represented by @a wim, plus + * explicitly referenced external resources (via wimlib_reference_resources() or + * wimlib_reference_resource_files()) are included in the iteration. For + * example, if @p wim represents just one part of a split WIM, then only + * resources in that part will be included, unless other resources were + * explicitly referenced. * * @param wim - * Pointer to the ::WIMStruct of a standalone WIM file or a split WIM part. - * Note: metadata resources will only be included if the WIM is standalone - * or the first part of the split 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). * * @param flags * Reserved; set to 0. @@ -2180,6 +2866,8 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, void *user_ctx); /** + * @ingroup G_nonstandalone_wims + * * Joins a split WIM into a stand-alone one-part WIM. * * @param swms @@ -2190,8 +2878,7 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * Number of filenames in @p swms. * @param swm_open_flags * Open flags for the split WIM parts (e.g. - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). Note: WIMLIB_OPEN_FLAG_SPLIT_OK is - * automatically added to the value specified here. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). * @param wim_write_flags * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will * be used to write the joined WIM. @@ -2210,9 +2897,12 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * the parts of the original WIM, there are duplicate parts, or not all the * parts have the same GUID and compression type. * - * Note: wimlib_export_image() can provide similar functionality to - * wimlib_join(), since it is possible to export all images from a split WIM. - * Actually, wimlib_join() currently calls wimlib_export_image internally. + * Note: wimlib is generalized enough that this function is not actually needed + * to join a split WIM; instead, you could open the first part of the split WIM, + * then reference the other parts with wimlib_reference_resource_files(), then + * write the joined WIM using wimlib_write(). However, wimlib_join() provides + * an easy-to-use wrapper around this that has some advantages (e.g. extra + * sanity checks). */ extern int wimlib_join(const wimlib_tchar * const *swms, @@ -2222,61 +2912,10 @@ wimlib_join(const wimlib_tchar * const *swms, int wim_write_flags, wimlib_progress_func_t progress_func); -/** - * Compress a chunk of a WIM resource using LZX compression. - * - * This function is exported for convenience only and should only be used by - * library clients looking to make use of wimlib's compression code for another - * purpose. - * - * @param chunk - * Uncompressed data of the chunk. - * @param chunk_size - * Size of the uncompressed chunk, in bytes. - * @param out - * Pointer to output buffer of size at least (@p chunk_size - 1) bytes. - * - * @return - * The size of the compressed data written to @p out in bytes, or 0 if the - * data could not be compressed to (@p chunk_size - 1) bytes or fewer. - * - * As a special requirement, the compression code is optimized for the WIM - * format and therefore requires (@p chunk_size <= 32768). - */ -extern unsigned -wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out); /** - * Decompresses a block of LZX-compressed data as used in the WIM file format. - * - * Note that this will NOT work unmodified for LZX as used in the cabinet - * format, which is not the same as in the WIM format! + * @ingroup G_mounting_wim_images * - * This function is exported for convenience only and should only be used by - * library clients looking to make use of wimlib's compression code for another - * purpose. - * - * @param compressed_data - * Pointer to the compressed data. - * - * @param compressed_len - * Length of the compressed data, in bytes. - * - * @param uncompressed_data - * Pointer to the buffer into which to write the uncompressed data. - * - * @param uncompressed_len - * Length of the uncompressed data. It must be 32768 bytes or less. - * - * @return - * 0 on success; non-zero on failure. - */ -extern int -wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); - - -/** * 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 @@ -2308,17 +2947,7 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * @param dir * The path to an existing empty directory to mount the image on. * @param mount_flags - * Bitwise OR of the flags prefixed with WIMLIB_MOUNT_FLAG. - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @p num_additional_swms is 0. The pointers do not - * need to be in any particular order, but they must include all parts of - * the split WIM other than the first part, which must be provided in the - * @p wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @p additional_swms array. - * This number should be one less than the total number of parts in the - * split WIM. Set to 0 if the WIM is a standalone WIM. + * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. * @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 @@ -2332,14 +2961,10 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * 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. - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Could not decompress the metadata resource for @p image in @p wim. * @retval ::WIMLIB_ERR_FUSE * A non-zero status 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_METADATA_RESOURCE - * The metadata resource for @p image is invalid. * @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 @@ -2347,43 +2972,37 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * @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_NOMEM - * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_NOTDIR * Could not determine the current working directory. - * @retval ::WIMLIB_ERR_READ - * Failed to read data from the WIM file associated with @p wim. * @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_SPLIT_INVALID - * The WIM is a split WIM, but the parts specified do not form a complete - * split WIM because they do not include all the parts of the original WIM, - * there are duplicate parts, or not all the parts have the same GUID and - * compression type. * @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. - * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Unexpected end-of-file occurred while reading data from the WIM file - * associated with @p wim. * @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. + * + * 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. */ extern int wimlib_mount_image(WIMStruct *wim, int image, const wimlib_tchar *dir, int mount_flags, - WIMStruct **additional_swms, - unsigned num_additional_swms, const wimlib_tchar *staging_dir); /** + * @ingroup G_creating_and_opening_wims + * * Opens a WIM file and creates a ::WIMStruct for it. * * @param wim_file @@ -2416,10 +3035,11 @@ wimlib_mount_image(WIMStruct *wim, * chunk of the WIM does not match the corresponding message digest given * in the integrity table. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * Resources in @p wim_file are compressed, but the chunk size is not 32768. + * Resources in @p wim_file are compressed, but the chunk size was invalid + * for the WIM's 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. + * but the header flag for a recognized compression type is not set. * @retval ::WIMLIB_ERR_INVALID_HEADER * The header of @p wim_file was otherwise invalid. * @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE @@ -2427,11 +3047,12 @@ wimlib_mount_image(WIMStruct *wim, * wim_file contains an integrity table, but the integrity table is * 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 for 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 + * specified in @p open_flags. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocated needed memory. * @retval ::WIMLIB_ERR_NOT_A_WIM_FILE @@ -2440,14 +3061,13 @@ wimlib_mount_image(WIMStruct *wim, * Failed to open the file @p wim_file for reading. * @retval ::WIMLIB_ERR_READ * Failed to read data from @p wim_file. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @p wim_file is a split WIM, but ::WIMLIB_OPEN_FLAG_SPLIT_OK was not - * specified in @p open_flags. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE * Unexpected end-of-file while reading data from @p wim_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 @@ -2462,6 +3082,8 @@ wimlib_open_wim(const wimlib_tchar *wim_file, wimlib_progress_func_t progress_func); /** + * @ingroup G_writing_and_overwriting_wims + * * Overwrites the file that the WIM was originally read from, with changes made. * This only makes sense for ::WIMStruct's obtained from wimlib_open_wim() * rather than wimlib_create_new_wim(). @@ -2515,8 +3137,9 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * 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 any value - * returned by wimlib_write() as well as the following error codes: + * @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: + * * @retval ::WIMLIB_ERR_ALREADY_LOCKED * The WIM was going to be modified in-place (with no temporary file), but * an exclusive advisory lock on the on-disk WIM file could not be acquired @@ -2538,6 +3161,8 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads, wimlib_progress_func_t progress_func); /** + * @ingroup G_wim_information + * * Prints information about one image, or all images, contained in a WIM. * * @param wim @@ -2555,6 +3180,8 @@ extern void wimlib_print_available_images(const WIMStruct *wim, int image); /** + * @ingroup G_wim_information + * * Deprecated in favor of wimlib_get_wim_info(), which provides the information * in a way that can be accessed programatically. */ @@ -2562,18 +3189,176 @@ extern void wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; /** - * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the - * information in a way that can be accessed programatically. + * @ingroup G_nonstandalone_wims + * + * Reference resources from other WIM files or split WIM parts. This function + * can be used on WIMs that are not standalone, such as split or "delta" WIMs, + * to load needed resources (that is, "streams" keyed by SHA1 message digest) + * from other files, before calling a function such as wimlib_extract_image() + * that requires the resources to be present. + * + * @param wim + * The ::WIMStruct for a WIM that contains metadata resources, but is not + * necessarily "standalone". In the case of split WIMs, this should be the + * first part, since only the first part contains the metadata resources. + * In the case of delta WIMs, this should be the delta WIM rather than the + * WIM on which it is based. + * @param resource_wimfiles_or_globs + * Array of paths to WIM files and/or split WIM parts to reference. + * Alternatively, when ::WIMLIB_REF_FLAG_GLOB_ENABLE is specified in @p + * ref_flags, these are treated as globs rather than literal paths. That + * is, using this function you can specify zero or more globs, each of + * which expands to one or more literal paths. + * @param count + * Number of entries in @p resource_wimfiles_or_globs. + * @param ref_flags + * Bitwise OR of ::WIMLIB_REF_FLAG_GLOB_ENABLE and/or + * ::WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH. + * @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. + * + * @retval ::WIMLIB_ERR_GLOB_HAD_NO_MATCHES + * One of the specified globs did not match any paths (only with both + * ::WIMLIB_REF_FLAG_GLOB_ENABLE and ::WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH + * specified in @p ref_flags). + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory. + * @retval ::WIMLIB_ERR_READ + * I/O or permissions error while processing a file glob. + * + * This function can additionally return most values that can be returned by + * wimlib_open_wim(). */ extern int -wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; +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); /** + * @ingroup G_nonstandalone_wims + * + * Similar to wimlib_reference_resource_files(), but operates at a lower level + * where the caller must open the ::WIMStruct for each referenced file itself. + * + * @param wim + * The ::WIMStruct for a WIM that contains metadata resources, but is not + * necessarily "standalone". In the case of split WIMs, this should be the + * first part, since only the first part contains the metadata resources. + * @param resource_wims + * Array of pointers to the ::WIMStruct's for additional resource WIMs or + * split WIM parts to reference. + * @param num_resource_wims + * Number of entries in @p resource_wims. + * @param ref_flags + * Currently ignored (set to 0). + * + * @return 0 on success; nonzero on error. On success, the ::WIMStruct's of the + * @p resource_wims are referenced internally by @p wim and must not be freed + * with wimlib_free() or overwritten with wimlib_overwrite() until @p wim has + * been freed with wimlib_free(), or immediately before freeing @p wim with + * wimlib_free(). + * + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p wim was @c NULL, or @p num_resource_wims was nonzero but @p + * resource_wims was @c NULL, or an entry in @p resource_wims was @p NULL. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory. + */ +extern int +wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, + unsigned num_resource_wims, int ref_flags); + +/** + * @ingroup G_modifying_wims + * + * Declares that a newly added image is mostly the same as a prior image, but + * captured at a later point in time, possibly with some modifications in the + * intervening time. This is designed to be used in incremental backups of the + * same filesystem or directory tree. + * + * This function compares the metadata of the directory tree of the newly added + * image against that of the old image. Any files that are present in both the + * newly added image and the old image and have timestamps that indicate they + * haven't been modified are deemed not to have been modified and have their + * SHA1 message digest copied from the old image. Because of this and because + * WIM uses single-instance streams, such files need not be read from the + * filesystem when the WIM is being written or overwritten. Note that these + * unchanged files will still be "archived" and will be logically present in the + * new image; the optimization is that they don't need to actually be read from + * the filesystem because the WIM already contains them. + * + * This function is provided to optimize incremental backups. The resulting WIM + * file will still be the same regardless of whether this function is called. + * (This is, however, assuming that timestamps have not been manipulated or + * unmaintained as to trick this function into thinking a file has not been + * modified when really it has. To partly guard against such cases, other + * metadata such as file sizes will be checked as well.) + * + * This function must be called after adding the new image (e.g. with + * wimlib_add_image()), but before writing the updated WIM file (e.g. with + * wimlib_overwrite()). + * + * @param wim + * Pointer to the ::WIMStruct for a WIM. + * @param new_image + * 1-based index in the WIM of the newly added image. This image can have + * been added with wimlib_add_image() or wimlib_add_image_multisource(), or + * wimlib_add_empty_image() followed by wimlib_update_image(). + * @param template_wim + * The ::WIMStruct for the WIM containing the template image. This can be + * the same as @p wim, or it can be a different ::WIMStruct. + * @param template_image + * 1-based index in the WIM of a template image that reflects a prior state + * 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. + * + * @retval ::WIMLIB_ERR_INVALID_IMAGE + * @p new_image and/or @p template_image were not a valid image indices in + * the WIM. + * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND + * The specified ::WIMStruct did not actually contain the metadata resource + * for the new or template image; for example, it was a non-first part of a + * split WIM. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate needed memory. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p new_image was equal to @p template_image, or @p new_image specified + * an image that had not been modified since opening the WIM. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for the template image. + */ +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); + +/** + * @ingroup G_wim_information + * * Translates a string specifying the name or number of an image in the WIM into * the number of the image. The images are numbered starting at 1. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct for a WIM. * @param image_name_or_num * A string specifying the name or number of an image in the WIM. If it * parses to a positive integer, this integer is taken to specify the @@ -2599,12 +3384,12 @@ wimlib_resolve_image(WIMStruct *wim, const wimlib_tchar *image_name_or_num); /** + * @ingroup G_modifying_wims + * * Changes the description of an image in the WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM; however, you should set the same - * description on all parts of a split WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image * The number of the image for which to change the description. * @param description @@ -2626,10 +3411,85 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, const wimlib_tchar *description); /** + * @ingroup G_writing_and_overwriting_wims + * + * Set the compression chunk size of a WIM to use in subsequent calls to + * wimlib_write() or wimlib_overwrite(). + * + * For compatibility reasons, using this function is not generally recommended. + * See the documentation for the @c --chunk-size option of wimlib-imagex + * capture for more information. + * + * 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 chunk_size + * The chunk size (in bytes) to set. The valid chunk sizes are dependent + * on the compression format; see the documentation for the @c --chunk-size + * option of wimlib-imagex capture for more information. As a + * special case, if @p chunk_size is specified as 0, the chunk size is set + * to the default for the currently selected output compression type. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE + * @p chunk_size is not a supported chunk size for the currently selected + * output compression type. + */ +extern int +wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing + * packed streams. + */ +extern int +wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Set the compression type of a WIM to use in subsequent calls to + * wimlib_write() or wimlib_overwrite(). + * + * @param wim + * ::WIMStruct for a WIM. + * @param ctype + * The compression type to set (one of ::wimlib_compression_type). If this + * compression type is incompatible with the current output chunk size + * (either the default or as set with wimlib_set_output_chunk_size()), the + * output chunk size is reset to the default for that compression type. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype did not specify a valid compression type. + */ +extern int +wimlib_set_output_compression_type(WIMStruct *wim, int ctype); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Similar to wimlib_set_output_compression_type(), but set the compression type + * for writing packed streams (solid blocks). + */ +extern int +wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype); + +/** + * @ingroup G_modifying_wims + * * Set basic information about a WIM. * * @param wim - * A WIMStruct for a standalone WIM file. + * Pointer to the ::WIMStruct for a WIM. * @param info * A struct ::wimlib_wim_info that contains the information to set. Only * the information explicitly specified in the @p which flags need be @@ -2656,13 +3516,13 @@ wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, int which); /** + * @ingroup G_modifying_wims + * * Changes what is written in the \ element in the WIM XML data * (something like "Core" or "Ultimate") * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM; however, you should set the same - * \ element on all parts of a split WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image * The number of the image for which to change the description. * @param flags @@ -2682,12 +3542,12 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** + * @ingroup G_modifying_wims + * * Changes the name of an image in the WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM; however, you should set the same - * name on all parts of a split WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image * The number of the image for which to change the name. * @param name @@ -2706,10 +3566,12 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); * @p wim is considered read-only because of any of the reasons mentioned * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. */ -extern int wimlib_set_image_name(WIMStruct *wim, int image, - const wimlib_tchar *name); +extern int +wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); /** + * @ingroup G_general + * * Set the functions that wimlib uses to allocate and free memory. * * These settings are global and not per-WIM. @@ -2732,10 +3594,7 @@ extern int wimlib_set_image_name(WIMStruct *wim, int image, * A function equivalent to @c realloc() that wimlib will use to reallocate * memory. If @c NULL, the free function is set back to the default @c * realloc() from the C library. - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_UNSUPPORTED - * wimlib was compiled with the @c --without-custom-memory-allocator flag, - * so custom memory allocators are unsupported. + * @return 0 */ extern int wimlib_set_memory_allocator(void *(*malloc_func)(size_t), @@ -2743,6 +3602,8 @@ wimlib_set_memory_allocator(void *(*malloc_func)(size_t), void *(*realloc_func)(void *, size_t)); /** + * @ingroup G_general + * * Sets whether wimlib is to print error messages to @c stderr when a function * fails. These error messages may provide information that cannot be * determined only from the error code that is returned. Not every error will @@ -2768,11 +3629,12 @@ extern int wimlib_set_print_errors(bool show_messages); /** + * @ingroup G_nonstandalone_wims + * * Splits a WIM into multiple parts. * * @param wim - * The ::WIMStruct for the WIM to split. It must be a standalone, one-part - * WIM. + * The ::WIMStruct for the WIM to split. * @param swm_name * Name of the SWM file to create. This will be the name of the first * part. The other parts will have the same name with 2, 3, 4, ..., etc. @@ -2797,8 +3659,6 @@ wimlib_set_print_errors(bool show_messages); * codes that can be returned by wimlib_write() as well as the following error * codes: * - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @p wim was not part 1 of a stand-alone WIM. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p swm_name was not a nonempty string, or @p part_size was 0. * @@ -2815,14 +3675,16 @@ wimlib_split(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @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 thread calling this function communicates with the - * thread that is managing the mounted WIM image. This function blocks until it + * 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. @@ -2882,6 +3744,8 @@ wimlib_unmount_image(const wimlib_tchar *dir, wimlib_progress_func_t progress_func); /** + * @ingroup G_modifying_wims + * * Update a WIM image by adding, deleting, and/or renaming files or directories. * * @param wim @@ -2900,12 +3764,10 @@ wimlib_unmount_image(const wimlib_tchar *dir, * 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_DECOMPRESSION - * Failed to decompress the metadata resource from @p image in @p wim. * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG * The capture configuration structure specified for an add command was * invalid. @@ -2926,10 +3788,6 @@ wimlib_unmount_image(const wimlib_tchar *dir, * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA * (Windows only): While executing an add command, tried to capture a * reparse point with invalid data. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for @p image in @p wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for image @p image in @p wim is invalid. * @retval ::WIMLIB_ERR_IS_DIRECTORY * A delete command without ::WIMLIB_DELETE_FLAG_RECURSIVE specified was * for a WIM path that corresponded to a directory; or, a rename command @@ -2956,18 +3814,14 @@ wimlib_unmount_image(const wimlib_tchar *dir, * WIM path that did not exist; or, a rename command attempted to rename a * file that does not exist. * @retval ::WIMLIB_ERR_READ - * Failed to read the metadata resource for @p image in @p wim; or, while - * executing an add command, failed to read data from a file or directory - * to be captured. + * While executing an add command, failed to read data from a file or + * directory to be captured. * @retval ::WIMLIB_ERR_READLINK * While executing an add command, failed to read the target of a symbolic * link or junction point. * @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED * (Windows only) Failed to perform a reparse point fixup because of * problems with the data of a reparse point. - * @retval ::WIMLIB_ERR_SPECIAL_FILE - * While executing an add command, attempted to capture a file that was not - * a supported file type (e.g. a device file). * @retval ::WIMLIB_ERR_STAT * While executing an add command, failed to get attributes for a file or * directory. @@ -2977,10 +3831,22 @@ wimlib_unmount_image(const wimlib_tchar *dir, * or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA * or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @p * add_flags for an update command. + * @retval ::WIMLIB_ERR_UNSUPPORTED_FILE + * While executing an add command, attempted to capture a file that was not + * a supported file type (e.g. a device file). Only if + * ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the add_flags + * for an update command. * @retval ::WIMLIB_ERR_WIM_IS_READONLY * The WIM file is considered read-only because of any of the reasons * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS * flag. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be updated. */ extern int wimlib_update_image(WIMStruct *wim, @@ -2991,20 +3857,29 @@ wimlib_update_image(WIMStruct *wim, wimlib_progress_func_t progress_func); /** - * Writes a standalone WIM to a file. + * @ingroup G_writing_and_overwriting_wims + * + * Writes a WIM to a file. * * This brings in resources from any external locations, such as directory trees * or NTFS volumes scanned with wimlib_add_image(), or other WIM files via * wimlib_export_image(), and incorporates them into a new on-disk WIM file. * + * By default, the new WIM file is written as stand-alone. Using the + * ::WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS flag, a "delta" WIM can be written + * instead. However, this function cannot directly write a "split" WIM; use + * wimlib_split() for that. + * * @param wim * Pointer to the ::WIMStruct for a WIM. There may have been in-memory * changes made to it, which are then reflected in the output file. * @param path * The path to the file to write the WIM to. * @param image - * The 1-based index of the image inside the WIM to write. Use - * ::WIMLIB_ALL_IMAGES to include all images. + * Normally, specify ::WIMLIB_ALL_IMAGES here. This indicates that all + * images are to be included in the new on-disk WIM file. If for some + * reason you only want to include a single image, specify the index of + * that image instead. * @param write_flags * Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG. * @param num_threads @@ -3024,8 +3899,6 @@ wimlib_update_image(WIMStruct *wim, * * @return 0 on success; nonzero on error. * - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress a metadata or file resource in @p wim. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image does not specify a single existing image in @p wim, and is not * ::WIMLIB_ALL_IMAGES. @@ -3035,8 +3908,6 @@ wimlib_update_image(WIMStruct *wim, * message digest check. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p path was @c NULL. - * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE - * The metadata resource for @p image in @p wim is invalid. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_OPEN @@ -3048,10 +3919,21 @@ wimlib_update_image(WIMStruct *wim, * with @p wim, or some file resources in @p wim refer to files in the * outside filesystem, and a read error occurred when reading one of these * files. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @p wim is part of a split WIM, not a standalone WIM. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * A stream that needed to be written could not be found in the stream + * lookup table of @p wim. This error can occur if, for example, @p wim is + * part of a split WIM but needed resources from the other split WIM parts + * were not referenced with wimlib_reference_resources() or + * wimlib_reference_resource_files() before the call to wimlib_write(). * @retval ::WIMLIB_ERR_WRITE * An error occurred when trying to write data to the new WIM file. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be written. */ extern int wimlib_write(WIMStruct *wim, @@ -3062,6 +3944,8 @@ wimlib_write(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @ingroup G_writing_and_overwriting_wims + * * Since wimlib v1.5.0: Same as wimlib_write(), but write the WIM directly to a * file descriptor, which need not be seekable if the write is done in a special * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p @@ -3088,18 +3972,366 @@ wimlib_write_to_fd(WIMStruct *wim, wimlib_progress_func_t progress_func); /** - * This function is equivalent to wimlib_lzx_compress(), but instead compresses - * the data using "XPRESS" compression. + * @defgroup G_compression Compression and decompression functions + * + * @brief Functions for LZX, XPRESS, and LZMS compression and decompression, + * exported for convenience only, as they are already used by wimlib internally + * when appropriate. + * + * These functions can be used for general-purpose lossless data compression, + * but some limitations apply; for example, none of the compressors or + * decompressors currently support sliding windows, and there also exist + * slightly different variants of these formats that are not supported + * unmodified. + * + * @{ */ -extern unsigned -wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out); + +/** Header for compression parameters to pass to wimlib_create_compressor() or + * wimlib_set_default_compressor_params(). */ +struct wimlib_compressor_params_header { + /** Size of the parameters, in bytes. */ + uint32_t size; +}; + +/** Header for decompression parameters to pass to wimlib_create_decompressor() + * or wimlib_set_default_decompressor_params() */ +struct wimlib_decompressor_params_header { + /** Size of the parameters, in bytes. */ + uint32_t size; +}; + +/** LZX compression parameters that can optionally be passed to + * wimlib_create_compressor() with the compression type + * ::WIMLIB_COMPRESSION_TYPE_LZX. */ +struct wimlib_lzx_compressor_params { + /** hdr.size Must be set to the size of this structure, in bytes. */ + struct wimlib_compressor_params_header hdr; + + /** Relatively fast LZX compression algorithm with a decent compression + * ratio; the suggested default. */ +#define WIMLIB_LZX_ALGORITHM_FAST 0 + + /** Slower LZX compression algorithm that provides a better compression + * ratio. */ +#define WIMLIB_LZX_ALGORITHM_SLOW 1 + + /** Algorithm to use to perform the compression: either + * ::WIMLIB_LZX_ALGORITHM_FAST or ::WIMLIB_LZX_ALGORITHM_SLOW. The + * format is still LZX; this refers to the method the code will use to + * perform LZX-compatible compression. */ + uint32_t algorithm : 3; + + /** If set to 1, the default parameters for the specified algorithm are + * used rather than the ones specified in the following union. */ + uint32_t use_defaults : 1; + + union { + /** Parameters for the fast algorithm. */ + struct wimlib_lzx_fast_params { + uint32_t fast_reserved1[10]; + } fast; + + /** Parameters for the slow algorithm. */ + struct wimlib_lzx_slow_params { + /** If set to 1, the compressor can output length 2 + * matches. If set 0, the compressor only outputs + * matches of length 3 or greater. Suggested value: 1 + */ + uint32_t use_len2_matches : 1; + + uint32_t slow_reserved1 : 31; + + /** Matches with length (in bytes) greater than or equal + * to this value are immediately taken without spending + * time on minimum-cost measurements. Suggested value: + * 32. */ + uint32_t nice_match_length; + + /** Number of passes to compute a match/literal sequence + * for each LZX block. This is for an iterative + * algorithm that attempts to minimize the cost of the + * match/literal sequence by using a cost model provided + * by the previous iteration. Must be at least 1. + * Suggested value: 2. */ + uint32_t num_optim_passes; + + /** Reserved; set to 0. */ + uint32_t slow_reserved_blocksplit; + + /** Maximum depth to search for matches at each + * position. Suggested value: 50. */ + uint32_t max_search_depth; + + /** Maximum number of potentially good matches to + * consider for each position. Suggested value: 3. */ + uint32_t max_matches_per_pos; + + uint32_t slow_reserved2[2]; + + /** Assumed cost of a main symbol with zero frequency. + * Must be at least 1 and no more than 16. Suggested + * value: 15. */ + uint8_t main_nostat_cost; + + /** Assumed cost of a length symbol with zero frequency. + * Must be at least 1 and no more than 16. Suggested + * value: 15. */ + uint8_t len_nostat_cost; + + /** Assumed cost of an aligned symbol with zero + * frequency. Must be at least 1 and no more than 8. + * Suggested value: 7. */ + uint8_t aligned_nostat_cost; + + uint8_t slow_reserved3[5]; + } slow; + } alg_params; +}; + +/** LZMS compression parameters that can optionally be passed to + * wimlib_create_compressor() with the compression type + * ::WIMLIB_COMPRESSION_TYPE_LZMS. */ +struct wimlib_lzms_compressor_params { + /** hdr.size Must be set to the size of this structure, in bytes. */ + struct wimlib_compressor_params_header hdr; + + /** Minimum match length to output. This must be at least 2. Suggested + * value: 2 */ + uint32_t min_match_length; + + /** Maximum match length to output. This must be at least @p + * min_match_length. Suggested value: @p UINT32_MAX. */ + uint32_t max_match_length; + + /** Matches with length (in bytes) greater than or equal to this value + * are immediately taken without spending time on minimum-cost + * measurements. The minimum of @p max_match_length and @p + * nice_match_length may not exceed 65536. Suggested value: 32. */ + uint32_t nice_match_length; + + /** Maximum depth to search for matches at each position. Suggested + * value: 50. */ + uint32_t max_search_depth; + + /** Maximum number of potentially good matches to consider at each + * position. Suggested value: 3. */ + uint32_t max_matches_per_pos; + + /** Length of the array for the near-optimal LZ parsing algorithm. This + * must be at least 1. Suggested value: 1024. */ + uint32_t optim_array_length; + + uint64_t reserved2[4]; +}; + +/** Opaque compressor handle. */ +struct wimlib_compressor; + +/** Opaque decompressor handle. */ +struct wimlib_decompressor; /** - * This function is equivalent to wimlib_lzx_decompress(), but instead assumes - * the data is compressed using "XPRESS" compression. + * Set the default compression parameters for the specified compression type. + * This will affect both explicit and wimlib-internal calls to + * wimlib_create_compressor(). + * + * @param ctype + * Compression type for which to set the default compression parameters. + * @param params + * Compression-type specific parameters. This may be @c NULL, in which + * case the "default default" parameters are restored. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p params were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Not enough memory to duplicate the parameters (perhaps @c params->size + * was invalid). + */ +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. + * + * @param ctype + * Compression type for which to create the compressor. + * @param max_block_size + * Maximum block size to support. The exact meaning and allowed values for + * this parameter depend on the compression type, but it at least specifies + * the maximum allowed value for @p uncompressed_size to wimlib_compress(). + * @param extra_params + * An optional pointer to extra compressor parameters for the specified + * compression type. For LZX, a pointer to ::wimlib_lzx_compressor_params + * may be specified here. If left @c NULL, the default parameters are + * used. + * @param compressor_ret + * A location into which to return the pointer to the allocated compressor, + * which can be used for any number of calls to wimlib_compress() before + * being freed with wimlib_free_compressor(). + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The compression parameters were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Insufficient memory to allocate the compressor. + */ +extern int +wimlib_create_compressor(enum wimlib_compression_type ctype, + size_t max_block_size, + const struct wimlib_compressor_params_header *extra_params, + struct wimlib_compressor **compressor_ret); + +/** + * Losslessly compress a block of data using a compressor previously created + * with wimlib_create_compressor(). + * + * @param uncompressed_data + * Buffer containing the data to compress. + * @param uncompressed_size + * Size, in bytes, of the data to compress. + * @param compressed_data + * Buffer into which to write the compressed data. + * @param compressed_size_avail + * Number of bytes available in @p compressed_data. + * @param compressor + * A compressor previously allocated with wimlib_create_compressor(). + * + * @return + * The size of the compressed data, in bytes, or 0 if the input data could + * not be compressed to @p compressed_size_avail or fewer bytes. + */ +extern size_t +wimlib_compress(const void *uncompressed_data, size_t uncompressed_size, + void *compressed_data, size_t compressed_size_avail, + struct wimlib_compressor *compressor); + +/** + * Free a compressor previously allocated with wimlib_create_compressor(). + * + * @param compressor + * The compressor to free. + */ +extern void +wimlib_free_compressor(struct wimlib_compressor *compressor); + +/** + * Set the default decompression parameters for the specified compression type. + * This will affect both explicit and wimlib-internal calls to + * wimlib_create_decompressor(). + * + * @param ctype + * Compression type for which to set the default decompression parameters. + * @param params + * Compression-type specific parameters. This may be @c NULL, in which + * case the "default default" parameters are restored. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_NOMEM + * Not enough memory to duplicate the parameters (perhaps @c params->size + * was invalid). + */ +extern int +wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype, + const struct wimlib_decompressor_params_header *params); + +/** + * Allocate a decompressor for the specified compression type using the + * specified parameters. + * + * @param ctype + * Compression type for which to create the decompressor. + * @param max_block_size + * Maximum block size to support. The exact meaning and allowed values for + * this parameter depend on the compression type, but it at least specifies + * the maximum allowed value for @p uncompressed_size to + * wimlib_decompress(). + * @param extra_params + * An optional pointer to extra decompressor parameters for the specified + * compression type. If @c NULL, the default parameters are used. + * @param decompressor_ret + * A location into which to return the pointer to the allocated + * decompressor, which can be used for any number of calls to + * wimlib_decompress() before being freed with wimlib_free_decompressor(). + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The decompression parameters were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Insufficient memory to allocate the decompressor. + */ +extern int +wimlib_create_decompressor(enum wimlib_compression_type ctype, + size_t max_block_size, + const struct wimlib_decompressor_params_header *extra_params, + struct wimlib_decompressor **decompressor_ret); + +/** + * Decompress a block of data using a decompressor previously created with + * wimlib_create_decompressor(). + * + * @param compressed_data + * Buffer containing the data to decompress. + * @param compressed_size + * Size, in bytes, of the data to decompress. + * @param uncompressed_data + * Buffer into which to write the uncompressed data. + * @param uncompressed_size + * Size, in bytes, of the data when uncompressed. + * @param decompressor + * A decompressor previously allocated with wimlib_create_decompressor(). + * + * @return 0 on success; nonzero on error. */ extern int -wimlib_xpress_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); +wimlib_decompress(const void *compressed_data, size_t compressed_size, + void *uncompressed_data, size_t uncompressed_size, + struct wimlib_decompressor *decompressor); + +/** + * Free a decompressor previously allocated with wimlib_create_decompressor(). + * + * @param decompressor + * The decompressor to free. + */ +extern void +wimlib_free_decompressor(struct wimlib_decompressor *decompressor); + + +/** + * @} + */ + + +#ifdef __cplusplus +} +#endif #endif /* _WIMLIB_H */