X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=7bab4a34170e1a36ce2505cb29e82dabadc78147;hp=c1c00e42dc66d70104128d6e4c441b1cc2c313dd;hb=2b4f92cc80af257566c00e62fd3f0a7e3607416b;hpb=28d3d79a1894375e457237097bc80f0d92746018 diff --git a/include/wimlib.h b/include/wimlib.h index c1c00e42..7bab4a34 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -1,11 +1,12 @@ -/* - * 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. */ /* @@ -27,113 +28,143 @@ * 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.4.1, a C + * This is the documentation for the library interface of wimlib 1.5.2, 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. + * 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 systems, it should be easy to + * 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 + * + * 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. * - * 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. - * - * 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, - * 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, 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, 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. + * @subsection subsec_non_standalone_wims Non-standalone WIMs * - * 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. + * See @ref G_nonstandalone_wims. * - * 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(). + * @subsection subsec_pipable_wims Pipable WIMs * - * 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. + * 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 + * pipe, and wimlib_extract_image_from_pipe() can be used to apply an image from + * a pipable WIM. wimlib can also transparently open and operate on pipable WIM + * s using a seekable file descriptor using the regular function calls (e.g. + * wimlib_open_wim(), wimlib_extract_image()). * - * 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. - * race conditions with one-time allocations of memory. * - wimlib_mount_image(), while it can be used to mount multiple WIMs * concurrently in the same process, will daemonize the entire process when it * does so for the first time. This includes changing the working directory * to the root directory. * - * \section encodings Locales and character encodings - * - * To support Windows as well as UNIX, 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, 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. @@ -145,8 +176,164 @@ * - 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, as usual, by a ::WIMStruct). This normally extracts the image + * to a directory, but when supported by the build of the library there is also + * a special NTFS volume extraction mode (entered when + * ::WIMLIB_EXTRACT_FLAG_NTFS is specified) that allows extracting a WIM image + * directly to an unmounted NTFS volume. Various other flags allow further + * customization of image extraction. + * + * Another function, wimlib_extract_files(), is also provided. It can extract + * certain files or directories from a WIM image, instead of a full image. + * + * A third function, wimlib_extract_image_from_pipe(), allows an image to be + * extracted from a pipable WIM sent over a pipe; see @ref subsec_pipable_wims. + * + * Note that some details of how image extraction/application works are + * documented more fully in the manual pages for wimlib-imagex apply and + * wimlib-imagex extract. + */ + +/** @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_files(). 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. + */ + +/** @defgroup G_compression Compression and decompression functions + * + * @brief Functions for LZX and XPRESS compression and decompression, exported + * for convenience only. These functions normally do not need to be used. */ #ifndef _WIMLIB_H @@ -156,15 +343,27 @@ #include #include #include +#include + +/** @ingroup G_general + * @{ */ -/** Major version of the library (for example, the 1 in 1.2.5). */ +/** 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 4 +#define WIMLIB_MINOR_VERSION 5 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 1 +#define WIMLIB_PATCH_VERSION 2 + +#ifdef __cplusplus +extern "C" { +#endif + +/** @} */ +/** @ingroup G_general + * @{ */ /** * Opaque structure that represents a WIM file. This is an in-memory structure @@ -178,6 +377,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; @@ -187,7 +388,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 @@ -200,6 +401,15 @@ typedef char wimlib_tchar; # define WIMLIB_WIM_PATH_SEPARATOR '/' # define WIMLIB_WIM_PATH_SEPARATOR_STRING "/" #endif + +#ifdef __GNUC__ +# define _wimlib_deprecated __attribute__((deprecated)) +#else +# define _wimlib_deprecated +#endif + +#define WIMLIB_GUID_LEN 16 + /** * Specifies the compression type of a WIM file. */ @@ -217,121 +427,125 @@ enum wimlib_compression_type { WIMLIB_COMPRESSION_TYPE_XPRESS = 2, }; +/** @} */ +/** @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. @a info will point to + /** A WIM image is about to be extracted. @p info will point to * ::wimlib_progress_info.extract. */ 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. @a info will point to + * about to be extracted. @p info will point to * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, /** The directory structure of the WIM image is about to be extracted. - * @a info will point to ::wimlib_progress_info.extract. */ + * @p info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN, /** The directory structure of the WIM image has been successfully - * extracted. @a info will point to ::wimlib_progress_info.extract. */ + * extracted. @p info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - /** The WIM image's files resources are currently being extracted. @a + /** The WIM image's files resources are currently being extracted. @p * info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, - /** A file or directory is being extracted. @a info will point to - * ::wimlib_progress_info.extract, and the @a cur_path member will be - * valid. */ - WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY, + /** 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. @a info will point to + * timestamps are about to be applied. @p info will point to * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS, - /** A WIM image has been successfully extracted. @a info will point to + /** A WIM image has been successfully extracted. @p info will point to * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, /** A file or directory tree within a WIM image (not the full image) has - * been successfully extracted. @a info will point to + * been successfully extracted. @p info will point to * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, /** The directory or NTFS volume is about to be scanned to build a tree - * of WIM dentries in-memory. @a info will point to + * of WIM dentries in-memory. @p info will point to * ::wimlib_progress_info.scan. */ WIMLIB_PROGRESS_MSG_SCAN_BEGIN, - /** A directory or file is being scanned. @a info will point to - * ::wimlib_progress_info.scan, and its @a cur_path member will be + /** A directory or file is being scanned. @p info will point to + * ::wimlib_progress_info.scan, and its @p cur_path member will be * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE * is passed to wimlib_add_image(). */ WIMLIB_PROGRESS_MSG_SCAN_DENTRY, /** The directory or NTFS volume has been successfully scanned, and a - * tree of WIM dentries has been built in-memory. @a info will point to + * tree of WIM dentries has been built in-memory. @p info will point to * ::wimlib_progress_info.scan. */ WIMLIB_PROGRESS_MSG_SCAN_END, /** * File resources are currently being written to the WIM. - * @a info will point to ::wimlib_progress_info.write_streams. */ + * @p info will point to ::wimlib_progress_info.write_streams. */ WIMLIB_PROGRESS_MSG_WRITE_STREAMS, /** * The metadata resource for each image is about to be written to the - * WIM. @a info will not be valid. */ + * WIM. @p info will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, /** * The metadata resource for each image has successfully been writen to - * the WIM. @a info will not be valid. */ + * the WIM. @p info will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, /** * The temporary file has successfully been renamed to the original WIM * file. Only happens when wimlib_overwrite() is called and the * overwrite is not done in-place. - * @a info will point to ::wimlib_progress_info.rename. */ + * @p info will point to ::wimlib_progress_info.rename. */ WIMLIB_PROGRESS_MSG_RENAME, /** The contents of the WIM are being checked against the integrity * table. Only happens when wimlib_open_wim() is called with the - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. @a info will point to + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. @p info will point to * ::wimlib_progress_info.integrity. */ 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. @a info will point to + * the ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY flag. @p info will point to * ::wimlib_progress_info.integrity. */ WIMLIB_PROGRESS_MSG_CALC_INTEGRITY, - /** A wimlib_join() operation is in progress. @a info will point to - * ::wimlib_progress_info.join. */ - WIMLIB_PROGRESS_MSG_JOIN_STREAMS, + /** Reserved. (Previously used for WIMLIB_PROGRESS_MSG_JOIN_STREAMS, + * but in wimlib v1.5.0 this was removed to simplify the code and now + * you'll get ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages instead.) */ + WIMLIB_PROGRESS_MSG_RESERVED, /** A wimlib_split() operation is in progress, and a new split part is - * about to be started. @a info will point to + * about to be started. @p info will point to * ::wimlib_progress_info.split. */ WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART, /** A wimlib_split() operation is in progress, and a split part has been - * finished. @a 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; @a info will point + * A WIM update command is just about to be executed; @p info will point * to ::wimlib_progress_info.update. */ WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND, /** - * A WIM update command has just been executed; @a info will point to + * A WIM update command has just been executed; @p info will point to * ::wimlib_progress_info.update. */ WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND, @@ -355,20 +569,21 @@ union wimlib_progress_info { * (The actual number of bytes will be less if the data is being * written compressed.) */ uint64_t total_bytes; + /** Number of streams that are going to be written. */ uint64_t total_streams; /** Number of uncompressed bytes that have been written so far. - * Will be 0 initially, and equal to @a total_bytes at the end. + * Will be 0 initially, and equal to @p total_bytes at the end. * */ uint64_t completed_bytes; /** Number of streams that have been written. Will be 0 - * initially, and equal to @a total_streams at the end. */ + * initially, and equal to @p total_streams at the end. */ uint64_t completed_streams; /** Number of threads that are being used to compress resources - * (if applicable). */ + * (if applicable). */ unsigned num_threads; /** The compression type being used to write the streams; either @@ -377,8 +592,13 @@ union wimlib_progress_info { * ::WIMLIB_COMPRESSION_TYPE_LZX. */ int compression_type; - /** Library internal use only. */ - uint64_t _private; + /** Number of split WIM parts from which streams are being + * written (may be 0 if irrelevant). */ + unsigned total_parts; + + /** Number of split WIM parts from which streams have been + * written (may be 0 if irrelevant). */ + unsigned completed_parts; } write_streams; /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and @@ -392,9 +612,19 @@ union wimlib_progress_info { * */ const wimlib_tchar *cur_path; - /** True iff @a cur_path is being excluded from the image - * capture due to the capture configuration file. */ - bool excluded; + enum { + /** File or directory 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. */ + WIMLIB_SCAN_DENTRY_EXCLUDED, + + /** File or directory is being excluded from capture due + * to being unsupported (e.g. an encrypted or device + * file). */ + WIMLIB_SCAN_DENTRY_UNSUPPORTED, + } status; /** Target path in the WIM. Only valid on messages * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and @@ -424,18 +654,16 @@ union wimlib_progress_info { * extracted. */ const wimlib_tchar *target; - /** Current dentry being extracted. (Valid only if message is - * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY.) */ + /** Reserved. */ const wimlib_tchar *cur_path; /** Number of bytes of uncompressed data that will be extracted. * Takes into account hard links (they are not counted for each - * link.) - * */ + * link.) */ uint64_t total_bytes; /** Number of bytes that have been written so far. Will be 0 - * initially, and equal to @a total_bytes at the end. */ + * initially, and equal to @p total_bytes at the end. */ uint64_t completed_bytes; /** Number of streams that will be extracted. This may more or @@ -448,6 +676,19 @@ union wimlib_progress_info { * being extracted. Will be the empty string when extracting a * full image. */ const wimlib_tchar *extract_root_wim_source_path; + + /** Currently only used for + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ + + unsigned part_number; + + /** Currently only used for + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ + unsigned total_parts; + + /** Currently only used for + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ + uint8_t guid[WIMLIB_GUID_LEN]; } extract; /** Valid on messages ::WIMLIB_PROGRESS_MSG_RENAME. */ @@ -485,7 +726,7 @@ union wimlib_progress_info { uint64_t total_bytes; /** Number of bytes that have been SHA1-summed so far. Will be - * 0 initially, and equal @a total_bytes at the end. */ + * 0 initially, and equal @p total_bytes at the end. */ uint64_t completed_bytes; /** Number of chunks that the checksummed region is divided @@ -493,7 +734,7 @@ union wimlib_progress_info { uint32_t total_chunks; /** Number of chunks that have been SHA1-summed so far. Will - * be 0 initially, and equal to @a total_chunks at the end. */ + * be 0 initially, and equal to @p total_chunks at the end. */ uint32_t completed_chunks; /** Size of the chunks used for the integrity calculation. */ @@ -504,25 +745,6 @@ union wimlib_progress_info { const wimlib_tchar *filename; } integrity; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_JOIN_STREAMS. */ - struct wimlib_progress_info_join { - /** Total number of bytes of compressed data contained in all - * the split WIM part's file and metadata resources. */ - uint64_t total_bytes; - - /** Number of bytes that have been copied to the joined WIM so - * far. Will be 0 initially, and equal to @a total_bytes at the - * end. */ - uint64_t completed_bytes; - - /** Number of split WIM parts that have had all their file and - * metadata resources copied over to the joined WIM so far. */ - unsigned completed_parts; - - /** Number of split WIM parts. */ - unsigned total_parts; - } join; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART. */ struct wimlib_progress_info_split { @@ -532,7 +754,7 @@ union wimlib_progress_info { /** Number of bytes of file and metadata resources that have * been copied out of the original WIM so far. Will be 0 - * initially, and equal to @a total_bytes at the end. */ + * initially, and equal to @p total_bytes at the end. */ uint64_t completed_bytes; /** Number of the split WIM part that is about to be started @@ -540,6 +762,9 @@ union wimlib_progress_info { * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */ unsigned cur_part_number; + /** Total number of split WIM parts that are being written. */ + unsigned total_parts; + /** Name of the split WIM part that is about to be started * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */ @@ -559,6 +784,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 { @@ -578,12 +807,12 @@ struct wimlib_capture_source { /** 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 @a pats pointer itself will not. See the man page for + * 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 @a pats array. */ + /** Number of patterns in the @p pats array. */ size_t num_pats; /** Ignored; may be used by the calling code. */ @@ -594,7 +823,7 @@ struct wimlib_pattern_list { * 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 @a + * captured, except if the same path appears in @p * exclusion_exception_pats. */ struct wimlib_pattern_list exclusion_pats; @@ -609,16 +838,293 @@ struct wimlib_capture_config { struct wimlib_pattern_list reserved2; /** Library internal use only. */ - const wimlib_tchar *_prefix; + 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 + * is distinct from basic file permissions; this flag can be set on a WIM file + * that is physically writable. If this flag is set, all further operations to + * modify the WIM will fail, except calling wimlib_overwrite() with + * ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG specified, which is a loophole that + * allows you to set this flag persistently on the underlying WIM file. + */ +#define WIMLIB_CHANGE_READONLY_FLAG 0x00000001 + +/** Set the GUID (globally unique identifier) of the WIM file to the value + * specified in ::wimlib_wim_info.guid of the @p info parameter. */ +#define WIMLIB_CHANGE_GUID 0x00000002 + +/** Change the bootable image of the WIM to the value specified in + * ::wimlib_wim_info.boot_index of the @p info parameter. */ +#define WIMLIB_CHANGE_BOOT_INDEX 0x00000004 + +/** Change the WIM_HDR_FLAG_RP_FIX flag of the WIM file to the value specified + * in ::wimlib_wim_info.has_rpfix of the @p info parameter. This flag generally + * indicates whether an image in the WIM has been captured with reparse-point + * fixups enabled. wimlib also treats this flag as specifying whether to do + * reparse-point fixups by default when capturing or applying WIM images. */ +#define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 + +/** @} */ +/** @ingroup G_wim_information + * @{ */ + +/** General information about a WIM file. */ +struct wimlib_wim_info { + + /** Globally unique identifier for the WIM file. Note: all parts of a + * split WIM should have an identical value in this field. */ + uint8_t guid[WIMLIB_GUID_LEN]; + + /** Number of images in the WIM. */ + uint32_t image_count; + + /** 1-based index of the bootable image in the WIM, or 0 if no image is + * bootable. */ + uint32_t boot_index; + + /** Version of the WIM file. */ + uint32_t wim_version; + + /** Chunk size used for compression. */ + uint32_t chunk_size; + + /** For split WIMs, the 1-based index of this part within the split WIM; + * otherwise 1. */ + uint16_t part_number; + + /** 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 + * method used to compress resources in the WIM. */ + int32_t compression_type; + + /** Size of the WIM file in bytes, excluding the XML data and integrity + * table. */ + uint64_t total_bytes; + + /** 1 if the WIM has an integrity table. Note: if the ::WIMStruct was + * created via wimlib_create_new_wim() rather than wimlib_open_wim(), + * this will always be 0, even if the ::WIMStruct was written to + * somewhere by calling wimlib_write() with the + * ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY flag specified. */ + uint32_t has_integrity_table : 1; + + /** 1 if the ::WIMStruct was created via wimlib_open_wim() rather than + * wimlib_create_new_wim(). */ + uint32_t opened_from_file : 1; -/***************************** - * WIMLIB_ADD_FLAG_* - *****************************/ + /** 1 if the WIM is considered readonly for any reason. */ + uint32_t is_readonly : 1; + + /** 1 if reparse-point fixups are supposedly enabled for one or more + * images in the WIM. */ + uint32_t has_rpfix : 1; + + /** 1 if the WIM is marked as read-only. */ + uint32_t is_marked_readonly : 1; + + /** 1 if the WIM is part of a spanned set. */ + uint32_t spanned : 1; + + uint32_t write_in_progress : 1; + uint32_t metadata_only : 1; + uint32_t resource_only : 1; + + /** 1 if the WIM is pipable (see ::WIMLIB_WRITE_FLAG_PIPABLE). */ + uint32_t pipable : 1; + uint32_t reserved_flags : 22; + uint32_t reserved[9]; +}; + +/** Information about a unique resource in the WIM file. + */ +struct wimlib_resource_entry { + /** Uncompressed size of the resource 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. */ + uint64_t compressed_size; + + /** Offset, in bytes, of this resource from the start of the WIM file. + */ + uint64_t offset; + + /** SHA1 message digest of the resource's uncompressed contents. */ + uint8_t sha1_hash[20]; + + /** Which part number of the split WIM this resource 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. */ + uint32_t reference_count; + + /** 1 if this resource is compressed. */ + uint32_t is_compressed : 1; + + /** 1 if this resource is a metadata resource rather than a file + * resource. */ + uint32_t is_metadata : 1; + + uint32_t is_free : 1; + uint32_t is_spanned : 1; + + /** 1 if this resource 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; + + uint32_t reserved_flags : 27; + uint64_t reserved[4]; +}; + +/** A stream of a file in the WIM. */ +struct wimlib_stream_entry { + /** Name of the stream, or NULL if the stream is unnamed. */ + const wimlib_tchar *stream_name; + /** Location, size, etc. of the stream within the WIM file. */ + struct wimlib_resource_entry resource; + uint64_t reserved[4]; +}; + +/** Structure passed to the wimlib_iterate_dir_tree() callback function. + * Roughly, the information about a "file" in the WIM--- but really a directory + * entry ("dentry") because hard links are allowed. The hard_link_group_id + * field can be used to distinguish actual file inodes. */ +struct wimlib_dir_entry { + /** Name of the file, or NULL if this file is unnamed (only possible for + * the root directory) */ + const wimlib_tchar *filename; + + /** 8.3 DOS name of this file, or NULL if this file has no such name. + * */ + const wimlib_tchar *dos_name; + + /** Full path to this file within the WIM image. */ + const wimlib_tchar *full_path; + + /** Depth of this directory entry, where 0 is the root, 1 is the root's + * children, ..., etc. */ + size_t depth; + + /** Pointer to the security descriptor for this file, in Windows + * SECURITY_DESCRIPTOR_RELATIVE format, or NULL if this file has no + * security descriptor. */ + const char *security_descriptor; + + /** Length of the above security descriptor. */ + size_t security_descriptor_size; + +#define WIMLIB_FILE_ATTRIBUTE_READONLY 0x00000001 +#define WIMLIB_FILE_ATTRIBUTE_HIDDEN 0x00000002 +#define WIMLIB_FILE_ATTRIBUTE_SYSTEM 0x00000004 +#define WIMLIB_FILE_ATTRIBUTE_DIRECTORY 0x00000010 +#define WIMLIB_FILE_ATTRIBUTE_ARCHIVE 0x00000020 +#define WIMLIB_FILE_ATTRIBUTE_DEVICE 0x00000040 +#define WIMLIB_FILE_ATTRIBUTE_NORMAL 0x00000080 +#define WIMLIB_FILE_ATTRIBUTE_TEMPORARY 0x00000100 +#define WIMLIB_FILE_ATTRIBUTE_SPARSE_FILE 0x00000200 +#define WIMLIB_FILE_ATTRIBUTE_REPARSE_POINT 0x00000400 +#define WIMLIB_FILE_ATTRIBUTE_COMPRESSED 0x00000800 +#define WIMLIB_FILE_ATTRIBUTE_OFFLINE 0x00001000 +#define WIMLIB_FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 0x00002000 +#define WIMLIB_FILE_ATTRIBUTE_ENCRYPTED 0x00004000 +#define WIMLIB_FILE_ATTRIBUTE_VIRTUAL 0x00010000 + /** File attributes, such as whether the file is a directory or not. + * These are the "standard" Windows FILE_ATTRIBUTE_* values, although in + * wimlib.h they are defined as WIMLIB_FILE_ATTRIBUTE_* for convenience + * on other platforms. */ + uint32_t attributes; + +#define WIMLIB_REPARSE_TAG_RESERVED_ZERO 0x00000000 +#define WIMLIB_REPARSE_TAG_RESERVED_ONE 0x00000001 +#define WIMLIB_REPARSE_TAG_MOUNT_POINT 0xA0000003 +#define WIMLIB_REPARSE_TAG_HSM 0xC0000004 +#define WIMLIB_REPARSE_TAG_HSM2 0x80000006 +#define WIMLIB_REPARSE_TAG_DRIVER_EXTENDER 0x80000005 +#define WIMLIB_REPARSE_TAG_SIS 0x80000007 +#define WIMLIB_REPARSE_TAG_DFS 0x8000000A +#define WIMLIB_REPARSE_TAG_DFSR 0x80000012 +#define WIMLIB_REPARSE_TAG_FILTER_MANAGER 0x8000000B +#define WIMLIB_REPARSE_TAG_SYMLINK 0xA000000C + /** If the file is a reparse point (FILE_ATTRIBUTE_DIRECTORY set in the + * attributes), this will give the reparse tag. This tells you whether + * the reparse point is a symbolic link, junction point, or some other, + * more unusual kind of reparse point. */ + uint32_t reparse_tag; + + /* Number of (hard) links to this file. */ + uint32_t num_links; + + /** Number of named data streams that this file has. Normally 0. */ + uint32_t num_named_streams; + + /** Roughly, the inode number of this file. However, it may be 0 if + * @p num_links == 1. */ + uint64_t hard_link_group_id; + + /** Time this file was created. */ + struct timespec creation_time; + + /** Time this file was last written to. */ + struct timespec last_write_time; + + /** Time this file was last accessed. */ + struct timespec last_access_time; + uint64_t reserved[16]; + + /** Array of streams that make up this file. The first entry will + * always exist and will correspond to the unnamed data stream (default + * file contents), so it will have @p stream_name == @c NULL. There + * will then be @p num_named_streams additional entries that specify the + * named data streams, if any, each of which will have @p stream_name != + * @c NULL. */ + struct wimlib_stream_entry streams[]; +}; + +/** + * Type of a callback function to wimlib_iterate_dir_tree(). Must return 0 on + * success. + */ +typedef int (*wimlib_iterate_dir_tree_callback_t)(const struct wimlib_dir_entry *dentry, + void *user_ctx); + +/** + * Type of a callback function to wimlib_iterate_lookup_table(). Must return 0 + * on success. + */ +typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resource_entry *resource, + void *user_ctx); + +/** For wimlib_iterate_dir_tree(): Iterate recursively on children rather than + * just on the specified path. */ +#define WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001 + +/** For wimlib_iterate_dir_tree(): Don't iterate on the file or directory + * 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 + + +/** @} */ +/** @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 @@ -631,7 +1137,7 @@ struct wimlib_capture_config { /** Call the progress function with the message * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to - * be scanned. */ + * be scanned, or when a directory or file is being excluded from capture. */ #define WIMLIB_ADD_FLAG_VERBOSE 0x00000004 /** Mark the image being added as the bootable image of the WIM. */ @@ -642,7 +1148,7 @@ struct wimlib_capture_config { * 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 +#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. */ @@ -677,6 +1183,32 @@ struct wimlib_capture_config { * 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 directories in NTFS-3g capture mode, or device files and FIFOs + * on UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when + * such a file is encountered. */ +#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 + +/** Automatically select a capture configuration appropriate for capturing + * filesystems containing Windows operating systems. When this flag is + * specified, the corresponding @p config parameter or member must be @c NULL. + * + * Currently, selecting this capture configuration will cause the following + * files and directories to be excluded from capture: + * + * - "\$ntfs.log" + * - "\hiberfil.sys" + * - "\pagefile.sys" + * - "\System Volume Information" + * - "\RECYCLER" + * - "\Windows\CSC" + * + * 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 + #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 @@ -687,10 +1219,13 @@ struct wimlib_capture_config { #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 -/****************************** - * 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 @@ -699,82 +1234,117 @@ struct wimlib_capture_config { * 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; + * if not, ::WIMLIB_ERR_UNSUPPORTED will be returned. In this mode, the + * extraction target will be interpreted as the path to a NTFS volume image (as + * a regular file or block device) rather than a directory. It will be opened + * using libntfs-3g, and the image will be extracted to the NTFS filesystem's + * root directory. Note: this flag cannot be used when wimlib_extract_image() + * is called with ::WIMLIB_ALL_IMAGES as the @p image. */ #define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001 /** When identical files are extracted from the WIM, always hard link them - * together. Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */ + * together. */ #define WIMLIB_EXTRACT_FLAG_HARDLINK 0x00000002 /** When identical files are extracted from the WIM, always symlink them - * together. Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */ + * together. */ #define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004 -/** Call the progress function with the argument - * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY each time a file or directory is - * extracted. Note: these calls will be interspersed with calls for the message - * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. */ +/** 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. */ #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. Only has an effect in NTFS apply mode, - * or in Win32 native builds. */ +/** Do not extract security descriptors. */ #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. 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. */ + * 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. */ #define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080 -/* Extract equivalent to ::WIMLIB_ADD_FLAG_RPFIX; force reparse-point - * fixups on, so absolute symbolic links or junction points will be fixed to be - * absolute relative to the actual extraction root. 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. */ +/** 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). */ #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. */ #define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200 -/** Extract files to standard output rather than to the filesystem. */ +/** 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. */ #define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400 /** Instead of ignoring files and directories with names that cannot be * represented on the current platform (note: Windows has more restrictions on - * filenames than UNIX), try to replace characters or append junk to the names - * so that they can be extracted in some form. */ + * filenames than POSIX-compliant systems), try to replace characters or append + * junk to the names so that they can be extracted in some form. */ #define WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES 0x00000800 /** On Windows, when there exist two or more files with the same case * insensitive name but different case sensitive names, try to extract them all * by appending junk to the end of them, rather than arbitrarily extracting only - * one. */ + * one. */ #define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000 -/****************************** - * WIMLIB_MOUNT_FLAG_* - ******************************/ +/** Do not ignore failure to set timestamps on extracted files. */ +#define WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000 + +/** Do not ignore failure to set short names on extracted files. */ +#define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000 + +/** Do not ignore failure to extract symbolic links (and junction points, on + * Windows) due to permissions problems. By default, such failures are ignored + * since the default configuration of Windows only allows the Administrator to + * create symbolic links. */ +#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000 + +/** TODO: this flag is intended to allow resuming an aborted extraction, but the + * behavior is currently less than satisfactory. Do not use (yet). */ +#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 + +/** @} */ +/** @ingroup G_mounting_wim_images + * @{ */ /** Mount the WIM image read-write rather than the default of read-only. */ #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 @@ -801,142 +1371,271 @@ struct wimlib_capture_config { * 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. */ +/** Verify the WIM contents against the WIM's integrity table, if present. This + * causes the raw data of the WIM file, divided into 10 MB chunks, to be + * checksummed and checked against the SHA1 message digests specified in the + * integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any + * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the + * integrity table is invalid). */ #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 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_* - ******************************/ +/** @} */ +/** @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 new WIM file. */ +/** Include an integrity table in the WIM. + * + * For WIMs created with wimlib_open_wim(), the default behavior is to include + * an integrity table if and only if one was present before. For WIMs created + * with wimlib_create_new_wim(), the default behavior is to not include an + * integrity table. */ #define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY 0x00000001 -/** Re-build the entire WIM file rather than appending data to it, if possible. - * (Applies to wimlib_overwrite(), not wimlib_write()). */ -#define WIMLIB_WRITE_FLAG_REBUILD 0x00000002 +/** Do not include an integrity table in the new WIM file. This is the default + * behavior, unless the WIM already included an integrity table. */ +#define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY 0x00000002 + +/** Write the WIM as "pipable". After writing a WIM with this flag specified, + * images from it can be applied directly from a pipe using + * wimlib_extract_image_from_pipe(). See the documentation for the --pipable + * flag of `wimlib-imagex capture' for more information. Beware: WIMs written + * with this flag will not be compatible with Microsoft's software. + * + * For WIMs created with wimlib_open_wim(), the default behavior is to write the + * WIM as pipable if and only if it was pipable before. For WIMs created with + * wimlib_create_new_wim(), the default behavior is to write the WIM as + * non-pipable. */ +#define WIMLIB_WRITE_FLAG_PIPABLE 0x00000004 + +/** Do not write the WIM as "pipable". This is the default behavior, unless the + * WIM was pipable already. */ +#define WIMLIB_WRITE_FLAG_NOT_PIPABLE 0x00000008 /** Recompress all resources, even if they could otherwise be copied from a * different WIM with the same compression type (in the case of - * wimlib_export_image() being called previously). */ -#define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000004 + * wimlib_export_image() being called previously). This flag is also valid in + * the @p wim_write_flags of wimlib_join(), in which case all resources included + * in the joined WIM file will be recompressed. */ +#define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000010 + +/** Call fsync() just before the WIM file is closed. */ +#define WIMLIB_WRITE_FLAG_FSYNC 0x00000020 + +/** wimlib_overwrite() only: Re-build the entire WIM file rather than appending + * data to it if possible. */ +#define WIMLIB_WRITE_FLAG_REBUILD 0x00000040 + +/** wimlib_overwrite() only: Specifying this flag overrides the default + * behavior of wimlib_overwrite() after one or more calls to + * wimlib_delete_image(), which is to rebuild the entire WIM. With this flag, + * only minimal changes to correctly remove the image from the WIM will be + * taken. In particular, all streams will be left alone, even if they are no + * longer referenced. This is probably not what you want, because almost no + * space will be saved by deleting an image in this way. */ +#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080 + +/** wimlib_overwrite() only: Allow overwriting the WIM even if the readonly + * flag is set in the WIM header. This can be used in combination with + * wimlib_set_wim_info() with the ::WIMLIB_CHANGE_READONLY_FLAG flag to actually + * set the readonly flag on the on-disk WIM file. */ +#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100 + +/** Do not include non-metadata resources already present in other WIMs. This + * flag can be used to write a "delta" WIM after resources from the WIM on which + * the delta is to be based were referenced with + * wimlib_reference_resource_files() or wimlib_reference_resources(). */ +#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 + +/** Use the slow LZX compression algorithm (rather than the default fast LZX + * compression algorithm) to try to achieve a higher compression ratio. Only + * has an effect if the WIM uses LZX compression; not to be confused with "fast" + * (XPRESS) compression. This can be combined with + * ::WIMLIB_WRITE_FLAG_RECOMPRESS. */ +#define WIMLIB_WRITE_FLAG_COMPRESS_SLOW 0x00000800 + +/** @} */ +/** @ingroup G_general + * @{ */ -/** Call fsync() when the WIM file is closed */ -#define WIMLIB_WRITE_FLAG_FSYNC 0x00000008 +/** Assume that strings are represented in UTF-8, even if this is not the + * locale's character encoding. This flag is ignored on Windows, where wimlib + * always uses UTF-16LE. */ +#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 -/* Specifying this flag overrides the default behavior of wimlib_overwrite() - * after one or more calls to wimlib_delete_image(), which is to rebuild the - * entire WIM. - * - * If you specifiy this flag to wimlib_overwrite(), 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 spaced by - * deleting an image in this way. */ -#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000010 +/** Windows-only: do not attempt to acquire additional privileges (currently + * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and + * SeTakeOwnershipPrivilege) when initializing the library. This is intended + * for the case where the calling program manages these privileges itself. + * Note: no error is issued if privileges cannot be acquired, although related + * errors may be reported later, depending on if the operations performed + * actually require additional privileges or not. */ +#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002 + +/** 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 -/****************************** - * WIMLIB_INIT_FLAG_* - ******************************/ +/** 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 + +/** @} */ +/** @ingroup G_nonstandalone_wims + * @{ */ + +/** wimlib_reference_resource_files() only: Enable shell-style filename + * globbing. */ +#define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001 + +/** wimlib_reference_resource_files() only: 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. */ +#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, +}; -/** Assume that strings are represented in UTF-8, even if this is not the - * locale's character encoding. */ -#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 +/** 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 (use no configuration), unless + * ::WIMLIB_ADD_FLAG_WINCONFIG is specified in @p + * add_flags. */ + struct wimlib_capture_config *config; + + /** 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; +}; + +/** 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; +}; /** Specification of an update to perform on a WIM image. */ struct wimlib_update_command { - /** 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, + enum wimlib_update_op op; - /** 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, - } 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; + struct wimlib_add_command add; + struct wimlib_delete_command delete_; /* Underscore is for C++ + compatibility. */ + struct wimlib_rename_command rename; }; }; -/** Specification of a file or directory tree to extract from a WIM image. */ +/** @} */ +/** @ingroup G_extracting_wims + * @{ */ + +/** Specification of a file or directory tree to extract from a WIM image. Used + * in calls to wimlib_extract_files(). */ struct wimlib_extract_command { /** Path to file or directory tree within the WIM image to extract. It * must be provided as an absolute path from the root of the WIM image. @@ -950,6 +1649,101 @@ struct wimlib_extract_command { int extract_flags; }; +/** @} */ +/** @ingroup G_compression + * @{ */ + +/** LZX compression parameters to pass to wimlib_lzx_alloc_context(). */ +struct wimlib_lzx_params { + /** Must be set to the size of this structure, in bytes. */ + uint32_t size_of_this; + + /** 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; + + /** This is the maximum match length to return from the + * binary tree match-finder. Any match reaching this + * limit is still extended as far as possible. Must be + * at least 3 and no more than 257. Suggested value: + * 32. */ + uint32_t num_fast_bytes; + + /** 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: 3. */ + uint32_t num_optim_passes; + + /** The number of times to attempt to recursively split + * each LZX block. Up to (2**(num_split_passes) + * sub-blocks can be created for a given input. This + * parameter can be 0, in which case the full input is + * always output as one block. Suggested value: 3. + */ + uint32_t num_split_passes; + + uint32_t slow_reserved2[4]; + + /** 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; +}; + +/** Opaque LZX compression context. */ +struct wimlib_lzx_context; + +/** @} */ +/** @ingroup G_general + * @{ */ + /** * Possible values of the error code returned by many functions in wimlib. * @@ -959,40 +1753,41 @@ struct wimlib_extract_command { enum wimlib_error_code { WIMLIB_ERR_SUCCESS = 0, WIMLIB_ERR_ALREADY_LOCKED, - WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE, WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_DELETE_STAGING_DIR, WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED, WIMLIB_ERR_FORK, WIMLIB_ERR_FUSE, WIMLIB_ERR_FUSERMOUNT, + WIMLIB_ERR_GLOB_HAD_NO_MATCHES, WIMLIB_ERR_ICONV_NOT_AVAILABLE, WIMLIB_ERR_IMAGE_COUNT, WIMLIB_ERR_IMAGE_NAME_COLLISION, - WIMLIB_ERR_INSUFFICIENT_PRIVILEGES_TO_EXTRACT, + WIMLIB_ERR_INSUFFICIENT_PRIVILEGES, WIMLIB_ERR_INTEGRITY, WIMLIB_ERR_INVALID_CAPTURE_CONFIG, WIMLIB_ERR_INVALID_CHUNK_SIZE, WIMLIB_ERR_INVALID_COMPRESSION_TYPE, - WIMLIB_ERR_INVALID_DENTRY, - WIMLIB_ERR_INVALID_HEADER_SIZE, + WIMLIB_ERR_INVALID_HEADER, WIMLIB_ERR_INVALID_IMAGE, WIMLIB_ERR_INVALID_INTEGRITY_TABLE, WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY, + WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_INVALID_MULTIBYTE_STRING, WIMLIB_ERR_INVALID_OVERLAY, WIMLIB_ERR_INVALID_PARAM, WIMLIB_ERR_INVALID_PART_NUMBER, + WIMLIB_ERR_INVALID_PIPABLE_WIM, WIMLIB_ERR_INVALID_REPARSE_DATA, WIMLIB_ERR_INVALID_RESOURCE_HASH, - WIMLIB_ERR_INVALID_RESOURCE_SIZE, - 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, @@ -1000,6 +1795,7 @@ enum wimlib_error_code { WIMLIB_ERR_NOTEMPTY, WIMLIB_ERR_NOT_A_REGULAR_FILE, WIMLIB_ERR_NOT_A_WIM_FILE, + WIMLIB_ERR_NOT_PIPABLE, WIMLIB_ERR_NO_FILENAME, WIMLIB_ERR_NTFS_3G, WIMLIB_ERR_OPEN, @@ -1010,16 +1806,23 @@ enum wimlib_error_code { WIMLIB_ERR_RENAME, WIMLIB_ERR_REOPEN, WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED, + WIMLIB_ERR_RESOURCE_NOT_FOUND, WIMLIB_ERR_RESOURCE_ORDER, - WIMLIB_ERR_SPECIAL_FILE, + WIMLIB_ERR_SET_ATTRIBUTES, + WIMLIB_ERR_SET_REPARSE_DATA, + WIMLIB_ERR_SET_SECURITY, + WIMLIB_ERR_SET_SHORT_NAME, + WIMLIB_ERR_SET_TIMESTAMPS, WIMLIB_ERR_SPLIT_INVALID, - WIMLIB_ERR_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, }; @@ -1032,9 +1835,15 @@ enum wimlib_error_code { #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. + * modifications, a root directory will be created automatically for it. After + * calling this function, you can use wimlib_update_image() to add files to the + * new WIM image. This gives you slightly more control over making the new + * image compared to calling wimlib_add_image() or + * wimlib_add_image_multisource() directly. * * @param wim * Pointer to the ::WIMStruct for the WIM file to which the image is to be @@ -1042,19 +1851,21 @@ enum wimlib_error_code { * @param name * Name to give the new image. If @c NULL or empty, the new image is given * no name. If nonempty, it must specify a name that does not already - * exist in @a wim. + * exist in @p wim. * @param new_idx_ret * If non-NULL, the index of the newly added image is returned * in this location. * * @return 0 on success; nonzero on failure. The possible error codes are: * - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * There is already an image in @a wim named @a name. + * There is already an image in @p wim named @p name. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate the memory needed to add the new image. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * The WIM file is considered read-only because of any of the reasons + * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS + * flag. */ extern int wimlib_add_empty_image(WIMStruct *wim, @@ -1062,6 +1873,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 @@ -1085,7 +1898,7 @@ wimlib_add_empty_image(WIMStruct *wim, * @param name * Name to give the new image. If @c NULL or empty, the new image is given * no name. If nonempty, it must specify a name that does not already - * exist in @a wim. + * 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 @@ -1094,9 +1907,12 @@ wimlib_add_empty_image(WIMStruct *wim, * Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG. * @param progress_func * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * progress of the current operation. The progress messages that will be + * received are ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN, + * ::WIMLIB_PROGRESS_MSG_SCAN_END, and, if ::WIMLIB_ADD_FLAG_VERBOSE was + * included in @p add_flags, also ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. * - * @return 0 on success; nonzero on error. On error, changes to @a wim are + * @return 0 on success; nonzero on error. On error, changes to @p wim are * discarded so that it appears to be in the same state as when this function * was called. * @@ -1114,9 +1930,12 @@ wimlib_add_image(WIMStruct *wim, 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 @a sources and @a num_sources parameters instead of the @a + * 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 * same as wimlib_add_image(). See the documentation for wimlib-imagex * capture for full details on how this mode works. @@ -1126,7 +1945,7 @@ wimlib_add_image(WIMStruct *wim, * when trying to overlay a non-directory on a directory or when otherwise * trying to overlay multiple conflicting files to the same location in the WIM * image. It will also return ::WIMLIB_ERR_INVALID_PARAM if - * ::WIMLIB_ADD_FLAG_NTFS was specified in @a add_flags but there + * ::WIMLIB_ADD_FLAG_NTFS was specified in @p add_flags but there * was not exactly one capture source with the target being the root directory. * (In this respect, there is no advantage to using * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting @@ -1141,6 +1960,8 @@ wimlib_add_image_multisource(WIMStruct *wim, 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 @@ -1157,7 +1978,7 @@ wimlib_add_image_multisource(WIMStruct *wim, * it. * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * @a ctype was not ::WIMLIB_COMPRESSION_TYPE_NONE, + * @p ctype was not ::WIMLIB_COMPRESSION_TYPE_NONE, * ::WIMLIB_COMPRESSION_TYPE_LZX, or ::WIMLIB_COMPRESSION_TYPE_XPRESS. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. @@ -1166,6 +1987,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 @@ -1181,133 +2004,115 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); * @param image * The number of the image to delete, or ::WIMLIB_ALL_IMAGES to delete all * images. - * @return 0 on success; nonzero on failure. On failure, @a wim is guaranteed - * to be left unmodified only if @a image specified a single image. If instead - * @a image was ::WIMLIB_ALL_IMAGES and @a wim contained more than one image, it's + * @return 0 on success; nonzero on failure. On failure, @p wim is guaranteed + * to be left unmodified only if @p image specified a single image. If instead + * @p image was ::WIMLIB_ALL_IMAGES and @p wim contained more than one image, it's * possible for some but not all of the images to have been deleted when a * failure status is returned. * - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Could not decompress the metadata resource for @a image. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for @a image in the WIM is - * invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not exist in the WIM and is not ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for @a image in the WIM is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for @a image in the WIM is invalid. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_READ - * Could not read the metadata resource for @a image from the WIM. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. Deleting an image from a split WIM is - * unsupported. + * @p image does not exist in the WIM and is not ::WIMLIB_ALL_IMAGES. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * The WIM file is considered read-only because of any of the reasons + * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS + * flag. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::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 * structure as the source image. This places some restrictions on additional * functions that may be called. wimlib_mount_image() may not be called on * either the source image or the destination image without an intervening call - * to a function that un-shares the images, such as wimlib_free() on @a + * to a function that un-shares the images, such as wimlib_free() on @p * dest_wim, or wimlib_delete_image() on either the source or destination image. - * Furthermore, you may not call wimlib_free() on @a src_wim before calling - * wimlib_write() or wimlib_overwrite() on @a dest_wim because @a dest_wim will - * have references back to @a src_wim. - * - * If this function fails, all changes to @a dest_wim are rolled back. + * Furthermore, you may not call wimlib_free() on @p src_wim before calling + * wimlib_write() or wimlib_overwrite() on @p dest_wim because @p dest_wim will + * have references back to @p src_wim. * - * No changes shall be made to @a src_wim by this function. + * If this function fails, all changes to @p dest_wim are rolled back. * - * Please note that no changes are committed to the underlying WIM file of @a + * Please note that no changes are committed to the underlying WIM file of @p * dest_wim (if any) until wimlib_write() or wimlib_overwrite() is called. * * @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 @a 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 @a src_wim is used. This parameter must be left @c - * NULL if @a src_image is ::WIMLIB_ALL_IMAGES and @a src_wim contains more - * than one image; in that case, the names are all taken from the @a - * 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 @a src_wim is used. This parameter must - * be left @c NULL if @a src_image is ::WIMLIB_ALL_IMAGES and @a src_wim contains - * more than one image; in that case, the descriptions are all taken from - * @a 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 @a src_image is ::WIMLIB_ALL_IMAGES and - * there are multiple images in @a src_wim, specifying - * ::WIMLIB_EXPORT_FLAG_BOOT is valid only if one of the exported images is - * currently marked as bootable in @a 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 @a 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 - * @a wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @a 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_DECOMPRESSION - * Could not decompress the metadata resource for @a src_image - * in @a src_wim * @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_DENTRY - * A directory entry in the metadata resource for @a src_image in @a - * src_wim is invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a src_image does not exist in @a 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 @a flags, @a src_image was - * ::WIMLIB_ALL_IMAGES, @a src_wim contains multiple images, and no images in - * @a src_wim are marked as bootable; or @a dest_name and/or @a - * dest_description were non-NULL, @a src_image was - * ::WIMLIB_ALL_IMAGES, and @a src_wim contains multiple images. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for @a src_image in @a src_wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for @a src_image in @a src_wim is invalid. + * @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_READ - * Could not read the metadata resource for @a src_image from @a src_wim. - * @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 - * original WIM, there are duplicate parts, or not all the parts have the - * same GUID and compression type. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a dest_wim is part of a split WIM. Exporting an image to a split WIM - * is unsupported. + * Failed to allocate needed memory. + * @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_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, @@ -1315,11 +2120,11 @@ 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); /** + * @ingroup G_extracting_wims + * * Extract zero or more files or directory trees from a WIM image. * * This generalizes the single-image extraction functionality of @@ -1327,11 +2132,15 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * image. * * @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 files, specified as a pointer to the + * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a + * split WIM. In the case of a WIM file that is not standalone, this + * ::WIMStruct must have had any needed external resources previously + * referenced using wimlib_reference_resources() or + * wimlib_reference_resource_files(). * * @param image - * The 1-based number of the image in @a wim from which the files or + * 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 @@ -1339,33 +2148,24 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * extractions to perform. * * @param num_cmds - * Number of commands in the @a cmds array. + * 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 @a 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 - * @a wim parameter. - * - * @param num_additional_swms - * Number of additional WIM parts provided in the @a 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 - * those documented as returned by wimlib_extract_image() as well as the + * 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. @@ -1387,19 +2187,20 @@ wimlib_extract_files(WIMStruct *wim, 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 a NTFS volume. + * @ingroup G_extracting_wims * - * Please see the manual page for the @c wimlib-imagex program for more - * information about the "normal" extraction mode versus the NTFS extraction - * mode (entered by providing flag ::WIMLIB_EXTRACT_FLAG_NTFS). + * Extracts an image, or all images, from a WIM to a directory or directly to a + * NTFS volume image. * - * Extraction is done with one thread. + * The exact behavior of how wimlib extracts files from a WIM image is + * controllable by the @p extract_flags parameter, but there also are + * differences depending on the platform (UNIX-like vs Windows). See the manual + * page for wimlib-imagex apply for more information, including about the + * special "NTFS volume extraction mode" entered by providing + * ::WIMLIB_EXTRACT_FLAG_NTFS. * * 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 @@ -1408,143 +2209,195 @@ wimlib_extract_files(WIMStruct *wim, * 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 @a extract_flags. + * 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 @a extract_flags, the + * exist); or, with ::WIMLIB_EXTRACT_FLAG_NTFS in @p extract_flags, the * path to the unmounted NTFS volume to extract the image to. * @param extract_flags * Bitwise OR of the flags prefixed with WIMLIB_EXTRACT_FLAG. - *

- * If ::WIMLIB_EXTRACT_FLAG_NTFS is specified, @a target is interpreted as - * a NTFS volume to extract the image to. The volume will be opened using - * NTFS-3g and the image will be extracted to the root of the NTFS volume. - * Otherwise, @a target is interpreted as a directory to extract the - * image(s) to. - *

- * If ::WIMLIB_EXTRACT_FLAG_NTFS is not specified, one or none of - * ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK may be - * specified. These flags cause extracted files that are identical to be - * hardlinked or symlinked together, depending on the flag. These flags - * override the hard link groups that are specified in the WIM file itself. - * If ::WIMLIB_ALL_IMAGES is provided as the @a image parameter, files may be - * hardlinked or symlinked across images if a file is found to occur in - * more than one image. - *

- * You may also specify the flag ::WIMLIB_EXTRACT_FLAG_VERBOSE to print the - * name of each file or directory as it is extracted. - *

- * If ::WIMLIB_EXTRACT_FLAG_SEQUENTIAL is specified, data is read from the - * WIM sequentially, if possible. If ::WIMLIB_ALL_IMAGES is specified, - * each image is considered separately with regards to the sequential - * order. It is also possible for alternate data streams to break the - * sequential order (this only applies if ::WIMLIB_EXTRACT_FLAG_NTFS is - * specified). - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @a 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 - * @a wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @a 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. * @retval ::WIMLIB_ERR_DECOMPRESSION - * Could not decompress a resource (file or metadata) for @a image in @a - * wim. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for @a image in @a wim is - * invalid. + * Failed to decompress a resource to be extracted. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a target was @c NULL, or both ::WIMLIB_EXTRACT_FLAG_HARDLINK and - * ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags; or - * both ::WIMLIB_EXTRACT_FLAG_NTFS and either - * ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK were - * specified in @a extract_flags; or ::WIMLIB_EXTRACT_FLAG_NTFS was - * specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES; or - * both ::WIMLIB_EXTRACT_FLAG_NTFS and ::WIMLIB_EXTRACT_FLAG_UNIX_DATA were - * specified in @a extract_flag. + * 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. * @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. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * A resource (file or metadata) for @a image in @a wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_LINK -* Failed to create a symbolic link or a hard link (only if - * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @a extract_flags). + * Failed to create a symbolic link or a hard link. * @retval ::WIMLIB_ERR_MKDIR - * Failed create a needed directory (only if ::WIMLIB_EXTRACT_FLAG_NTFS was - * not specified in @a extract_flags). + * Failed create a directory. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_NTFS_3G - * An error was returned from a libntfs-3g function while the WIM image was - * being extracted to the NTFS volume (only if ::WIMLIB_EXTRACT_FLAG_NTFS - * was specified in @a extract_flags). * @retval ::WIMLIB_ERR_OPEN - * Could not open one of the files being extracted for writing (only if - * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @a extract_flags). + * Could not create a file, or failed to open an already-extracted file. * @retval ::WIMLIB_ERR_READ - * A unexpected end-of-file or read error occurred when trying to read data - * from the WIM file associated with @a wim. - * @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. + * Failed to read data from the WIM file associated with @p 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.) + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * One of the files or directories that needed to be extracted referenced a + * stream not present in the WIM's lookup table (or in any of the lookup + * tables of the split WIM parts). + * @retval ::WIMLIB_ERR_SET_ATTRIBUTES + * Failed to set attributes on a file. + * @retval ::WIMLIB_ERR_SET_REPARSE_DATA + * Failed to set reparse data on a file (only if reparse data was supported + * by the extraction mode). + * @retval ::WIMLIB_ERR_SET_SECURITY + * Failed to set security descriptor on a file + * (only if ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS was specified in @p + * extract_flags). + * @retval ::WIMLIB_ERR_SET_SHORT_NAME + * Failed to set the short name of a file (only if + * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES was specified in @p extract_flags). + * @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_UNEXPECTED_END_OF_FILE + * Unexpected end-of-file occurred when reading data from the WIM file + * associated with @p wim. * @retval ::WIMLIB_ERR_UNSUPPORTED - * ::WIMLIB_EXTRACT_FLAG_NTFS was specified in @a extract_flags, but wimlib - * was configured with the @c --without-ntfs-3g flag. + * A requested extraction flag, or the data or metadata that must be + * extracted to support it, is unsupported in the build and configuration + * of wimlib, or on the current platform or extraction mode or target + * volume. Flags affected by this include ::WIMLIB_EXTRACT_FLAG_NTFS, + * ::WIMLIB_EXTRACT_FLAG_UNIX_DATA, ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS, + * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES, + * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS, + * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS, ::WIMLIB_EXTRACT_FLAG_SYMLINK, + * and ::WIMLIB_EXTRACT_FLAG_HARDLINK. For example, if + * ::WIMLIB_EXTRACT_FLAG_STRICT_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 + * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags. * @retval ::WIMLIB_ERR_WRITE - * Failed to write a file being extracted (only if - * ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @a extract_flags). + * Failed to write data to a file being extracted. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image that needed to + * be extracted. */ 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); /** + * @ingroup G_extracting_wims + * + * Since wimlib v1.5.0: Extract one or more images from a pipe on which a + * pipable WIM is being sent. + * + * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information + * about pipable WIMs. + * + * This function operates in a special way to read the WIM fully sequentially. + * As a result, there is no ::WIMStruct is made visible to library users, and + * you cannot call wimlib_open_wim() on the pipe. (You can, however, use + * wimlib_open_wim() to transparently open a pipable WIM if it's available as a + * seekable file, not a pipe.) + * + * @param pipe_fd + * File descriptor, which may be a pipe, opened for reading and positioned + * at the start of the pipable WIM. + * @param image_num_or_name + * String that specifies the 1-based index or name of the image to extract. + * It is translated to an image index using the same rules that + * 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 ::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 + * 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. + * + * @return 0 on success; nonzero on error. The possible error codes include + * those returned by wimlib_extract_image() as well as the following: + * + * @retval ::WIMLIB_ERR_INVALID_PIPABLE_WIM + * Data read from the pipable WIM was invalid. + * @retval ::WIMLIB_ERR_NOT_PIPABLE + * The WIM being piped in a @p pipe_fd is a normal WIM, not a pipable WIM. + */ +extern int +wimlib_extract_image_from_pipe(int pipe_fd, + const wimlib_tchar *image_num_or_name, + const wimlib_tchar *target, int extract_flags, + wimlib_progress_func_t progress_func); + +/** + * @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. - * This function works on standalone WIMs as well as split WIM parts. + * + * See wimlib_get_xml_data() to read the XML data into memory instead. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct for a WIM file, which does not necessarily + * have to be standalone (e.g. it could be part of a split WIM). * @param fp * @c stdout, or a FILE* opened for writing, to extract the data to. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim is not a ::WIMStruct that was created by wimlib_open_wim(). + * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(). * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_READ + * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE * Failed to read the XML data from the WIM. * @retval ::WIMLIB_ERR_WRITE - * Failed to completely write the XML data to @a fp. + * Failed to completely write the XML data to @p fp. */ 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. * @@ -1557,32 +2410,8 @@ extern void wimlib_free(WIMStruct *wim); /** - * Returns the index of the bootable image of the WIM. + * @ingroup G_general * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * - * @return - * 0 if no image is marked as bootable, or the number of the image marked - * as bootable (numbered starting at 1). - */ -extern int -wimlib_get_boot_idx(const WIMStruct *wim); - -/** - * Returns the compression type used in the WIM. - * - * @param wim - * Pointer to the ::WIMStruct for a WIM file - * - * @return - * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, or - * ::WIMLIB_COMPRESSION_TYPE_XPRESS. - */ -extern int -wimlib_get_compression_type(const WIMStruct *wim); - -/** * Converts a ::wimlib_compression_type value into a string. * * @param ctype @@ -1597,6 +2426,8 @@ 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 @@ -1610,11 +2441,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. * @@ -1629,96 +2462,108 @@ 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. * * @return - * The name of the image, or @c NULL if there is no such image. The name - * string is in library-internal memory and may not be modified or freed; - * in addition, the string will become invalid if the name of the image is - * changed, the image is deleted, or the ::WIMStruct is destroyed. - * - * If @a wim was read with wimlib_open_wim(), it is allowed for image(s) in - * the WIM to be unnamed, in which case an empty string will be returned - * when the corresponding name is requested. + * The name of the image, or @c NULL if there is no such image, or an empty + * string if the image is unnamed. The name string is in + * library-internal memory and may not be modified or freed; in addition, + * the string will become invalid if the name of the image is changed, the + * image is deleted, or the ::WIMStruct is destroyed. */ extern const wimlib_tchar * wimlib_get_image_name(const WIMStruct *wim, int image); /** - * Returns the number of images contained in a WIM. + * @ingroup G_wim_information * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or a split WIM part. + * Get basic information about a WIM file. * + * @param wim + * Pointer to the ::WIMStruct for a WIM file that does not necessarily have + * to be standalone (e.g. it could be part of a split WIM). + * @param info + * A ::wimlib_wim_info structure that will be filled in with information + * about the WIM file. * @return - * The number of images contained in the WIM file. + * 0 */ extern int -wimlib_get_num_images(const WIMStruct *wim); +wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); /** - * Returns the part number of a WIM in a split WIM and the total number of parts - * of the split WIM. + * @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. - * @param total_parts_ret - * If non-@c NULL, the total number of parts in the split WIM (1 for - * non-split WIMs) is written to this location. + * 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 - * The part number of the WIM (1 for non-split WIMs) + * @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_part_number(const WIMStruct *wim, int *total_parts_ret); +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. + * 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. * * @param init_flags - * On UNIX, specify ::WIMLIB_INIT_FLAG_ASSUME_UTF8 if wimlib should assume - * that all input data, including filenames, are in UTF-8 rather than the - * locale-dependent character encoding which may or may not be UTF-8, and - * that UTF-8 data can be directly printed to the console. On Windows, use - * 0 for this parameter. + * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. + * + * @return 0 on success; nonzero on failure. Currently, only the following + * error code is defined: * - * @return 0; other error codes may be returned in future releases. + * @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); /** - * Since wimlib 1.2.6: Cleanup function for wimlib. This is not re-entrant. - * You are not required to call this function, but it will release any global - * memory allocated by the library. + * @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. */ extern void wimlib_global_cleanup(void); /** - * Returns true if the WIM has an integrity table. + * @ingroup G_wim_information * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @return - * @c true if the WIM has an integrity table; @c false otherwise. If @a - * wim is a ::WIMStruct created with wimlib_create_new_wim() rather than - * wimlib_open_wim(), @c false will be returned, even if wimlib_write() has - * been called on @a wim with ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY set. - */ -extern bool -wimlib_has_integrity_table(const WIMStruct *wim); - -/** * Determines if an image name is already used by some image in the WIM. * * @param wim @@ -1727,14 +2572,108 @@ wimlib_has_integrity_table(const WIMStruct *wim); * The name to check. * * @return - * @c true if there is already an image in @a wim named @a name; @c false - * if there is no image named @a name in @a wim. If @a name is @c NULL or + * @c true if there is already an image in @p wim named @p name; @c false + * if there is no image named @p name in @p wim. If @p name is @c NULL or * the empty string, @c false is returned. */ 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 + * 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 + * directories to iterate over, or ::WIMLIB_ALL_IMAGES to repeat the same + * iteration on all images in the WIM. + * + * @param path + * Path in the WIM image at which to do the iteration. + * + * @param flags + * Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG. + * + * @param cb + * A callback function that will receive each directory entry. + * + * @param user_ctx + * An extra parameter that will always be passed to the callback function + * @p cb. + * + * @return Normally, returns 0 if all calls to @p cb returned 0; otherwise the + * first nonzero value that was returned from @p cb. However, additional error + * codes may be returned, including the following: + * + * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST + * @p path did not exist in the WIM image. + * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate memory needed to create a ::wimlib_dir_entry. + * + * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, + * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, + * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or + * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for + * different reasons) to read the metadata resource for an image over which + * iteration needed to be done. + */ +extern int +wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, + int flags, + 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 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 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. + * + * @param cb + * A callback function that will receive each resource. + * + * @param user_ctx + * An extra parameter that will always be passed to the callback function + * @p cb. + * + * @return 0 if all calls to @p cb returned 0; otherwise the first nonzero value + * that was returned from @p cb. + */ +extern int +wimlib_iterate_lookup_table(WIMStruct *wim, int flags, + wimlib_iterate_lookup_table_callback_t cb, + void *user_ctx); + +/** + * @ingroup G_nonstandalone_wims + * * Joins a split WIM into a stand-alone one-part WIM. * * @param swms @@ -1742,34 +2681,34 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * WIM. No specific order is required, but all parts must be included with * no duplicates. * @param num_swms - * Number of filenames in @a swms. + * Number of filenames in @p swms. * @param swm_open_flags - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY if the integrity of each split WIM - * part should be verified, if integrity tables are present. Otherwise, - * set to 0. + * Open flags for the split WIM parts (e.g. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). * @param wim_write_flags - * Bitwise OR of ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY, and/or ::WIMLIB_WRITE_FLAG_FSYNC. + * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will + * be used to write the joined WIM. * @param output_path - * The path to write the one-part WIM to. + * The path to write the joined WIM file to. * @param progress_func * If non-NULL, a function that will be called periodically with the * progress of the current operation. * - * @return 0 on success; nonzero on error. This function may return any value - * returned by wimlib_open_wim() and wimlib_write() except - * ::WIMLIB_ERR_SPLIT_UNSUPPORTED, as well as the following error code: + * @return 0 on success; nonzero on error. This function may return most error + * codes that can be returned by wimlib_open_wim() and wimlib_write(), as well + * as the following error code: * * @retval ::WIMLIB_ERR_SPLIT_INVALID * The split WIMs do not form a valid 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. * - * Note: the WIM's uncompressed and compressed resources are not checksummed - * when they are copied from the split WIM parts to the joined WIM, nor are - * compressed resources re-compressed. - * - * Note: wimlib_export_image() can provide similar functionality to - * wimlib_join(), since it is possible to export all images from a split WIM. + * 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, @@ -1780,34 +2719,93 @@ wimlib_join(const wimlib_tchar * const *swms, wimlib_progress_func_t progress_func); /** + * @ingroup G_compression + * * Compress a chunk of a WIM resource using LZX compression. * - * This function is exported for convenience only and need not be used. + * 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 (@a chunk_size - 1) bytes. + * Pointer to output buffer of size at least (@p chunk_size - 1) bytes. * * @return - * The size of the compressed data written to @a out in bytes, or 0 if the - * data could not be compressed to (@a chunk_size - 1) bytes or fewer. + * 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 (@a chunk_size <= 32768). + * format and therefore requires (@p chunk_size <= 32768). + */ +extern unsigned +wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out) + _wimlib_deprecated; + +/** + * @ingroup G_compression + * + * Equivalent to wimlib_lzx_compress(), but uses the specified compression + * context, allocated by wimlib_lzx_alloc_context(). */ extern unsigned -wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out); +wimlib_lzx_compress2(const void *chunk, unsigned chunk_size, void *out, + struct wimlib_lzx_context *ctx); + +/** + * @ingroup G_compression + * + * Allocate a LZX compression context using the specified parameters. + * + * 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 params + * Compression parameters to use, or @c NULL to use the default algorithm + * and parameters. + * + * @param ctx_ret + * A pointer to either @c NULL or an existing ::wimlib_lzx_context. If + * *ctx_ret == NULL, the new context is allocated. If + * *ctx_ret != NULL, the existing context is re-used if + * possible. Alternatively, this argument can itself be @c NULL to + * indicate that only parameter validation is to be performed. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The compression parameters were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Not enough memory to allocate the compression context. + */ +extern int +wimlib_lzx_alloc_context(const struct wimlib_lzx_params *params, + struct wimlib_lzx_context **ctx_pp); /** + * @ingroup G_compression + * + * Free the specified LZX compression context, allocated with + * wimlib_lzx_alloc_context(). + */ +extern void +wimlib_lzx_free_context(struct wimlib_lzx_context *ctx); + +/** + * @ingroup G_compression + * * 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! * - * This function is exported for convenience only and need not be used. + * 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. @@ -1830,25 +2828,30 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, /** - * Mounts an image in a WIM file on a directory read-only or read-write. + * @ingroup G_mounting_wim_images * - * This is not supported on Windows. + * Mounts an image in a WIM file on a directory read-only or read-write. * - * Unless ::WIMLIB_MOUNT_FLAG_DEBUG is specified or an early error occurs, the - * process will be daemonized. + * As this is implemented using FUSE (Filesystme in UserSpacE), this is not + * supported if wimlib was configured with @c --without-fuse. This includes + * Windows builds of wimlib; ::WIMLIB_ERR_UNSUPPORTED will be returned in such + * cases. * - * If the mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), - * modifications to the WIM are staged in a temporary directory. + * Calling this function daemonizes the process, unless + * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early occur occurs. If the + * mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), modifications + * to the WIM are staged in a temporary directory. * - * It is safe to mount multiple images from the same WIM file read-only at the - * same time, but only if different ::WIMStruct's are used. It is @b not safe - * to mount multiple images from the same WIM file read-write at the same time. + * It is safe to mount multiple images from the same underlying WIM file + * read-only at the same time, but only if different ::WIMStruct's are used. It + * is @b not safe to mount multiple images from the same WIM file read-write at + * the same time. * * wimlib_mount_image() cannot be used on an image that was exported with * wimlib_export_image() while the dentry trees for both images are still in * memory. In addition, wimlib_mount_image() may not be used to mount an image - * that has just been added with wimlib_add_image(), unless the WIM has been - * written and read into a new ::WIMStruct. + * that already has modifications pending (e.g. an image added with + * wimlib_add_image()). * * @param wim * Pointer to the ::WIMStruct containing the image to be mounted. @@ -1859,32 +2862,11 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, * 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. - *

- * If ::WIMLIB_MOUNT_FLAG_READWRITE is given, the WIM is mounted read-write - * rather than the default of read-only. - *

- * WIMs may contain named (alternate) data streams, which are a somewhat - * obscure NTFS feature. They can be read and written on a mounted WIM - * through one of several interfaces. The interface to use if specified by - * exactly one of ::WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE, - * ::WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR, or - * ::WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS. The default interface is - * the XATTR interface. - * @param additional_swms - * Array of pointers to the ::WIMStruct for each additional part in the - * split WIM. Ignored if @a 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 - * @a wim parameter. - * @param num_additional_swms - * Number of additional WIM parts provided in the @a 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 staging_dir * If non-NULL, the name of a directory in which the staging directory will * be created. Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified - * in @a mount_flags. If left @c NULL, the staging directory is created in - * the same directory as the WIM file that @a wim was originally read from. + * in @p mount_flags. If left @c NULL, the staging directory is created in + * the same directory as the WIM file that @p wim was originally read from. * * @return 0 on success; nonzero on error. * @@ -1893,132 +2875,118 @@ 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 @a image in @a wim. * @retval ::WIMLIB_ERR_FUSE * A non-zero status was returned by @c fuse_main(). - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for @a image in @a wim is - * invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify an existing, single image in @a wim. + * @p image does not specify an existing, single image in @p wim. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a image is shared among multiple ::WIMStruct's as a result of a call to - * wimlib_export_image(), or @a image has been added with + * @p image is shared among multiple ::WIMStruct's as a result of a call to + * wimlib_export_image(), or @p image has been added with * wimlib_add_image(). - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for @a image in @a wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_MKDIR - * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @a mount_flags, but the + * ::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 - * An unexpected end-of-file or read error occurred when trying to read - * data from the WIM file associated with @a wim. - * @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_SPLIT_UNSUPPORTED - * The WIM is a split WIM and a read-write mount was requested. We only - * support mounting a split WIM read-only. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * One of the dentries in the image referenced a stream not present in the + * WIM's lookup table (or in any of the lookup tables of the split WIM + * parts). + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but @p + * wim is considered read-only because of any of the reasons mentioned in + * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. * @retval ::WIMLIB_ERR_UNSUPPORTED * Mounting is not supported, either because the platform is Windows, or - * because the platform is UNIX and wimlib was compiled with @c + * 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 * The path to the WIM file to open. + * * @param open_flags - * Bitwise OR of flags ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY and/or - * ::WIMLIB_OPEN_FLAG_SPLIT_OK. - *

- * If ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is given, the integrity table of - * the WIM, if it exists, is checked, and this function will fail with an - * ::WIMLIB_ERR_INTEGRITY status if any of the computed SHA1 message - * digests of the WIM do not exactly match the corresponding message - * digests given in the integrity table. - *

- * If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the - * WIM is part of a split WIM; otherwise ::WIMLIB_ERR_SPLIT_UNSUPPORTED is - * returned. (This flag may be removed in the future, in which case no - * error will be issued when opening a split WIM.) + * Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG. * * @param progress_func * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * progress of the current operation. Currently, the only messages sent + * will be ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY, and only if + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags. * * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the opened WIM file * is written to the memory location pointed to by this parameter. The - * ::WIMStruct must be freed using using wimlib_free() when finished with + * ::WIMStruct can be freed using using wimlib_free() when finished with * it. * * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE - * The lookup table of @a wim_file is compressed. Support for this can be - * added to wimlib if needed, but it appears to be the case that the lookup - * table is never compressed. * @retval ::WIMLIB_ERR_IMAGE_COUNT * The WIM is not the non-first part of a split WIM, and the number of * metadata resources found in the WIM did not match the image count given * in the WIM header, or the number of <IMAGE> elements in the XML * data for the WIM did not match the image count given in the WIM header. * @retval ::WIMLIB_ERR_INTEGRITY - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @a open_flags and @a + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p * wim_file contains an integrity table, but the SHA1 message digest for a * chunk of the WIM does not match the corresponding message digest given * in the integrity table. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * Resources in @a wim_file are compressed, but the chunk size is not 32768. + * Resources in @p wim_file are compressed, but the chunk size is not 32768. * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * The header of @a wim_file says that resources in the WIM are compressed, + * 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. - * @retval ::WIMLIB_ERR_INVALID_HEADER_SIZE - * The length field of the WIM header is not 208. + * @retval ::WIMLIB_ERR_INVALID_HEADER + * The header of @p wim_file was otherwise invalid. * @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @a open_flags and @a + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and @p * 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. + * @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 - * @a wim_file does not begin with the expected magic characters. + * @p wim_file does not begin with the expected magic characters. * @retval ::WIMLIB_ERR_OPEN - * Failed to open the file @a wim_file for reading. + * Failed to open the file @p wim_file for reading. * @retval ::WIMLIB_ERR_READ - * An unexpected end-of-file or read error occurred when trying to read - * data from @a wim_file. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim_file is a split WIM, but ::WIMLIB_OPEN_FLAG_SPLIT_OK was not - * specified in @a open_flags. + * Failed to read data from @p wim_file. + * @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 @a wim_file. (Probably a pre-Vista WIM). + * header of @p wim_file. (May be a pre-Vista WIM.) + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was + * considered read-only because of any of the reasons mentioned in the + * documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. * @retval ::WIMLIB_ERR_XML - * The XML data for @a wim_file is invalid. + * The XML data for @p wim_file is invalid. */ extern int wimlib_open_wim(const wimlib_tchar *wim_file, @@ -2027,6 +2995,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(). @@ -2065,7 +3035,7 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * appended to the original WIM, it should still be a valid WIM. * * If this function completes successfully, no more functions should be called - * on @a wim other than wimlib_free(). You must use wimlib_open_wim() to read + * on @p wim other than wimlib_free(). You must use wimlib_open_wim() to read * the WIM file anew. * * @param wim @@ -2073,34 +3043,39 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * been in-memory changes made to it, which are then reflected in the * output file. * @param write_flags - * Bitwise OR of the flags ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY, - * ::WIMLIB_WRITE_FLAG_REBUILD, ::WIMLIB_WRITE_FLAG_RECOMPRESS, and/or - * ::WIMLIB_WRITE_FLAG_SOFT_DELETE. + * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. * @param num_threads * Number of threads to use for compression (see wimlib_write()). * @param progress_func * If non-NULL, a function that will be called periodically with the * progress of the current operation. * - * @return 0 on success; nonzero on error. This function may return 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 modifien in-place (with no temporary file), but + * The WIM was going to be modified in-place (with no temporary file), but * an exclusive advisory lock on the on-disk WIM file could not be acquired * because another thread or process has mounted an image from the WIM * read-write or is currently modifying the WIM in-place. * @retval ::WIMLIB_ERR_NO_FILENAME - * @a wim corresponds to a WIM created with wimlib_create_new_wim() rather + * @p wim corresponds to a WIM created with wimlib_create_new_wim() rather * than a WIM read with wimlib_open_wim(). * @retval ::WIMLIB_ERR_RENAME * The temporary file that the WIM was written to could not be renamed to - * the original filename of @a wim. + * the original filename of @p wim. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * The WIM file is considered read-only because of any of the reasons + * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS + * flag. */ extern int wimlib_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 @@ -2111,133 +3086,201 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads, * WIM. * * @return This function has no return value. No error checking is done when - * printing the information. If @a image is invalid, an error message is + * printing the information. If @p image is invalid, an error message is * printed. */ extern void wimlib_print_available_images(const WIMStruct *wim, int image); /** - * Prints the full paths to all files contained in an image, or all images, in a - * WIM file. + * @ingroup G_wim_information * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @param image - * Which image to print files for. Can be the number of an image, or - * ::WIMLIB_ALL_IMAGES to print the files contained in all images. + * Deprecated in favor of wimlib_get_wim_info(), which provides the information + * in a way that can be accessed programatically. + */ +extern void +wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; + +/** + * @ingroup G_wim_information * - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_DECOMPRESSION - * The metadata resource for one of the specified images could not be - * decompressed. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for one of the specified - * images is invaled. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a valid image in @a wim, and is not - * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_READ - * An unexpected read error or end-of-file occurred when reading the - * metadata resource for one of the specified images. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim was not a standalone WIM and was not the first part of a split - * WIM. + * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the + * information in a way that can be accessed programatically. */ extern int -wimlib_print_files(WIMStruct *wim, int image); +wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; /** - * Prints detailed information from the header of a WIM file. + * @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 - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split 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 This function has no return value. + * @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 void -wimlib_print_header(const WIMStruct *wim); +extern int +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); /** - * Prints the lookup table of a WIM file. The lookup table maps SHA1 message - * digests, as found in the directory entry tree in the WIM file, to file - * resources in the WIM file. This table includes one entry for each unique - * file in the WIM, so it can be quite long. There is only one lookup table per - * WIM file, but each split WIM part has its own lookup table. + * @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 - * Pointer to the ::WIMStruct for a WIM file. + * 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(). * - * @return This function has no return value. + * @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 void -wimlib_print_lookup_table(WIMStruct *wim); +extern int +wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, + unsigned num_resource_wims, int ref_flags); /** - * Prints the metadata of the specified image in a WIM file. The metadata - * consists of the security data as well as the directory entry tree. Each - * image has its own metadata. + * @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 file. - * @param image - * Which image to print the metadata for. Can be the number of an image, - * or ::WIMLIB_ALL_IMAGES to print the metadata for all images in the 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_DECOMPRESSION - * The metadata resource for one of the specified images could not be - * decompressed. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for one of the specified - * images is invaled. + * * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a valid image in @a wim, and is not - * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for one of the specified images is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for one of the specified images is invalid. + * @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_READ - * An unexpected read error or end-of-file occurred when reading the - * metadata resource for one of the specified images. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim was not a standalone WIM and was not the first part of a split - * WIM. + * 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_print_metadata(WIMStruct *wim, int image); +wimlib_reference_template_image(WIMStruct *wim, int new_image, + WIMStruct *template_wim, int template_image, + int flags, wimlib_progress_func_t progress_func); /** - * Prints some basic information about a WIM file. All information printed by - * this function is also printed by wimlib_print_header(), but - * wimlib_print_wim_information() prints some of this information more concisely - * and in a more readable form. + * @ingroup G_wim_information * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * - * @return This function has no return value. - */ -extern void -wimlib_print_wim_information(const WIMStruct *wim); - -/** * 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 @@ -2254,39 +3297,21 @@ wimlib_print_wim_information(const WIMStruct *wim); * If the string resolved to a single existing image, the number of that * image, indexed starting at 1, is returned. If the keyword "all" or "*" * was specified, ::WIMLIB_ALL_IMAGES is returned. Otherwise, - * ::WIMLIB_NO_IMAGE is returned. If @a image_name_or_num was @c NULL or + * ::WIMLIB_NO_IMAGE is returned. If @p image_name_or_num was @c NULL or * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more - * images in @a wim has no name. + * images in @p wim has no name. */ extern int wimlib_resolve_image(WIMStruct *wim, const wimlib_tchar *image_name_or_num); /** - * Sets which image in the WIM is marked as bootable. + * @ingroup G_modifying_wims * - * @param wim - * Pointer to the ::WIMStruct for a WIM file. - * @param boot_idx - * The number of the image to mark as bootable, or 0 to mark no image as - * bootable. - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a boot_idx does not specify an existing image in @a wim, and it was not - * 0. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. - */ -extern int -wimlib_set_boot_idx(WIMStruct *wim, int boot_idx); - -/** * 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 @@ -2295,25 +3320,58 @@ wimlib_set_boot_idx(WIMStruct *wim, int boot_idx); * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a single existing image in @a wim. + * @p image does not specify a single existing image in @p wim. * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate the memory needed to duplicate the @a description + * Failed to allocate the memory needed to duplicate the @p description * string. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * @p wim is considered read-only because of any of the reasons mentioned + * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. */ extern int wimlib_set_image_descripton(WIMStruct *wim, int image, const wimlib_tchar *description); /** + * @ingroup G_modifying_wims + * + * Set basic information about a WIM. + * + * @param wim + * Pointer to the ::WIMStruct for a WIM. + * @param info + * A struct ::wimlib_wim_info that contains the information to set. Only + * the information explicitly specified in the @p which flags need be + * valid. + * @param which + * Flags that specify which information to set. This is a bitwise OR of + * ::WIMLIB_CHANGE_READONLY_FLAG, ::WIMLIB_CHANGE_GUID, + * ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG. + * + * @return 0 on success; nonzero on failure. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * The WIM file is considered read-only because of any of the reasons + * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS + * flag. However, as a special case, if you are using + * ::WIMLIB_CHANGE_READONLY_FLAG to unset the readonly flag, then this + * function will not fail due to the readonly flag being previously set. + * @retval ::WIMLIB_ERR_IMAGE_COUNT + * ::WIMLIB_CHANGE_BOOT_INDEX was specified, but + * ::wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image + * index in the WIM. + */ +extern int +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 @@ -2322,43 +3380,47 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a single existing image in @a wim. + * @p image does not specify a single existing image in @p wim. * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate the memory needed to duplicate the @a flags string. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. + * Failed to allocate the memory needed to duplicate the @p flags string. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * @p wim is considered read-only because of any of the reasons mentioned + * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. */ -extern int wimlib_set_image_flags(WIMStruct *wim, int image, - const wimlib_tchar *flags); +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 * New name to give the new image. If @c NULL or empty, the new image is * given no name. If nonempty, it must specify a name that does not - * already exist in @a wim. + * already exist in @p wim. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * There is already an image named @a name in @a wim. + * There is already an image named @p name in @p wim. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a single existing image in @a wim. + * @p image does not specify a single existing image in @p wim. * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate the memory needed to duplicate the @a name string. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. + * Failed to allocate the memory needed to duplicate the @p name string. + * @retval ::WIMLIB_ERR_WIM_IS_READONLY + * @p wim is considered read-only because of any of the reasons mentioned + * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. */ -extern int wimlib_set_image_name(WIMStruct *wim, int image, - const wimlib_tchar *name); +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. @@ -2392,6 +3454,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 @@ -2401,13 +3465,15 @@ wimlib_set_memory_allocator(void *(*malloc_func)(size_t), * * By default, error messages are not printed. * + * This can be called before wimlib_global_init(). + * * @param show_messages * @c true if error messages are to be printed; @c false if error messages * are not to be printed. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_UNSUPPORTED - * @a show_messages was @c true, but wimlib was compiled with the @c + * @p show_messages was @c true, but wimlib was compiled with the @c * --without-error-messages option. Therefore, error messages cannot be * shown. */ @@ -2415,55 +3481,62 @@ 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. * appended before the suffix. * @param part_size - * The maximum size per part, in bytes. It is not guaranteed that this - * will really be the maximum size per part, because some file resources in - * the WIM may be larger than this size, and the WIM file format provides - * no way to split up file resources among multiple WIMs. + * The maximum size per part, in bytes. Unfortunately, it is not + * guaranteed that this will really be the maximum size per part, because + * some file resources in the WIM may be larger than this size, and the WIM + * file format provides no way to split up file resources among multiple + * WIMs. * @param write_flags - * ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY if integrity tables are to be - * included in the split WIM parts. + * Bitwise OR of relevant flags prefixed with @c WIMLIB_WRITE_FLAG. These + * flags will be used to write each split WIM part. Specify 0 here to get + * the default behavior. * @param progress_func * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * progress of the current operation + * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and + * ::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). * - * @return 0 on success; nonzero on error. This function may return 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 that can be returned by wimlib_write() as well as the following error + * codes: * - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is not part 1 of a stand-alone WIM. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a swm_name was @c NULL, or @a part_size was 0. + * @p swm_name was not a nonempty string, or @p part_size was 0. * * Note: the WIM's uncompressed and compressed resources are not checksummed * when they are copied from the joined WIM to the split WIM parts, nor are - * compressed resources re-compressed. + * compressed resources re-compressed (unless explicitly requested with + * ::WIMLIB_WRITE_FLAG_RECOMPRESS). */ extern int wimlib_split(WIMStruct *wim, const wimlib_tchar *swm_name, - size_t part_size, + uint64_t part_size, int write_flags, 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. @@ -2477,7 +3550,8 @@ wimlib_split(WIMStruct *wim, * mounts. * @param progress_func * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * progress of the current operation. Currently, only + * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS will be sent. * * @return 0 on success; nonzero on error. * @@ -2509,7 +3583,7 @@ wimlib_split(WIMStruct *wim, * original WIM file. * @retval ::WIMLIB_ERR_UNSUPPORTED * Mounting is not supported, either because the platform is Windows, or - * because the platform is UNIX and wimlib was compiled with @c + * because the platform is UNIX-like and wimlib was compiled with @c * --without-fuse. * @retval ::WIMLIB_ERR_WRITE * A write error occurred when the filesystem daemon was writing to the new @@ -2522,6 +3596,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 @@ -2533,7 +3609,7 @@ wimlib_unmount_image(const wimlib_tchar *dir, * An array of ::wimlib_update_command's that specify the update operations * to perform. * @param num_cmds - * Number of commands in @a cmds. + * Number of commands in @p cmds. * @param update_flags * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0. * @param progress_func @@ -2544,34 +3620,26 @@ wimlib_unmount_image(const wimlib_tchar *dir, * update commands may have been executed. No individual update command will * have been partially executed. Possible error codes include: * - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress the metadata resource from @a image in @a wim. * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG * The capture configuration structure specified for an add command was * invalid. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image did not specify a single, existing image in @a wim. + * @p image did not specify a single, existing image in @p wim. * @retval ::WIMLIB_ERR_INVALID_OVERLAY * Attempted to perform an add command that conflicted with previously * existing files in the WIM when an overlay was attempted. * @retval ::WIMLIB_ERR_INVALID_PARAM * An unknown operation type was specified in the update commands; or, * attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set - * in the @a add_flags, but the same image had previously already been + * in the @p add_flags, but the same image had previously already been * added from a NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and - * ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @a add_flags for one add + * ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add * command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were - * specified in the @a add_flags for an add command in which @a + * specified in the @p add_flags for an add command in which @p * wim_target_path was not the root directory of the WIM image. * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA * (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 @a image in @a wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for image @a image in @a 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 @@ -2598,30 +3666,39 @@ 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 @a image in @a 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, such as a regular file, directory, symbolic link, - * or (on Windows) a reparse point. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @a wim is part of a split WIM. Updating a split WIM is unsupported. * @retval ::WIMLIB_ERR_STAT * While executing an add command, failed to get attributes for a file or * directory. * @retval ::WIMLIB_ERR_UNSUPPORTED - * ::WIMLIB_ADD_FLAG_NTFS was specified in the @a add_flags for an update + * ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update * command, but wimlib was configured with the @c --without-ntfs-3g flag; * or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA - * or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @a + * 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, @@ -2632,72 +3709,83 @@ 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 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 the flags ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY, - * ::WIMLIB_WRITE_FLAG_RECOMPRESS, ::WIMLIB_WRITE_FLAG_FSYNC, and/or - * ::WIMLIB_WRITE_FLAG_SOFT_DELETE. + * Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG. * @param num_threads * Number of threads to use for compressing data. If 0, the number of * threads is taken to be the number of online processors. Note: if no * data compression needs to be done, no additional threads will be created * regardless of this parameter (e.g. if writing an uncompressed WIM, or * exporting an image from a compressed WIM to another WIM of the same - * compression type without ::WIMLIB_WRITE_FLAG_RECOMPRESS specified in @a + * compression type without ::WIMLIB_WRITE_FLAG_RECOMPRESS specified in @p * write_flags). * @param progress_func * If non-NULL, a function that will be called periodically with the - * progress of the current operation. + * progress of the current operation. The possible messages are + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, + * ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, and + * ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. * * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress a metadata or file resource in @a wim. - * @retval ::WIMLIB_ERR_INVALID_DENTRY - * A directory entry in the metadata resource for @a image in @a wim is - * invalid. + * * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @a image does not specify a single existing image in @a wim, and is not + * @p image does not specify a single existing image in @p wim, and is not * ::WIMLIB_ALL_IMAGES. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH * A file that had previously been scanned for inclusion in the WIM by * wimlib_add_image() was concurrently modified, so it failed the SHA1 * message digest check. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a path was @c NULL. - * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE - * The metadata resource for @a image in @a wim is invalid. - * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA - * The security data for @a image in @a wim is invalid. + * @p path was @c NULL. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_OPEN - * Failed to open @a path for writing, or some file resources in @a - * wim refer to files in the outside filesystem, and one of these files - * could not be opened for reading. + * Failed to open @p path for writing, or some file resources in @p wim + * refer to files in the outside filesystem, and one of these files could + * not be opened for reading. * @retval ::WIMLIB_ERR_READ * An error occurred when trying to read data from the WIM file associated - * with @a wim, or some file resources in @a wim refer to files in the + * 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 - * @a wim is part of a split WIM. You may not call this function on a - * split 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 at @a - * path. + * 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, @@ -2708,6 +3796,36 @@ 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 + * write_flags. This can, for example, allow capturing a WIM image and + * streaming it over the network. See the documentation for + * ::WIMLIB_WRITE_FLAG_PIPABLE for more information about pipable WIMs. + * + * The file descriptor @p fd will @b not be closed when the write is complete; + * the calling code is responsible for this. + * + * Returns 0 on success; nonzero on failure. The possible error codes include + * those that can be returned by wimlib_write() as well as the following: + * + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p fd was not seekable, but ::WIMLIB_WRITE_FLAG_PIPABLE was not + * specified in @p write_flags. + */ +extern int +wimlib_write_to_fd(WIMStruct *wim, + int fd, + int image, + int write_flags, + unsigned num_threads, + wimlib_progress_func_t progress_func); + +/** + * @ingroup G_compression + * * This function is equivalent to wimlib_lzx_compress(), but instead compresses * the data using "XPRESS" compression. */ @@ -2715,6 +3833,8 @@ extern unsigned wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out); /** + * @ingroup G_compression + * * This function is equivalent to wimlib_lzx_decompress(), but instead assumes * the data is compressed using "XPRESS" compression. */ @@ -2722,4 +3842,8 @@ extern int wimlib_xpress_decompress(const void *compressed_data, unsigned compressed_len, void *uncompressed_data, unsigned uncompressed_len); +#ifdef __cplusplus +} +#endif + #endif /* _WIMLIB_H */