X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=7e89f4a7676076027da8c4a87fdba6f54bd3fff3;hp=acc9c0c6e1dd41d519786772c7dccfb948b2535c;hb=6f1261c57e213d6f12cb7aa8f858f2971bee687e;hpb=af1a9f0d89f9d4428776238a561a6a5b6900f2d4 diff --git a/include/wimlib.h b/include/wimlib.h index acc9c0c6..7e89f4a7 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,76 +28,118 @@ * along with wimlib; if not, see http://www.gnu.org/licenses/. */ -/** \mainpage +/** + * @mainpage * - * \section intro Introduction + * @section sec_intro Introduction * - * This is the documentation for the library interface of wimlib 1.5.0, a C + * This is the documentation for the library interface of wimlib 1.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 or manual pages. * - * \section starting Getting Started + * @section sec_installing_and_compiling Installing and Compiling * * wimlib uses the GNU autotools, so, on UNIX-like systems, it should be easy to * install with configure && make && sudo make install; however, - * please see the README for more information about installing it. To use - * wimlib in a program after installing it, include @c wimlib.h and link your - * program with @c -lwim. + * please see the README for more information about installing it. + * + * To use wimlib in your program after installing it, include wimlib.h and link + * your program with @c -lwim. + * + * As of wimlib 1.5.0, wimlib.h is also compatible with C++. + * + * Note: before calling any other function declared in wimlib.h, + * wimlib_global_init() can (and in some cases, must) be called. See its + * documentation for more details. + * + * @section sec_basic_wim_handling_concepts Basic WIM handling concepts + * + * wimlib wraps up a WIM file in an opaque ::WIMStruct structure. There are + * two ways to create such a structure: wimlib_open_wim(), which opens a WIM + * file and creates a ::WIMStruct representing it, and wimlib_create_new_wim(), + * which creates a new ::WIMStruct that initially contains no images and does + * not yet have a backing on-disk file. See @ref G_creating_and_opening_wims + * for more details. + * + * A WIM file, represented by a ::WIMStruct, contains zero or more images. + * Images can be extracted (or "applied") using wimlib_extract_image(), added + * (or "captured" or "appended") using wimlib_add_image(), deleted using + * wimlib_delete_image(), exported using wimlib_export_image(), and updated or + * modified using wimlib_update_image(). However, changes made to a WIM + * represented by a ::WIMStruct have no persistent effect until the WIM is + * actually written to an on-disk file. This can be done using wimlib_write(), + * but if the WIM was originally opened using wimlib_open_wim(), then + * wimlib_overwrite() can be used instead. See @ref G_extracting_wims, @ref + * G_modifying_wims, and @ref G_writing_and_overwriting_wims for more details. + * + * Note that with this ::WIMStruct abstraction, performing many tasks on WIM + * files is a multi-step process. For example, to add, or "append" an image to + * an existing stand-alone WIM file in a way similar to wimlib-imagex + * append, you must call the following functions: + * + * 1. wimlib_open_wim() + * 2. wimlib_add_image() + * 3. wimlib_overwrite() + * + * This design is very much on purpose as it makes the library more useful in + * general by allowing functions to be composed in different ways. For example, + * you can make multiple changes to a WIM and commit them all to the underlying + * file in only one overwrite operation, which is more efficient. + * + * @section sec_cleaning_up Cleaning up + * + * After you are done with any ::WIMStruct, you can call wimlib_free() to free + * all resources associated with it. Also, when you are completely done with + * using wimlib in your program, you can call wimlib_global_cleanup() to free + * any other resources allocated by the library. + * + * @section sec_error_handling Error Handling + * + * Most functions in wimlib return 0 on success and a positive error code on + * failure. Use wimlib_get_error_string() to get a string that describes an + * error code. wimlib also can print error messages to standard error itself + * when an error happens, and these may be more informative than the error code; + * to enable this, call wimlib_set_print_errors(). Please note that this is for + * convenience only, and some errors can occur without a message being printed. + * Currently, error messages and strings (as well as all documentation, for that + * matter) are only available in English. + * + * @section sec_encodings Locales and character encodings * - * wimlib wraps up a WIM file in an opaque ::WIMStruct structure. A ::WIMStruct - * may represent either a stand-alone WIM or one part of a split WIM. + * To support Windows as well as UNIX-like systems, wimlib's API typically takes + * and returns strings of ::wimlib_tchar, which are in a platform-dependent + * encoding. * - * All functions in wimlib's public API are prefixed with @c wimlib. Most - * return 0 on success and a positive error code on failure. Use - * wimlib_get_error_string() to get a string that describes an error code. - * wimlib also can print error messages itself when an error happens, and these - * may be more informative than the error code; to enable this, call - * wimlib_set_print_errors(). Please note that this is for convenience only, - * and some errors can occur without a message being printed. + * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t", + * and the encoding is UTF-16LE. * - * First before calling any other functions, you should call - * wimlib_global_init() to initialize the library. + * On UNIX-like systems, each ::wimlib_tchar is 1 byte and is simply a "char", + * and the encoding is the locale-dependent multibyte encoding. I recommend you + * set your locale to a UTF-8 capable locale to avoid any issues. Also, by + * default, wimlib on UNIX will assume the locale is UTF-8 capable unless you + * call wimlib_global_init() after having set your desired locale. * - * To open an existing WIM, use wimlib_open_wim(). + * @section sec_advanced Additional information and features * - * To create a new WIM that initially contains no images, use - * wimlib_create_new_wim(). * - * To add an image to a WIM file from a directory tree on your filesystem, call - * wimlib_add_image(). This can be done with a ::WIMStruct gotten from - * wimlib_open_wim() or from wimlib_create_new_wim(). On UNIX-like systems, - * wimlib_add_image() can also capture a WIM image directly from a block device - * containing a NTFS filesystem. + * @subsection subsec_mounting_wim_images Mounting WIM images * - * To extract an image from a WIM file, call wimlib_extract_image(). This can - * be done either to a directory, or, on UNIX-like systems, directly to a block - * device containing a NTFS filesystem. + * See @ref G_mounting_wim_images. * - * To extract individual files or directories from a WIM image, rather than a - * full image, call wimlib_extract_files(). + * @subsection subsec_progress_functions Progress Messages * - * To programatically make changes to a WIM image without mounting it, call - * wimlib_update_image(). + * See @ref G_progress. * - * On UNIX-like systems supporting FUSE (such as Linux), wimlib supports - * mounting WIM files either read-only or read-write. Mounting is done using - * wimlib_mount_image() and unmounting is done using wimlib_unmount_image(). - * Mounting can be done without root privileges because it is implemented using - * FUSE (Filesystem in Userspace). If wimlib is compiled with the - * --without-fuse flag, these functions will be available but will - * fail with ::WIMLIB_ERR_UNSUPPORTED. - * - * After creating or modifying a WIM file, you can write it to a file using - * wimlib_write(). Alternatively, if the WIM was originally read from a file - * (using wimlib_open_wim() rather than wimlib_create_new_wim()), you can use - * wimlib_overwrite() to overwrite the original file. Still alternatively, you - * can write a WIM directly to a file descriptor by calling wimlib_write_to_fd() - * instead. - * - * wimlib supports a special "pipable" WIM format (which unfortunately is @b not - * compatible with Microsoft's software). To create a pipable WIM, call + * @subsection subsec_non_standalone_wims Non-standalone WIMs + * + * See @ref G_nonstandalone_wims. + * + * @subsection subsec_pipable_wims Pipable WIMs + * + * wimlib supports a special "pipable" WIM format which unfortunately is @b not + * compatible with Microsoft's software. To create a pipable WIM, call * wimlib_write(), wimlib_write_to_fd(), or wimlib_overwrite() with * ::WIMLIB_WRITE_FLAG_PIPABLE specified. Pipable WIMs are pipable in both * directions, so wimlib_write_to_fd() can be used to write a pipable WIM to a @@ -105,24 +148,14 @@ * s using a seekable file descriptor using the regular function calls (e.g. * wimlib_open_wim(), wimlib_extract_image()). * - * Please note: merely by calling wimlib_add_image() or many of the other - * functions in this library that operate on ::WIMStruct's, you are @b not - * modifying the WIM file on disk. Changes are not saved until you explicitly - * call wimlib_write() or wimlib_overwrite(). - * - * After you are done with the WIM file, use wimlib_free() to free all memory - * associated with a ::WIMStruct and close all files associated with it. + * See the documentation for the --pipable flag of wimlib-imagex + * capture for more information about pipable WIMs. * - * When you are completely done with using wimlib in your program, you should - * call wimlib_global_cleanup(). + * @subsection subsec_thread_safety Thread Safety * - * 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). - * - * wimlib is thread-safe as long as different ::WIMStruct's are used, except for - * the following exceptions: + * wimlib is thread-safe, with the following exceptions: + * - Different threads cannot operate on the same ::WIMStruct at the same time; + * they must use different ::WIMStruct's. * - You must call wimlib_global_init() in one thread before calling any other * functions. * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally. @@ -131,22 +164,7 @@ * does so for the first time. This includes changing the working directory * to the root directory. * - * \section encodings Locales and character encodings - * - * To support Windows as well as UNIX-like systems, wimlib's API typically takes - * and returns strings of ::wimlib_tchar, which are in a platform-dependent - * encoding. - * - * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t", - * and the encoding is UTF-16LE. - * - * On UNIX-like systems, each ::wimlib_tchar is 1 byte and is simply a "char", - * and the encoding is the locale-dependent multibyte encoding. I recommend you - * set your locale to a UTF-8 capable locale to avoid any issues. Also, by - * default, wimlib on UNIX will assume the locale is UTF-8 capable unless you - * call wimlib_global_init() after having set your desired locale. - * - * \section Limitations + * @subsection subsec_limitations Limitations * * This section documents some technical limitations of wimlib not already * documented in the man page for @b wimlib-imagex. @@ -158,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 @@ -171,14 +345,25 @@ #include #include -/** Major version of the library (for example, the 1 in 1.2.5). */ +/** @ingroup G_general + * @{ */ + +/** Major version of the library (for example, the 1 in 1.2.5). */ #define WIMLIB_MAJOR_VERSION 1 /** Minor version of the library (for example, the 2 in 1.2.5). */ #define WIMLIB_MINOR_VERSION 5 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 0 +#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 @@ -192,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; @@ -201,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 @@ -240,6 +427,10 @@ 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 { @@ -593,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 { @@ -675,6 +870,10 @@ struct wimlib_capture_config { * reparse-point fixups by default when capturing or applying WIM images. */ #define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 +/** @} */ +/** @ingroup G_wim_information + * @{ */ + /** General information about a WIM file. */ struct wimlib_wim_info { @@ -695,12 +894,12 @@ struct wimlib_wim_info { /** Chunk size used for compression. */ uint32_t chunk_size; - /** 1-based index of this part within a split WIM, or 1 if the WIM is - * standalone. */ + /** For split WIMs, the 1-based index of this part within the split WIM; + * otherwise 1. */ uint16_t part_number; - /** Total number of parts in the split WIM, or 1 if the WIM is - * standalone. */ + /** For split WIMs, the total number of parts in the split WIM; + * otherwise 1. */ uint16_t total_parts; /** One of the ::wimlib_compression_type values that specifies the @@ -778,7 +977,14 @@ struct wimlib_resource_entry { uint32_t is_free : 1; uint32_t is_spanned : 1; - uint32_t reserved_flags : 28; + + /** 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]; }; @@ -900,14 +1106,6 @@ typedef int (*wimlib_iterate_dir_tree_callback_t)(const struct wimlib_dir_entry typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resource_entry *resource, void *user_ctx); -/** - * @name Directory tree iteration flags - * - * The following flags can be passed to wimlib_iterate_dir_tree(). - * - * @{ - */ - /** For wimlib_iterate_dir_tree(): Iterate recursively on children rather than * just on the specified path. */ #define WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001 @@ -916,17 +1114,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * itself; only its children (in the case of a non-empty directory) */ #define WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002 +/** Return ::WIMLIB_ERR_RESOURCE_NOT_FOUND if any resources needed to fill in + * the ::wimlib_resource_entry's for the iteration cannot be found in the lookup + * table of the ::WIMStruct. The default behavior without this flag is to fill + * in the SHA1 message digest of the ::wimlib_resource_entry and set the @ref + * wimlib_resource_entry::is_missing "is_missing" flag. */ +#define WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED 0x00000004 -/** - * @name Add flags - * - * The following flags can be passed to wimlib_add_image(), - * wimlib_add_image_multisource(), and add commands passed to - * wimlib_update_image(). - * - * @{ - */ +/** @} */ +/** @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 @@ -1025,14 +1223,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE #define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG -/** - * @name Delete flags - * - * The following flags can be specified in delete commands passed to - * wimlib_update_image(). - * - * @{ - */ +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ /** Do not issue an error if the path to delete does not exist. */ #define WIMLIB_DELETE_FLAG_FORCE 0x00000001 @@ -1041,13 +1234,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * issued if the path to delete is a directory. */ #define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002 -/** - * @name Export flags - * - * The following flags can be passed to wimlib_export_image(). - * - * @{ - */ +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ /** * If a single image is being exported, mark it bootable in the destination WIM. @@ -1065,14 +1254,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Give the exported image(s) no descriptions. */ #define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004 -/** - * @name Extract flags - * - * The following flags can be passed to wimlib_extract_image(), - * wimlib_extract_files(), and wimlib_extract_image_from_pipe(). - * - * @{ - */ +/** @} */ +/** @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; @@ -1158,13 +1342,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * behavior is currently less than satisfactory. Do not use (yet). */ #define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 -/** - * @name Mount flags - * - * The following flags can be passed to wimlib_mount_image(). - * - * @{ - */ +/** @} */ +/** @ingroup G_mounting_wim_images + * @{ */ /** Mount the WIM image read-write rather than the default of read-only. */ #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 @@ -1191,13 +1371,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * allow_other option to FUSE mount) */ #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 -/** - * @name Open flags - * - * The following flags can be passed to wimlib_open_wim() and several other - * functions such as wimlib_join(). - * @{ - */ +/** @} */ +/** @ingroup G_creating_and_opening_wims + * @{ */ /** Verify the WIM contents against the WIM's integrity table, if present. This * causes the raw data of the WIM file, divided into 10 MB chunks, to be @@ -1207,10 +1383,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * 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. Programs must - * specify this flag if they intend to open part of a split WIM, rather than - * only supporting standalone WIMs. */ -#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 @@ -1220,12 +1396,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * an error sooner rather than later. */ #define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004 -/** - * @name Unmount flags - * - * The following flags can be passed to wimlib_unmount_image(). - * @{ - */ +/** @} */ +/** @ingroup G_mounting_wim_images + * @{ */ /** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ #define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001 @@ -1243,24 +1416,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Do a "lazy" unmount (detach filesystem immediately, even if busy). */ #define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010 -/** - * @name Update flags - * - * The following flags can be passed to wimlib_update_image(). - * @{ - */ +/** @} */ +/** @ingroup G_modifying_wims + * @{ */ /** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */ #define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001 -/** - * @name Write flags - * - * The following flags can be passed to wimlib_write(), wimlib_overwrite(), - * wimlib_write_to_fd(), and several other functions such as wimlib_join(). - * @{ - */ +/** @} */ +/** @ingroup G_writing_and_overwriting_wims + * @{ */ /** Include an integrity table in the WIM. * @@ -1335,12 +1501,16 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * already implied for wimlib_overwrite(). */ #define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 -/** - * @name Init flags - * - * The following flags can be passed to wimlib_global_init(). - * @{ - */ +/** 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 + * @{ */ /** 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 @@ -1370,13 +1540,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008 -/** - * @name Resource reference flags - * - * The following flags can be passed to wimlib_reference_resource_files() and - * wimlib_reference_resources(). - * @{ - */ +/** @} */ +/** @ingroup G_nonstandalone_wims + * @{ */ /** wimlib_reference_resource_files() only: Enable shell-style filename * globbing. */ @@ -1390,71 +1556,86 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * ::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, +}; + +/** 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 (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; - } 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. @@ -1468,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. * @@ -1508,6 +1784,7 @@ enum wimlib_error_code { 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, @@ -1537,7 +1814,6 @@ enum wimlib_error_code { WIMLIB_ERR_SET_SHORT_NAME, WIMLIB_ERR_SET_TIMESTAMPS, WIMLIB_ERR_SPLIT_INVALID, - WIMLIB_ERR_SPLIT_UNSUPPORTED, WIMLIB_ERR_STAT, WIMLIB_ERR_TIMEOUT, WIMLIB_ERR_UNEXPECTED_END_OF_FILE, @@ -1559,6 +1835,8 @@ 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. After @@ -1595,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 @@ -1650,7 +1930,10 @@ 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 @p sources and @p num_sources parameters instead of the @p * source parameter of wimlib_add_image(). The rest of the parameters are the @@ -1677,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 @@ -1702,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 @@ -1741,6 +2028,8 @@ 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 @@ -1759,8 +2048,12 @@ wimlib_delete_image(WIMStruct *wim, int image); * dest_wim (if any) until wimlib_write() or wimlib_overwrite() is called. * * @param src_wim - * Pointer to the ::WIMStruct for a stand-alone WIM or part 1 of a split - * WIM that contains the image(s) being exported. + * The WIM from which to export the images, specified as a pointer to the + * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a + * split WIM. In the case of a WIM file that is not standalone, this + * ::WIMStruct must have had any needed external resources previously + * referenced using wimlib_reference_resources() or + * wimlib_reference_resource_files(). * @param src_image * The image to export from @p src_wim, as either a 1-based image index to * export a single image, or ::WIMLIB_ALL_IMAGES to export all images. @@ -1830,6 +2123,8 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, 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 @@ -1837,8 +2132,12 @@ 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 @p wim from which the files or @@ -1891,8 +2190,10 @@ wimlib_extract_files(WIMStruct *wim, wimlib_progress_func_t progress_func); /** - * Extracts an image, or all images, from a standalone or split WIM file to a - * directory or directly to a NTFS volume image. + * @ingroup G_extracting_wims + * + * Extracts an image, or all images, from a WIM to a directory or directly to a + * NTFS volume image. * * The exact behavior of how wimlib extracts files from a WIM image is * controllable by the @p extract_flags parameter, but there also are @@ -1908,8 +2209,12 @@ 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 @@ -2012,6 +2317,8 @@ wimlib_extract_image(WIMStruct *wim, int image, 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. * @@ -2062,12 +2369,14 @@ wimlib_extract_image_from_pipe(int pipe_fd, 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. * * @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. * @@ -2085,6 +2394,8 @@ extern int wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); /** + * @ingroup G_general + * * Frees all memory allocated for a WIMStruct and closes all files associated * with it. * @@ -2097,6 +2408,8 @@ extern void wimlib_free(WIMStruct *wim); /** + * @ingroup G_general + * * Converts a ::wimlib_compression_type value into a string. * * @param ctype @@ -2111,6 +2424,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 @@ -2124,11 +2439,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. * @@ -2143,11 +2460,13 @@ extern const wimlib_tchar * wimlib_get_image_description(const WIMStruct *wim, int image); /** + * @ingroup G_wim_information + * * Returns the name of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or a split WIM part. + * Pointer to the ::WIMStruct for a WIM file that does not necessarily have + * to be standalone (e.g. it could be part of a split WIM). * @param image * The number of the image, numbered starting at 1. * @@ -2163,11 +2482,13 @@ wimlib_get_image_name(const WIMStruct *wim, int image); /** + * @ingroup G_wim_information + * * Get basic information about a WIM file. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be for either a - * standalone WIM or part of a split WIM. + * Pointer to the ::WIMStruct for a WIM file that does not necessarily have + * to be standalone (e.g. it could be part of a split WIM). * @param info * A ::wimlib_wim_info structure that will be filled in with information * about the WIM file. @@ -2178,10 +2499,12 @@ extern int wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); /** + * @ingroup G_general + * * Initialization function for wimlib. Call before using any other wimlib - * function except wimlib_set_print_errors(). (However, currently this is not - * strictly necessary and it will be called automatically if not done manually, - * but you should not rely on this behavior.) + * function except wimlib_set_print_errors(). If not done manually, this + * function will be called automatically with @p init_flags set to + * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. * * @param init_flags * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. @@ -2198,6 +2521,8 @@ extern int wimlib_global_init(int init_flags); /** + * @ingroup G_general + * * Cleanup function for wimlib. You are not required to call this function, but * it will release any global resources allocated by the library. */ @@ -2205,6 +2530,8 @@ extern void wimlib_global_cleanup(void); /** + * @ingroup G_wim_information + * * Determines if an image name is already used by some image in the WIM. * * @param wim @@ -2221,14 +2548,22 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); /** + * @ingroup G_wim_information + * * Iterate through a file or directory tree in the WIM image. By specifying * appropriate flags and a callback function, you can get the attributes of a * file in the WIM, get a directory listing, or even get a listing of the entire * WIM image. * * @param wim - * Pointer to the ::WIMStruct for a standalone WIM file, or part 1 of a - * split WIM. + * The WIM containing the image(s) over which to iterate, specified as a + * pointer to the ::WIMStruct for a standalone WIM file, a delta WIM file, + * or part 1 of a split WIM. In the case of a WIM file that is not + * standalone, this ::WIMStruct should have had any needed external + * resources previously referenced using wimlib_reference_resources() or + * wimlib_reference_resource_files(). If not, see + * ::WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED for information about + * the behavior when resources are missing. * * @param image * The 1-based number of the image in @p wim that contains the files or @@ -2239,8 +2574,7 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * Path in the WIM image at which to do the iteration. * * @param flags - * Bitwise OR of ::WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE and/or - * ::WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN. + * Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG. * * @param cb * A callback function that will receive each directory entry. @@ -2271,14 +2605,21 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, wimlib_iterate_dir_tree_callback_t cb, void *user_ctx); /** + * @ingroup G_wim_information + * * Iterate through the lookup table of a WIM file. This can be used to directly - * get a listing of the unique resources contained in a WIM file. Both file - * resources and metadata resources are included. + * get a listing of the unique resources contained in a WIM file over all + * images. Both file resources and metadata resources are included. However, + * only resources actually included in the file represented by @a wim, plus + * explicitly referenced external resources (via wimlib_reference_resources() or + * wimlib_reference_resource_files()) are included in the iteration. For + * example, if @p wim represents just one part of a split WIM, then only + * resources in that part will be included, unless other resources were + * explicitly referenced. * * @param wim - * Pointer to the ::WIMStruct of a standalone WIM file or a split WIM part. - * Note: metadata resources will only be included if the WIM is standalone - * or the first part of the split WIM. + * Pointer to the ::WIMStruct for a WIM file that does not necessarily have + * to be standalone (e.g. it could be part of a split WIM). * * @param flags * Reserved; set to 0. @@ -2299,6 +2640,8 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, void *user_ctx); /** + * @ingroup G_nonstandalone_wims + * * Joins a split WIM into a stand-alone one-part WIM. * * @param swms @@ -2309,8 +2652,7 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * Number of filenames in @p swms. * @param swm_open_flags * Open flags for the split WIM parts (e.g. - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). Note: ::WIMLIB_OPEN_FLAG_SPLIT_OK - * is automatically added to the value specified here. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). * @param wim_write_flags * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will * be used to write the joined WIM. @@ -2329,10 +2671,12 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * the parts of the original WIM, there are duplicate parts, or not all the * parts have the same GUID and compression type. * - * Note: wimlib_export_image() can provide similar functionality to - * wimlib_join(), since it is possible to export all images from a split WIM - * into a new ::WIMStruct, then write it. However, wimlib_join() may have - * better performance than this method. + * 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, @@ -2343,6 +2687,8 @@ 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 should only be used by @@ -2367,6 +2713,58 @@ extern unsigned wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out); /** + * @ingroup G_compression + * + * Equivalent to wimlib_lzx_compress(), but uses the specified compression + * context, allocated by wimlib_lzx_alloc_context(). + */ +extern unsigned +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 @@ -2397,6 +2795,8 @@ wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, /** + * @ingroup G_mounting_wim_images + * * Mounts an image in a WIM file on a directory read-only or read-write. * * As this is implemented using FUSE (Filesystme in UserSpacE), this is not @@ -2482,6 +2882,8 @@ wimlib_mount_image(WIMStruct *wim, const wimlib_tchar *staging_dir); /** + * @ingroup G_creating_and_opening_wims + * * Opens a WIM file and creates a ::WIMStruct for it. * * @param wim_file @@ -2530,6 +2932,9 @@ wimlib_mount_image(WIMStruct *wim, * 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 @@ -2538,9 +2943,6 @@ wimlib_mount_image(WIMStruct *wim, * Failed to open the file @p wim_file for reading. * @retval ::WIMLIB_ERR_READ * Failed to read data from @p wim_file. - * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED - * @p wim_file is a split WIM, but ::WIMLIB_OPEN_FLAG_SPLIT_OK was not - * specified in @p open_flags. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE * Unexpected end-of-file while reading data from @p wim_file. * @retval ::WIMLIB_ERR_UNKNOWN_VERSION @@ -2560,6 +2962,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(). @@ -2637,6 +3041,8 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads, wimlib_progress_func_t progress_func); /** + * @ingroup G_wim_information + * * Prints information about one image, or all images, contained in a WIM. * * @param wim @@ -2654,6 +3060,8 @@ extern void wimlib_print_available_images(const WIMStruct *wim, int image); /** + * @ingroup G_wim_information + * * Deprecated in favor of wimlib_get_wim_info(), which provides the information * in a way that can be accessed programatically. */ @@ -2661,6 +3069,8 @@ extern void wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated; /** + * @ingroup G_wim_information + * * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the * information in a way that can be accessed programatically. */ @@ -2668,6 +3078,8 @@ extern int wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; /** + * @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) @@ -2694,8 +3106,6 @@ wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated; * @param open_flags * Additional open flags, such as ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY, to * pass to internal calls to wimlib_open_wim() on the reference files. - * Note: ::WIMLIB_OPEN_FLAG_SPLIT_OK will be supplied regardless of this - * parameter. * @param progress_func * Passed to internal calls to wimlib_open_wim() on the reference files. * @@ -2722,6 +3132,8 @@ wimlib_reference_resource_files(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @ingroup G_nonstandalone_wims + * * Similar to wimlib_reference_resource_files(), but operates at a lower level * where the caller must open the ::WIMStruct for each referenced file itself. * @@ -2754,6 +3166,8 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, unsigned num_resource_wims, int ref_flags); /** + * @ingroup G_modifying_wims + * * Declares that a newly added image is mostly the same as a prior image, but * captured at a later point in time, possibly with some modifications in the * intervening time. This is designed to be used in incremental backups of the @@ -2827,11 +3241,13 @@ wimlib_reference_template_image(WIMStruct *wim, int new_image, int flags, wimlib_progress_func_t progress_func); /** + * @ingroup G_wim_information + * * Translates a string specifying the name or number of an image in the WIM into * the number of the image. The images are numbered starting at 1. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct for a WIM. * @param image_name_or_num * A string specifying the name or number of an image in the WIM. If it * parses to a positive integer, this integer is taken to specify the @@ -2857,12 +3273,12 @@ wimlib_resolve_image(WIMStruct *wim, const wimlib_tchar *image_name_or_num); /** + * @ingroup G_modifying_wims + * * Changes the description of an image in the WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM; however, you should set the same - * description on all parts of a split WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image * The number of the image for which to change the description. * @param description @@ -2884,10 +3300,12 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, const wimlib_tchar *description); /** + * @ingroup G_modifying_wims + * * Set basic information about a WIM. * * @param wim - * A WIMStruct for a standalone WIM file. + * Pointer to the ::WIMStruct for a WIM. * @param info * A struct ::wimlib_wim_info that contains the information to set. Only * the information explicitly specified in the @p which flags need be @@ -2914,13 +3332,13 @@ wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, int which); /** + * @ingroup G_modifying_wims + * * Changes what is written in the \ element in the WIM XML data * (something like "Core" or "Ultimate") * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM; however, you should set the same - * \ element on all parts of a split WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image * The number of the image for which to change the description. * @param flags @@ -2940,12 +3358,12 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** + * @ingroup G_modifying_wims + * * Changes the name of an image in the WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. It may be either a - * standalone WIM or part of a split WIM; however, you should set the same - * name on all parts of a split WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image * The number of the image for which to change the name. * @param name @@ -2968,6 +3386,8 @@ 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. @@ -3001,6 +3421,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 @@ -3026,11 +3448,12 @@ extern int wimlib_set_print_errors(bool show_messages); /** + * @ingroup G_nonstandalone_wims + * * Splits a WIM into multiple parts. * * @param wim - * The ::WIMStruct for the WIM to split. It must be a standalone, one-part - * WIM. + * The ::WIMStruct for the WIM to split. * @param swm_name * Name of the SWM file to create. This will be the name of the first * part. The other parts will have the same name with 2, 3, 4, ..., etc. @@ -3071,14 +3494,16 @@ wimlib_split(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @ingroup G_mounting_wim_images + * * Unmounts a WIM image that was mounted using wimlib_mount_image(). * * The image to unmount is specified by the path to the mountpoint, not the * original ::WIMStruct passed to wimlib_mount_image(), which should not be * touched and also may have been allocated in a different process. * - * To unmount the image, the thread calling this function communicates with the - * thread that is managing the mounted WIM image. This function blocks until it + * To unmount the image, the process calling this function communicates with the + * process that is managing the mounted WIM image. This function blocks until it * is known whether the unmount succeeded or failed. In the case of a * read-write mounted WIM, the unmount is not considered to have succeeded until * all changes have been saved to the underlying WIM file. @@ -3138,6 +3563,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 @@ -3249,20 +3676,29 @@ wimlib_update_image(WIMStruct *wim, wimlib_progress_func_t progress_func); /** - * Writes a standalone WIM to a file. + * @ingroup G_writing_and_overwriting_wims + * + * Writes a WIM to a file. * * This brings in resources from any external locations, such as directory trees * or NTFS volumes scanned with wimlib_add_image(), or other WIM files via * wimlib_export_image(), and incorporates them into a new on-disk WIM file. * + * By default, the new WIM file is written as stand-alone. Using the + * ::WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS flag, a "delta" WIM can be written + * instead. However, this function cannot directly write a "split" WIM; use + * wimlib_split() for that. + * * @param wim * Pointer to the ::WIMStruct for a WIM. There may have been in-memory * changes made to it, which are then reflected in the output file. * @param path * The path to the file to write the WIM to. * @param image - * The 1-based index of the image inside the WIM to write. Use - * ::WIMLIB_ALL_IMAGES to include all images. + * Normally, specify ::WIMLIB_ALL_IMAGES here. This indicates that all + * images are to be included in the new on-disk WIM file. If for some + * reason you only want to include a single image, specify the index of + * that image instead. * @param write_flags * Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG. * @param num_threads @@ -3327,6 +3763,8 @@ wimlib_write(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @ingroup G_writing_and_overwriting_wims + * * Since wimlib v1.5.0: Same as wimlib_write(), but write the WIM directly to a * file descriptor, which need not be seekable if the write is done in a special * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p @@ -3353,6 +3791,8 @@ wimlib_write_to_fd(WIMStruct *wim, 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. */ @@ -3360,6 +3800,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. */ @@ -3367,4 +3809,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 */