X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=c0aaf13bf2f46bb103976c7a0d2c2adb08e5b1dd;hb=e014475fba041d91e3977fe64298c6a2cbe8195e;hp=faeb1a3e69b4ab171234abf0c66d3854f74ea690;hpb=df1050ef86e54f027912a15fe60bf67c8ab43d2c;p=wimlib diff --git a/include/wimlib.h b/include/wimlib.h index faeb1a3e..c0aaf13b 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,17 +28,18 @@ * along with wimlib; if not, see http://www.gnu.org/licenses/. */ -/** \mainpage +/** + * @mainpage * - * \section intro Introduction + * @section sec_intro Introduction * - * This is the documentation for the library interface of wimlib 1.5.0, a C + * This is the documentation for the library interface of wimlib 1.6.0, 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 installing_and_compiling Installing and Compiling + * @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, @@ -52,13 +54,14 @@ * wimlib_global_init() can (and in some cases, must) be called. See its * documentation for more details. * - * \section basic_wim_handling_concepts Basic WIM handling concepts + * @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. + * 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 @@ -68,7 +71,8 @@ * 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. + * 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 @@ -84,14 +88,14 @@ * 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 cleaning_up Cleaning up + * @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 error_handling Error Handling + * @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 @@ -102,7 +106,7 @@ * Currently, error messages and strings (as well as all documentation, for that * matter) are only available in English. * - * \section encodings Locales and character encodings + * @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 @@ -117,11 +121,90 @@ * 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 advanced Additional information and features + * @section sec_advanced Additional information and features + * + * + * @subsection subsec_mounting_wim_images Mounting WIM images + * + * See @ref G_mounting_wim_images. + * + * @subsection subsec_progress_functions Progress Messages + * + * See @ref G_progress. + * + * @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 + * 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()). + * + * See the documentation for the --pipable flag of wimlib-imagex + * capture for more information about pipable WIMs. + * + * @subsection subsec_thread_safety Thread Safety + * + * wimlib is thread-safe, with the following exceptions: + * - Different threads cannot operate on the same ::WIMStruct at the same time; + * they must use different ::WIMStruct's. + * - You must call wimlib_global_init() in one thread before calling any other + * functions. + * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally. + * - wimlib_mount_image(), while it can be used to mount multiple WIMs + * concurrently in the same process, will daemonize the entire process when it + * does so for the first time. This includes changing the working directory + * to the root directory. + * + * @subsection subsec_limitations Limitations + * + * This section documents some technical limitations of wimlib not already + * documented in the man page for @b wimlib-imagex. + * + * - The old WIM format from Vista pre-releases is not supported. + * - wimlib does not provide a clone of the @b PEImg tool, or the @b Dism + * functionality other than that already present in @b ImageX, that allows you + * to make certain Windows-specific modifications to a Windows PE image, such + * as adding a driver or Windows component. Such a tool could be implemented + * 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 * - * \subsection image_addition Image addition/capture + * @brief Make changes to a WIM. * - * As described in \ref basic_wim_handling_concepts, capturing a new WIM or + * @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 @@ -142,7 +225,31 @@ * Note that some details of how image addition/capture works are documented * more fully in the manual page for wimlib-imagex capture. * - * \subsection extraction Image extraction/application + * @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 @@ -155,31 +262,21 @@ * 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 pipable_wims. + * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a set + * of paths from a WIM image in a manner that may be easier to use than + * wimlib_extract_files(), and also allow wildcard patterns. + * + * 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 * - * \subsection non_standalone_wims Non-standalone WIMs - * - * Earlier it was stated that a ::WIMStruct represents a WIM file, but there's a - * bit more to it than that. Normally, WIM files are "standalone". However, - * WIM files can also be arranged in non-standalone ways, such as a set of - * on-disk files that together form a single "split WIM" or "delta WIM". Such - * arrangements are 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. - * - * \subsection 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 @@ -189,8 +286,11 @@ * 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 * - * \subsection progress_functions Progress Functions + * @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 @@ -199,55 +299,36 @@ * 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 * - * \subsection 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 - * 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()). - * - * See the documentation for the --pipable flag of wimlib-imagex - * capture for more information about pipable WIMs. - * - * \subsection thread_safety Thread Safety - * - * wimlib is thread-safe, with the following exceptions: - * - Different threads cannot operate on the same ::WIMStruct at the same time; - * they must use different ::WIMStruct's. - * - You must call wimlib_global_init() in one thread before calling any other - * functions. - * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally. - * - wimlib_mount_image(), while it can be used to mount multiple WIMs - * concurrently in the same process, will daemonize the entire process when it - * does so for the first time. This includes changing the working directory - * to the root directory. - * - * \subsection limitations Limitations + * @brief Write and overwrite on-disk WIM files. * - * This section documents some technical limitations of wimlib not already - * documented in the man page for @b wimlib-imagex. + * 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 * - * - The old WIM format from Vista pre-releases is not supported. - * - Compressed resource chunk sizes other than 32768 are not supported. This - * doesn't seem to be a real problem because the chunk size always seems to be - * this value. - * - wimlib does not provide a clone of the @b PEImg tool, or the @b Dism - * functionality other than that already present in @b ImageX, that allows you - * to make certain Windows-specific modifications to a Windows PE image, such - * as adding a driver or Windows component. Such a tool could be implemented - * on top of wimlib. + * @brief Create and handle non-standalone WIMs, such as split and delta WIMs. * - * \subsection more_info More information + * 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(). * - * 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. + * wimlib_write() can create delta WIMs as well as standalone WIMs, but a + * specialized function (wimlib_split()) is needed to create a split WIM. */ #ifndef _WIMLIB_H @@ -259,11 +340,14 @@ #include #include -/** Major version of the library (for example, the 1 in 1.2.5). */ +/** @ingroup G_general + * @{ */ + +/** Major version of the library (for example, the 1 in 1.2.5). */ #define WIMLIB_MAJOR_VERSION 1 /** Minor version of the library (for example, the 2 in 1.2.5). */ -#define WIMLIB_MINOR_VERSION 5 +#define WIMLIB_MINOR_VERSION 6 /** Patch version of the library (for example, the 5 in 1.2.5). */ #define WIMLIB_PATCH_VERSION 0 @@ -272,6 +356,10 @@ extern "C" { #endif +/** @} */ +/** @ingroup G_general + * @{ */ + /** * Opaque structure that represents a WIM file. This is an in-memory structure * and need not correspond to a specific on-disk file. However, a ::WIMStruct @@ -284,6 +372,8 @@ extern "C" { * * 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; @@ -293,7 +383,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 @@ -330,8 +420,18 @@ enum wimlib_compression_type { /** Compressed resources in the WIM use XPRESS compression. */ WIMLIB_COMPRESSION_TYPE_XPRESS = 2, + + /** Compressed resources in the WIM use LZMS compression. Note: LZMS + * compression is only compatible with wimlib v1.6.0 and later and with + * WIMGAPI Windows 8 and later (and some restrictions apply on the + * latter). */ + WIMLIB_COMPRESSION_TYPE_LZMS = 3, }; +/** @} */ +/** @ingroup G_progress + * @{ */ + /** Possible values of the first parameter to the user-supplied * ::wimlib_progress_func_t progress function */ enum wimlib_progress_msg { @@ -340,8 +440,8 @@ enum wimlib_progress_msg { * ::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. @p info will point to + /** One or more file or directory trees within a WIM image (not the full + * image) is about to be extracted. @p info will point to * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, @@ -353,8 +453,8 @@ enum wimlib_progress_msg { * extracted. @p info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - /** The WIM image's files resources are currently being extracted. @p - * info will point to ::wimlib_progress_info.extract. */ + /** File data is currently being extracted. @p info will point to + * ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, /** Starting to read a new part of a split pipable WIM over the pipe. @@ -391,9 +491,8 @@ enum wimlib_progress_msg { * ::wimlib_progress_info.scan. */ WIMLIB_PROGRESS_MSG_SCAN_END, - /** - * File resources are currently being written to the WIM. - * @p info will point to ::wimlib_progress_info.write_streams. */ + /** File resources ("streams") are currently being written to the WIM. + * @p info will point to ::wimlib_progress_info.write_streams. */ WIMLIB_PROGRESS_MSG_WRITE_STREAMS, /** @@ -425,9 +524,7 @@ enum wimlib_progress_msg { * ::wimlib_progress_info.integrity. */ WIMLIB_PROGRESS_MSG_CALC_INTEGRITY, - /** Reserved. (Previously used for WIMLIB_PROGRESS_MSG_JOIN_STREAMS, - * but in wimlib v1.5.0 this was removed to simplify the code and now - * you'll get ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages instead.) */ + /** Reserved. */ WIMLIB_PROGRESS_MSG_RESERVED, /** A wimlib_split() operation is in progress, and a new split part is @@ -463,124 +560,255 @@ union wimlib_progress_info { /* N.B. I wanted these to be anonymous structs, but Doxygen won't * document them if they aren't given a name... */ - /** Valid on messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. */ + /** Valid on the message ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS. This is + * the primary message for tracking the progress of writing a WIM file. + */ struct wimlib_progress_info_write_streams { - /** Number of bytes that are going to be written for all the - * streams combined. This is the amount in uncompressed data. - * (The actual number of bytes will be less if the data is being - * written compressed.) */ + /** Total number of uncompressed bytes of stream data being + * written. This can be thought of as the total uncompressed + * size of the files being archived, with some caveats. WIM + * files use single-instance streams, so the size provided here + * only counts distinct streams, except for the following + * exception: the size provided here may include the sizes of + * all newly added (e.g. with wimlib_add_image() streams, + * pending automatic de-duplication during the write operation + * itself. When each such stream de-duplication occurs, this + * number will be decreased by the size of the duplicate stream + * that need not be written. + * + * In the case of a wimlib_overwrite() that the library opted to + * perform in-place, both @p total_streams and @p total_bytes + * will only count the streams actually being written and not + * pre-existing streams in the WIM file. */ uint64_t total_bytes; - /** Number of streams that are going to be written. */ + /** Total number of streams being written. This can be thought + * of as the total number of files being archived, with some + * caveats. In general, a single file or directory may contain + * multiple data streams, each of which will be represented + * separately in this number. Furthermore, WIM files use + * single-instance streams, so the stream count provided here + * only counts distinct streams, except for the following + * exception: the stream count provided here may include newly + * added (e.g. with wimlib_add_image() streams, pending + * automatic de-duplication during the write operation itself. + * When each such stream de-duplication occurs, this number will + * be decreased by 1 to account for the duplicate stream that + * need not be written. */ uint64_t total_streams; - /** Number of uncompressed bytes that have been written so far. - * Will be 0 initially, and equal to @p total_bytes at the end. - * */ + /** Number of uncompressed bytes of stream data that have been + * written so far. This number be 0 initially, and will be + * equal to @p total_bytes at the end of the write operation. + * Note that @p total_bytes (but not @p completed_bytes) may + * decrease throughout the write operation due to the discovery + * of stream duplications. */ uint64_t completed_bytes; - /** Number of streams that have been written. Will be 0 - * initially, and equal to @p total_streams at the end. */ + /** Number of streams that have been written so far. This + * number will be 0 initially, and will be equal to @p + * total_streams at the end of the write operation. Note that + * @p total_streams (but not @p completed_streams) may decrease + * throughout the write operation due to the discovery of stream + * duplications. + * + * For applications that wish to calculate a simple "percent + * complete" for the write operation, it will likely be more + * accurate to calculate the percentage from @p completed_bytes + * and @p total_bytes rather than @p completed_streams and + * @p total_streams because the time for the operation to + * complete is mainly determined by the number of bytes that + * need to be read, compressed, and written, not just the number + * of files being archived. */ uint64_t completed_streams; - /** Number of threads that are being used to compress resources - * (if applicable). */ - unsigned num_threads; + /** Number of threads that are being used to compress streams, + * or 1 if streams are being written uncompressed. */ + uint32_t num_threads; - /** The compression type being used to write the streams; either - * ::WIMLIB_COMPRESSION_TYPE_NONE, - * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or - * ::WIMLIB_COMPRESSION_TYPE_LZX. */ - int compression_type; + /** The compression type being used to write the streams, as one + * of the ::wimlib_compression_type constants. */ + int32_t compression_type; /** Number of split WIM parts from which streams are being * written (may be 0 if irrelevant). */ - unsigned total_parts; + uint32_t total_parts; /** Number of split WIM parts from which streams have been * written (may be 0 if irrelevant). */ - unsigned completed_parts; + uint32_t completed_parts; } write_streams; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and - * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ + /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN, + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY, and + * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ struct wimlib_progress_info_scan { - /** Directory or NTFS volume that is being scanned. */ + /** Top-level directory being scanned; or, when capturing a NTFS + * volume with ::WIMLIB_ADD_FLAG_NTFS, this is instead the path + * to the file or block device that contains the NTFS volume + * being scanned. */ const wimlib_tchar *source; - /** Path to the file or directory that is about to be scanned, - * relative to the root of the image capture or the NTFS volume. - * */ + /** Path to the file (or directory) that has been scanned, valid + * on ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. When capturing a NTFS + * volume with ::WIMLIB_ADD_FLAG_NTFS, this path will be + * relative to the root of the NTFS volume. */ const wimlib_tchar *cur_path; + /** Dentry scan status, valid on + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. */ enum { - /** File or directory looks okay and will be captured. */ + /** The file looks okay and will be captured. */ WIMLIB_SCAN_DENTRY_OK = 0, - /** File or directory is being excluded from capture due - * to the capture configuration file. */ + /** File is being excluded from capture due to the + * capture configuration. */ WIMLIB_SCAN_DENTRY_EXCLUDED, - /** File or directory is being excluded from capture due - * to being unsupported (e.g. an encrypted or device - * file). */ + /** File is being excluded from capture due to being + * unsupported (e.g. an encrypted or device file). */ WIMLIB_SCAN_DENTRY_UNSUPPORTED, + + /** The file is an absolute symbolic link or junction + * point and it is being excluded from capture because + * it points outside of the capture directory and + * reparse-point fixups are enabled. (Reparse point + * fixups can be disabled by using the flag + * ::WIMLIB_ADD_FLAG_NORPFIX.) */ + WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, } status; - /** Target path in the WIM. Only valid on messages - * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and - * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ - const wimlib_tchar *wim_target_path; + union { + /** Target path in the WIM image. Only valid on + * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and + * ::WIMLIB_PROGRESS_MSG_SCAN_END. If capturing a full + * image, this will be the empty string; otherwise it + * will name the place in the WIM image at which the + * directory tree is being added. */ + const wimlib_tchar *wim_target_path; + + /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status + * of ::WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is the + * target of the absolute symbolic link or junction + * point. */ + const wimlib_tchar *symlink_target; + }; + + /** Number of directories scanned so far, including the root + * directory but excluding any unsupported/excluded directories. + * + * Details: On Windows and in NTFS capture mode, a reparse point + * counts as a directory if and only if it has + * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link + * counts as a directory if and only if when fully dereferenced + * it points to an accessible directory. If a file has multiple + * names (hard links), it is only counted one time. */ + uint64_t num_dirs_scanned; + + /** Number of non-directories scanned so far, excluding any + * unsupported/excluded files. + * + * Details: On Windows and in NTFS capture mode, a reparse point + * counts as a non-directory if and only if it does not have + * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link + * counts as a non-directory if and only if when fully + * dereferenced it points to a non-directory or its target is + * inaccessible. If a file has multiple names (hard links), it + * is only counted one time. */ + uint64_t num_nondirs_scanned; + + /** Number of bytes of file data that have been detected so far. + * + * Details: This data may not actually have been read yet, and + * it will not actually be written to the WIM file until + * wimlib_write() or wimlib_overwrite() has been called. Data + * from excluded files is not counted. This number includes + * default file contents as well as named data streams and + * reparse point data. The size of reparse point data is + * tallied after any reparse-point fixups, and in the case of + * capturing a symbolic link on a UNIX-like system, the creation + * of the reparse point data itself. If a file has multiple + * names (hard links), its size(s) are only counted one time. + * On Windows, encrypted files have their encrypted size + * counted, not their unencrypted size; however, compressed + * files have their uncompressed size counted. */ + uint64_t num_bytes_scanned; } scan; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, + /** Valid on messages + * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END, - * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, and - * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */ + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, and + * ::WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS. + * + * Note: most of the time of an extraction operation will be spent + * extracting streams, and the application will receive + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS during this time. Using @p + * completed_bytes and @p total_bytes, the application can calculate a + * percentage complete. However, note that this message does not, in + * general, actually provide information about which "file" is currently + * being extracted. This is because wimlib, by default, extracts the + * individual data streams in whichever order it determines to be the + * most efficient. */ struct wimlib_progress_info_extract { - /** Number of the image being extracted (1-based). */ + /** Number of the image from which files are being extracted + * (1-based). */ int image; - /** Flags passed to to wimlib_extract_image() */ + /** Extraction flags being used. */ int extract_flags; - /** Full path to the WIM file being extracted. */ + /** Full path to the WIM file from which files are being + * extracted, or @c NULL if the WIMStruct has no associated + * on-disk file. */ const wimlib_tchar *wimfile_name; - /** Name of the image being extracted. */ + /** Name of the image from which files are being extracted, or + * the empty string if the image is unnamed. */ const wimlib_tchar *image_name; - /** Directory or NTFS volume to which the image is being - * extracted. */ + /** Path to the directory or NTFS volume to which the files are + * being extracted. */ const wimlib_tchar *target; /** Reserved. */ - const wimlib_tchar *cur_path; + const wimlib_tchar *reserved; /** Number of bytes of uncompressed data that will be extracted. - * Takes into account hard links (they are not counted for each - * link.) */ + * If a file has multiple names (hard links), its size (or + * sizes, in the case of named data streams) is only counted one + * time. For "reparse points" and symbolic links, the size to + * be extracted is the size of the reparse data buffer. + * + * This number will stay constant throughout the extraction. */ uint64_t total_bytes; - /** Number of bytes that have been written so far. Will be 0 - * initially, and equal to @p total_bytes at the end. */ + /** Number of bytes of uncompressed data that have been + * extracted so far. This initially be 0 and will equal to @p + * total_bytes at the end of the extraction. */ uint64_t completed_bytes; - /** Number of streams that will be extracted. This may more or - * less than the number of "files" to be extracted due to - * special cases (hard links, symbolic links, and alternate data - * streams.) */ + /** Number of (not necessarily unique) streams that will be + * extracted. This may be more or less than the number of + * "files" to be extracted due to hard links as well as + * potentially multiple streams per file (named data streams). + * A "stream" may be the default contents of a file, a named + * data stream, or a reparse data buffer. */ uint64_t num_streams; - /** Path to the root dentry within the WIM for the tree that is - * being extracted. Will be the empty string when extracting a - * full image. */ + /** When extracting files using wimlib_extract_files(), this + * will be the path within the WIM image to the file or + * directory tree currently being extracted. Otherwise, this + * will be the empty string. */ 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 @@ -685,6 +913,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 { @@ -767,6 +999,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 { @@ -837,41 +1073,64 @@ struct wimlib_wim_info { uint32_t reserved[9]; }; -/** Information about a unique resource in the WIM file. - */ +/** Information about a unique stream in the WIM file. (A stream is the same + * thing as a "resource", except in the case of packed resources.) */ struct wimlib_resource_entry { - /** Uncompressed size of the resource in bytes. */ + /** Uncompressed size of the stream in bytes. */ uint64_t uncompressed_size; - /** Compressed size of the resource in bytes. This will be the same as - * @p uncompressed_size if the resource is uncompressed. */ + /** Compressed size of the stream in bytes. This will be the same as @p + * uncompressed_size if the stream is uncompressed. Or, if @p + * is_packed_streams is 1, this will be 0. */ uint64_t compressed_size; - /** Offset, in bytes, of this resource from the start of the WIM file. + /** Offset, in bytes, of this stream from the start of the WIM file. Or + * if @p packed is 1, then this is actually the offset at which this + * stream begins in the uncompressed contents of the packed resource. */ uint64_t offset; - /** SHA1 message digest of the resource's uncompressed contents. */ + /** SHA1 message digest of the stream's uncompressed contents. */ uint8_t sha1_hash[20]; - /** Which part number of the split WIM this resource is in. This should + /** Which part number of the split WIM this stream is in. This should * be the same as the part number provided by wimlib_get_wim_info(). */ uint32_t part_number; - /** Number of times this resource is referenced over all WIM images. */ + /** Number of times this stream is referenced over all WIM images. */ uint32_t reference_count; - /** 1 if this resource is compressed. */ + /** 1 if this stream is compressed. */ uint32_t is_compressed : 1; - /** 1 if this resource is a metadata resource rather than a file - * resource. */ + /** 1 if this stream is a metadata resource rather than a file resource. + * */ uint32_t is_metadata : 1; uint32_t is_free : 1; uint32_t is_spanned : 1; - uint32_t reserved_flags : 28; - uint64_t reserved[4]; + + /** 1 if this stream was not found in the lookup table of the + * ::WIMStruct. This normally implies a missing call to + * wimlib_reference_resource_files() or wimlib_reference_resources(). + * */ + uint32_t is_missing : 1; + + /** 1 if this stream is located in a packed resource which may contain + * other streams (all compressed together) as well. */ + uint32_t packed : 1; + + uint32_t reserved_flags : 26; + + /** If @p packed is 1, then this will specify the offset of the packed + * resource in the WIM. */ + uint64_t raw_resource_offset_in_wim; + + /** If @p is_packed_streams is 1, then this will specify the compressed + * size of the packed resource in the WIM. */ + uint64_t raw_resource_compressed_size; + + uint64_t reserved[2]; }; /** A stream of a file in the WIM. */ @@ -992,14 +1251,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 @@ -1008,17 +1259,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 @@ -1030,8 +1281,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002 /** Call the progress function with the message - * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to - * be scanned, or when a directory or file is being excluded from capture. */ + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been + * scanned. */ #define WIMLIB_ADD_FLAG_VERBOSE 0x00000004 /** Mark the image being added as the bootable image of the WIM. */ @@ -1040,17 +1291,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Store the UNIX owner, group, and mode. This is done by adding a special * alternate data stream to each regular file, symbolic link, and directory to * contain this information. Please note that this flag is for convenience - * only; Microsoft's @a imagex.exe will not understand this special information. - * This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */ + * only; Microsoft's implementation will not understand this special + * information. This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */ #define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 /** Do not capture security descriptors. Only has an effect in NTFS capture - * mode, or in Win32 native builds. */ + * mode, or in Windows native builds. */ #define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020 /** Fail immediately if the full security descriptor of any file or directory - * cannot be accessed. Only has an effect in Win32 native builds. The default - * behavior without this flag is to first try omitting the SACL from the + * cannot be accessed. Only has an effect in Windows native builds. The + * default behavior without this flag is to first try omitting the SACL from the * security descriptor, then to try omitting the security descriptor entirely. * */ #define WIMLIB_ADD_FLAG_STRICT_ACLS 0x00000040 @@ -1117,14 +1368,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 @@ -1133,13 +1379,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. @@ -1157,14 +1399,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; @@ -1187,7 +1424,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** This flag no longer does anything but is reserved for future use. */ #define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008 -/** Read the WIM file sequentially while extracting the image. */ +/** Read the WIM file sequentially while extracting the image. As of wimlib + * v1.6.0 this is the default behavior, and this flag no longer does anything. + */ #define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010 /** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA. Only @@ -1250,13 +1489,34 @@ 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(). - * - * @{ +/** Perform the extraction ordered by the tree of files to extract rather than + * how the underlying streams are arranged in the WIM file. For regular WIM + * files this may decrease or increase performance, depending on various + * factors. For WIM files containing packed streams this will decrease + * performance. */ +#define WIMLIB_EXTRACT_FLAG_FILE_ORDER 0x00020000 + +/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the + * paths in the WIM as "glob" patterns which may contain the wildcard characters + * '?' and '*'. The '?' character matches any character except a path + * separator, whereas the '*' character matches zero or more non-path-separator + * characters. Each glob pattern may match zero or more paths in the WIM file. + * If a glob pattern ends in a path separator, it will only match directories + * (including reparse points with FILE_ATTRIBUTE_DIRECTORY set). By default, if + * a glob pattern does not match any files, a warning but not an error will be + * issued, even if the glob pattern did not actually contain wildcard + * characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error instead. */ +#define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000 + +/** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error + * (::WIMLIB_ERR_PATH_DOES_NOT_EXIST) rather than a warning to be issued when + * one of the provided globs did not match a file. */ +#define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000 + +/** @} */ +/** @ingroup G_mounting_wim_images + * @{ */ /** Mount the WIM image read-write rather than the default of read-only. */ #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 @@ -1283,13 +1543,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 @@ -1299,7 +1555,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * integrity table is invalid). */ #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001 -/** Issue an error if the WIM is part of a split WIM. */ +/** 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 @@ -1310,12 +1568,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 @@ -1333,24 +1588,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. * @@ -1425,12 +1673,26 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * already implied for wimlib_overwrite(). */ #define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 +#define WIMLIB_WRITE_FLAG_RESERVED 0x00000800 + /** - * @name Init flags - * - * The following flags can be passed to wimlib_global_init(). - * @{ - */ + * When writing streams in the resulting WIM file, pack multiple streams into a + * single WIM resource instead of compressing them independently. This tends to + * produce a better compression ratio at the cost of less random access. + * However, WIMs created with this flag are only compatible with wimlib v1.6.0 + * or later and WIMGAPI Windows 8 or later, seemingly for Windows Setup only and + * not including ImageX and Dism. WIMs created with this flag must use + * version number 3584 in their header instead of 68864. + * + * If this flag is passed to wimlib_overwrite() and the WIM did not previously + * contain packed streams, the WIM's version number will be changed to 3584 and + * the new streams will be written packed. Use ::WIMLIB_WRITE_FLAG_REBUILD to + * force the WIM to be fully rebuilt. */ +#define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000 + +/** @} */ +/** @ingroup G_general + * @{ */ /** Assume that strings are represented in UTF-8, even if this is not the * locale's character encoding. This flag is ignored on Windows, where wimlib @@ -1460,13 +1722,17 @@ 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(). - * @{ - */ +/** Default to interpreting WIM paths case sensitively (default on UNIX-like + * systems). */ +#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010 + +/** Default to interpreting WIM paths case insensitively (default on Windows). + * This does not apply to mounted images. */ +#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020 + +/** @} */ +/** @ingroup G_nonstandalone_wims + * @{ */ /** wimlib_reference_resource_files() only: Enable shell-style filename * globbing. */ @@ -1480,9 +1746,9 @@ 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 { @@ -1554,7 +1820,12 @@ struct wimlib_update_command { }; }; -/** 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. @@ -1568,6 +1839,11 @@ struct wimlib_extract_command { int extract_flags; }; + +/** @} */ +/** @ingroup G_general + * @{ */ + /** * Possible values of the error code returned by many functions in wimlib. * @@ -1649,6 +1925,7 @@ enum wimlib_error_code { WIMLIB_ERR_WIM_IS_READONLY, WIMLIB_ERR_WRITE, WIMLIB_ERR_XML, + WIMLIB_ERR_WIM_IS_ENCRYPTED, }; @@ -1659,6 +1936,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 @@ -1695,6 +1974,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 @@ -1750,7 +2031,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 @@ -1777,6 +2061,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 @@ -1802,6 +2088,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 @@ -1841,6 +2129,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 @@ -1934,6 +2224,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 @@ -1999,6 +2291,8 @@ wimlib_extract_files(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @ingroup G_extracting_wims + * * Extracts an image, or all images, from a WIM to a directory or directly to a * NTFS volume image. * @@ -2124,6 +2418,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. * @@ -2174,9 +2470,63 @@ wimlib_extract_image_from_pipe(int pipe_fd, wimlib_progress_func_t progress_func); /** + * Similar to wimlib_extract_paths(), but the paths to extract from the WIM + * image are specified in the UTF-8 text file named by @p path_list_file which + * itself contains the list of paths to use, one per line. Leading and trailing + * whitespace, and otherwise empty lines and lines beginning with the ';' + * character are ignored. No quotes are needed as paths are otherwise delimited + * by the newline character. + */ +extern int +wimlib_extract_pathlist(WIMStruct *wim, int image, + const wimlib_tchar *target, + const wimlib_tchar *path_list_file, + int extract_flags, + wimlib_progress_func_t progress_func); + +/** + * Similar to wimlib_extract_files(), but the files or directories to extract + * from the WIM image are specified as an array of paths. + * + * Each path will be extracted to a corresponding subdirectory of the @p target + * based on its location in the WIM image. For example, if one of the paths to + * extract is "/Windows/explorer.exe" and the target is "outdir", the file will + * be extracted to "outdir/Windows/explorer.exe". Each path to extract must be + * specified as the absolute path to a directory within the WIM image. + * Separators in the paths to extract may be either forwards or backwards + * slashes, and leading path separators are optional. Symbolic links are not + * dereferenced when interpreting paths to extract. Paths to extract will be + * interpreted either case-sensitively (UNIX default) or case-insensitively + * (Windows default); this can be changed by wimlib_global_init(). + * + * The @p target path, on the other hand, is expected to be a native path. On + * UNIX-like systems it may not contain backslashes, for example. + * + * By default, if any paths to extract do not exist, + * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is issued. This behavior changes if + * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified. + * + * With ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified in @p extract_flags, this + * function additionally allows paths to be globs using the wildcard characters + * '*' and '?'. + */ +extern int +wimlib_extract_paths(WIMStruct *wim, + int image, + const wimlib_tchar *target, + const wimlib_tchar * const *paths, + size_t num_paths, + int extract_flags, + wimlib_progress_func_t progress_func); + +/** + * @ingroup G_wim_information + * * Extracts the XML data of a WIM file to a file stream. Every WIM file * includes a string of XML that describes the images contained in the WIM. * + * See wimlib_get_xml_data() to read the XML data into memory instead. + * * @param wim * Pointer to the ::WIMStruct for a WIM file, which does not necessarily * have to be standalone (e.g. it could be part of a split WIM). @@ -2197,6 +2547,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. * @@ -2209,6 +2561,8 @@ extern void wimlib_free(WIMStruct *wim); /** + * @ingroup G_general + * * Converts a ::wimlib_compression_type value into a string. * * @param ctype @@ -2223,6 +2577,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 @@ -2236,6 +2592,8 @@ 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 @@ -2255,6 +2613,8 @@ 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 @@ -2275,6 +2635,8 @@ wimlib_get_image_name(const WIMStruct *wim, int image); /** + * @ingroup G_wim_information + * * Get basic information about a WIM file. * * @param wim @@ -2290,10 +2652,43 @@ extern int wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); /** + * @ingroup G_wim_information + * + * Read the XML data of a WIM file into an in-memory buffer. Every WIM file + * includes a string of XML that describes the images contained in the WIM. + * + * See wimlib_extract_xml_data() to extract the XML data to a file stream + * instead. + * + * @param wim + * Pointer to the ::WIMStruct for a WIM file, which does not necessarily + * have to be standalone (e.g. it could be part of a split WIM). + * @param buf_ret + * On success, a pointer to an allocated buffer containing the raw UTF16-LE + * XML data is written to this location. + * @param bufsize_ret + * The size of the XML data in bytes is written to this location. + * + * @return 0 on success; nonzero on error. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(), or + * @p buf_ret or @p bufsize_ret was @c NULL. + * @retval ::WIMLIB_ERR_NOMEM + * @retval ::WIMLIB_ERR_READ + * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE + * Failed to read the XML data from the WIM. + */ +extern int +wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); + +/** + * @ingroup G_general + * * Initialization function for wimlib. Call before using any other wimlib * function except wimlib_set_print_errors(). If not done manually, this * function will be called automatically with @p init_flags set to - * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. + * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again + * after it has already successfully run. * * @param init_flags * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. @@ -2310,6 +2705,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. */ @@ -2317,6 +2714,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 @@ -2333,6 +2732,8 @@ 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 @@ -2342,9 +2743,11 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * 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 must have had any needed external resources - * previously referenced using wimlib_reference_resources() or - * wimlib_reference_resource_files(). + * 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 @@ -2355,8 +2758,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. @@ -2387,6 +2789,8 @@ 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 over all * images. Both file resources and metadata resources are included. However, @@ -2420,6 +2824,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 @@ -2464,61 +2870,10 @@ wimlib_join(const wimlib_tchar * const *swms, int wim_write_flags, wimlib_progress_func_t progress_func); -/** - * Compress a chunk of a WIM resource using LZX compression. - * - * This function is exported for convenience only and should only be used by - * library clients looking to make use of wimlib's compression code for another - * purpose. - * - * @param chunk - * Uncompressed data of the chunk. - * @param chunk_size - * Size of the uncompressed chunk, in bytes. - * @param out - * Pointer to output buffer of size at least (@p chunk_size - 1) bytes. - * - * @return - * The size of the compressed data written to @p out in bytes, or 0 if the - * data could not be compressed to (@p chunk_size - 1) bytes or fewer. - * - * As a special requirement, the compression code is optimized for the WIM - * format and therefore requires (@p chunk_size <= 32768). - */ -extern unsigned -wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out); /** - * Decompresses a block of LZX-compressed data as used in the WIM file format. - * - * Note that this will NOT work unmodified for LZX as used in the cabinet - * format, which is not the same as in the WIM format! - * - * 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. + * @ingroup G_mounting_wim_images * - * @param compressed_data - * Pointer to the compressed data. - * - * @param compressed_len - * Length of the compressed data, in bytes. - * - * @param uncompressed_data - * Pointer to the buffer into which to write the uncompressed data. - * - * @param uncompressed_len - * Length of the uncompressed data. It must be 32768 bytes or less. - * - * @return - * 0 on success; non-zero on failure. - */ -extern int -wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); - - -/** * Mounts an image in a WIM file on a directory read-only or read-write. * * As this is implemented using FUSE (Filesystme in UserSpacE), this is not @@ -2604,6 +2959,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 @@ -2636,7 +2993,8 @@ wimlib_mount_image(WIMStruct *wim, * chunk of the WIM does not match the corresponding message digest given * in the integrity table. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * Resources in @p wim_file are compressed, but the chunk size is not 32768. + * Resources in @p wim_file are compressed, but the chunk size was invalid + * for the WIM's compression format. * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE * The header of @p wim_file says that resources in the WIM are compressed, * but the header flag indicating LZX or XPRESS compression is not set. @@ -2682,6 +3040,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(). @@ -2759,6 +3119,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 @@ -2776,6 +3138,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. */ @@ -2783,6 +3147,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. */ @@ -2790,6 +3156,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) @@ -2842,6 +3210,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. * @@ -2874,6 +3244,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 @@ -2947,6 +3319,8 @@ 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. * @@ -2977,6 +3351,8 @@ 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 @@ -3002,6 +3378,83 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, const wimlib_tchar *description); /** + * @ingroup G_writing_and_overwriting_wims + * + * Set the compression chunk size of a WIM to use in subsequent calls to + * wimlib_write() or wimlib_overwrite(). + * + * A compression chunk size will result in a greater compression ratio, but the + * speed of random access to the WIM will be reduced, and the effect of an + * increased compression chunk size is limited by the size of each file being + * compressed. + * + * WARNING: Microsoft's software is seemingly incompatible with LZX chunk + * sizes other than 32768. Chunk sizes other than 32768 (for any format) are + * also incompatible with wimlib v1.5.3 and earlier. + * + * @param wim + * ::WIMStruct for a WIM. + * @param out_chunk_size + * The chunk size (in bytes) to set. The valid chunk sizes are dependent + * on the compression format. The XPRESS and LZMS compression formats + * support chunk sizes that are powers of 2 with exponents between 15 and + * 26 inclusively, whereas the LZX compression format supports chunk sizes + * that are powers of 2 with exponents between 15 and 21 inclusively. As a + * special case, if @p out_chunk_size is specified as 0, the chunk size is + * set to the default for the currently selected output compression type. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE + * @p chunk_size is not a supported chunk size for the currently selected + * output compression type. + */ +extern int +wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing + * packed streams. + */ +extern int +wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Set the compression type of a WIM to use in subsequent calls to + * wimlib_write() or wimlib_overwrite(). + * + * @param wim + * ::WIMStruct for a WIM. + * @param ctype + * The compression type to set (one of ::wimlib_compression_type). If this + * compression type is incompatible with the current output chunk size + * (either the default or as set with wimlib_set_output_chunk_size()), the + * output chunk size is reset to the default for that compression type. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype did not specify a valid compression type. + */ +extern int +wimlib_set_output_compression_type(WIMStruct *wim, int ctype); + +/** + * @ingroup G_writing_and_overwriting_wims + * + * Similar to wimlib_set_output_compression_type(), but set the compression type + * for writing packed streams. + */ +extern int +wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype); + +/** + * @ingroup G_modifying_wims + * * Set basic information about a WIM. * * @param wim @@ -3032,6 +3485,8 @@ 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") * @@ -3056,6 +3511,8 @@ 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 @@ -3082,6 +3539,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. @@ -3104,10 +3563,7 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * A function equivalent to @c realloc() that wimlib will use to reallocate * memory. If @c NULL, the free function is set back to the default @c * realloc() from the C library. - * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_UNSUPPORTED - * wimlib was compiled with the @c --without-custom-memory-allocator flag, - * so custom memory allocators are unsupported. + * @return 0 */ extern int wimlib_set_memory_allocator(void *(*malloc_func)(size_t), @@ -3115,6 +3571,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 @@ -3140,6 +3598,8 @@ extern int wimlib_set_print_errors(bool show_messages); /** + * @ingroup G_nonstandalone_wims + * * Splits a WIM into multiple parts. * * @param wim @@ -3184,6 +3644,8 @@ 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 @@ -3251,6 +3713,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 @@ -3362,6 +3826,8 @@ wimlib_update_image(WIMStruct *wim, wimlib_progress_func_t progress_func); /** + * @ingroup G_writing_and_overwriting_wims + * * Writes a WIM to a file. * * This brings in resources from any external locations, such as directory trees @@ -3447,6 +3913,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 @@ -3473,19 +3941,362 @@ wimlib_write_to_fd(WIMStruct *wim, wimlib_progress_func_t progress_func); /** - * This function is equivalent to wimlib_lzx_compress(), but instead compresses - * the data using "XPRESS" compression. + * @defgroup G_compression Compression and decompression functions + * + * @brief Functions for LZX, XPRESS, and LZMS compression and decompression, + * exported for convenience only, as they are already used by wimlib internally + * when appropriate. + * + * These functions can be used for general-purpose lossless data compression, + * but some limitations apply; for example, none of the compressors or + * decompressors currently support sliding windows, and there also exist + * slightly different variants of these formats that are not supported + * unmodified. */ -extern unsigned -wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out); /** - * This function is equivalent to wimlib_lzx_decompress(), but instead assumes - * the data is compressed using "XPRESS" compression. + * @ingroup G_compression + * @{ + */ + +/** Header for compression parameters to pass to wimlib_create_compressor() or + * wimlib_set_default_compressor_params(). */ +struct wimlib_compressor_params_header { + /** Size of the parameters, in bytes. */ + uint32_t size; +}; + +/** Header for decompression parameters to pass to wimlib_create_decompressor() + * or wimlib_set_default_decompressor_params() */ +struct wimlib_decompressor_params_header { + /** Size of the parameters, in bytes. */ + uint32_t size; +}; + +/** LZX compression parameters that can optionally be passed to + * wimlib_create_compressor() with the compression type + * ::WIMLIB_COMPRESSION_TYPE_LZX. */ +struct wimlib_lzx_compressor_params { + /** hdr.size Must be set to the size of this structure, in bytes. */ + struct wimlib_compressor_params_header hdr; + + /** Relatively fast LZX compression algorithm with a decent compression + * ratio; the suggested default. */ +#define WIMLIB_LZX_ALGORITHM_FAST 0 + + /** Slower LZX compression algorithm that provides a better compression + * ratio. */ +#define WIMLIB_LZX_ALGORITHM_SLOW 1 + + /** Algorithm to use to perform the compression: either + * ::WIMLIB_LZX_ALGORITHM_FAST or ::WIMLIB_LZX_ALGORITHM_SLOW. The + * format is still LZX; this refers to the method the code will use to + * perform LZX-compatible compression. */ + uint32_t algorithm : 3; + + /** If set to 1, the default parameters for the specified algorithm are + * used rather than the ones specified in the following union. */ + uint32_t use_defaults : 1; + + union { + /** Parameters for the fast algorithm. */ + struct wimlib_lzx_fast_params { + uint32_t fast_reserved1[10]; + } fast; + + /** Parameters for the slow algorithm. */ + struct wimlib_lzx_slow_params { + /** If set to 1, the compressor can output length 2 + * matches. If set 0, the compressor only outputs + * matches of length 3 or greater. Suggested value: 1 + */ + uint32_t use_len2_matches : 1; + + uint32_t slow_reserved1 : 31; + + /** Matches with length (in bytes) greater than or equal + * to this value are immediately taken without spending + * time on minimum-cost measurements. Suggested value: + * 32. */ + uint32_t nice_match_length; + + /** Number of passes to compute a match/literal sequence + * for each LZX block. This is for an iterative + * algorithm that attempts to minimize the cost of the + * match/literal sequence by using a cost model provided + * by the previous iteration. Must be at least 1. + * Suggested value: 2. */ + uint32_t num_optim_passes; + + /** Reserved; set to 0. */ + uint32_t slow_reserved_blocksplit; + + /** Maximum depth to search for matches at each + * position. Suggested value: 50. */ + uint32_t max_search_depth; + + /** Maximum number of potentially good matches to + * consider for each position. Suggested value: 3. */ + uint32_t max_matches_per_pos; + + uint32_t slow_reserved2[2]; + + /** Assumed cost of a main symbol with zero frequency. + * Must be at least 1 and no more than 16. Suggested + * value: 15. */ + uint8_t main_nostat_cost; + + /** Assumed cost of a length symbol with zero frequency. + * Must be at least 1 and no more than 16. Suggested + * value: 15. */ + uint8_t len_nostat_cost; + + /** Assumed cost of an aligned symbol with zero + * frequency. Must be at least 1 and no more than 8. + * Suggested value: 7. */ + uint8_t aligned_nostat_cost; + + uint8_t slow_reserved3[5]; + } slow; + } alg_params; +}; + +/** Opaque compressor handle. */ +struct wimlib_compressor; + +/** Opaque decompressor handle. */ +struct wimlib_decompressor; + +/** + * Set the default compression parameters for the specified compression type. + * This will affect both explicit and wimlib-internal calls to + * wimlib_create_compressor(). + * + * @param ctype + * Compression type for which to set the default compression parameters. + * @param params + * Compression-type specific parameters. This may be @c NULL, in which + * case the "default default" parameters are restored. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_NOMEM + * Not enough memory to duplicate the parameters (perhaps @c params->size + * was invalid). + */ +extern int +wimlib_set_default_compressor_params(enum wimlib_compression_type ctype, + const struct wimlib_compressor_params_header *params); + +/** + * Allocate a compressor for the specified compression type using the specified + * parameters. + * + * @param ctype + * Compression type for which to create the compressor. + * @param max_block_size + * Maximum block size to support. The exact meaning and allowed values for + * this parameter depend on the compression type, but it at least specifies + * the maximum allowed value for @p uncompressed_size to wimlib_compress(). + * @param extra_params + * An optional pointer to extra compressor parameters for the specified + * compression type. For LZX, a pointer to ::wimlib_lzx_compressor_params + * may be specified here. If left @c NULL, the default parameters are + * used. + * @param compressor_ret + * A location into which to return the pointer to the allocated compressor, + * which can be used for any number of calls to wimlib_compress() before + * being freed with wimlib_free_compressor(). + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The compression parameters were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Insufficient memory to allocate the compressor. */ extern int -wimlib_xpress_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); +wimlib_create_compressor(enum wimlib_compression_type ctype, + size_t max_block_size, + const struct wimlib_compressor_params_header *extra_params, + struct wimlib_compressor **compressor_ret); + +/** + * Losslessly compress a block of data using a compressor previously created + * with wimlib_create_compressor(). + * + * @param uncompressed_data + * Buffer containing the data to compress. + * @param uncompressed_size + * Size, in bytes, of the data to compress. + * @param compressed_data + * Buffer into which to write the compressed data. + * @param compressed_size_avail + * Number of bytes available in @p compressed_data. + * @param compressor + * A compressor previously allocated with wimlib_create_compressor(). + * + * @return + * The size of the compressed data, in bytes, or 0 if the input data could + * not be compressed to @p compressed_size_avail or fewer bytes. + */ +extern size_t +wimlib_compress(const void *uncompressed_data, size_t uncompressed_size, + void *compressed_data, size_t compressed_size_avail, + struct wimlib_compressor *compressor); + +/** + * Free a compressor previously allocated with wimlib_create_compressor(). + * + * @param compressor + * The compressor to free. + */ +extern void +wimlib_free_compressor(struct wimlib_compressor *compressor); + +/** + * Set the default decompression parameters for the specified compression type. + * This will affect both explicit and wimlib-internal calls to + * wimlib_create_decompressor(). + * + * @param ctype + * Compression type for which to set the default decompression parameters. + * @param params + * Compression-type specific parameters. This may be @c NULL, in which + * case the "default default" parameters are restored. + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_NOMEM + * Not enough memory to duplicate the parameters (perhaps @c params->size + * was invalid). + */ +extern int +wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype, + const struct wimlib_decompressor_params_header *params); + +/** + * Allocate a decompressor for the specified compression type using the + * specified parameters. + * + * @param ctype + * Compression type for which to create the decompressor. + * @param max_block_size + * Maximum block size to support. The exact meaning and allowed values for + * this parameter depend on the compression type, but it at least specifies + * the maximum allowed value for @p uncompressed_size to + * wimlib_decompress(). + * @param extra_params + * An optional pointer to extra decompressor parameters for the specified + * compression type. If @c NULL, the default parameters are used. + * @param decompressor_ret + * A location into which to return the pointer to the allocated + * decompressor, which can be used for any number of calls to + * wimlib_decompress() before being freed with wimlib_free_decompressor(). + * + * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The decompression parameters were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Insufficient memory to allocate the decompressor. + */ +extern int +wimlib_create_decompressor(enum wimlib_compression_type ctype, + size_t max_block_size, + const struct wimlib_decompressor_params_header *extra_params, + struct wimlib_decompressor **decompressor_ret); + +/** + * Decompress a block of data using a decompressor previously created with + * wimlib_create_decompressor(). + * + * @param compressed_data + * Buffer containing the data to decompress. + * @param compressed_size + * Size, in bytes, of the data to decompress. + * @param uncompressed_data + * Buffer into which to write the uncompressed data. + * @param uncompressed_size + * Size, in bytes, of the data when uncompressed. + * @param decompressor + * A decompressor previously allocated with wimlib_create_decompressor(). + * + * @return 0 on success; nonzero on error. + */ +extern int +wimlib_decompress(const void *compressed_data, size_t compressed_size, + void *uncompressed_data, size_t uncompressed_size, + struct wimlib_decompressor *decompressor); + +/** + * Free a decompressor previously allocated with wimlib_create_decompressor(). + * + * @param decompressor + * The decompressor to free. + */ +extern void +wimlib_free_decompressor(struct wimlib_decompressor *decompressor); + + +struct wimlib_lzx_params_old; +struct wimlib_lzx_context_old; + +/** Deprecated; do not use. */ +extern int +wimlib_lzx_set_default_params(const struct wimlib_lzx_params_old *params) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern int +wimlib_lzx_alloc_context(const struct wimlib_lzx_params_old *params, + struct wimlib_lzx_context_old **ctx_pp) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern void +wimlib_lzx_free_context(struct wimlib_lzx_context_old *ctx) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern unsigned +wimlib_lzx_compress2(const void *udata, unsigned ulen, void *cdata, + struct wimlib_lzx_context_old *ctx) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern unsigned +wimlib_lzx_compress(const void *udata, unsigned ulen, void *cdata) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern unsigned +wimlib_xpress_compress(const void *udata, unsigned ulen, void *cdata) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern int +wimlib_lzx_decompress(const void *cdata, unsigned clen, + void *udata, unsigned ulen) + _wimlib_deprecated; + +/** Deprecated; do not use. */ +extern int +wimlib_xpress_decompress(const void *cdata, unsigned clen, + void *udata, unsigned ulen) + _wimlib_deprecated; + +/** @} */ + + #ifdef __cplusplus }