X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=c0aaf13bf2f46bb103976c7a0d2c2adb08e5b1dd;hp=afed2af1147b62ad37376af53cb150938e568ff8;hb=e014475fba041d91e3977fe64298c6a2cbe8195e;hpb=7a013be24d13570d28fea34c1c8c1f10ee3d653f diff --git a/include/wimlib.h b/include/wimlib.h index afed2af1..c0aaf13b 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -33,7 +33,7 @@ * * @section sec_intro Introduction * - * This is the documentation for the library interface of wimlib 1.5.3, a C + * This is the documentation for the library interface of wimlib 1.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 @@ -170,9 +170,6 @@ * documented in the man page for @b wimlib-imagex. * * - The old WIM format from Vista pre-releases is not supported. - * - Compressed resource chunk sizes other than 32768 are not supported. This - * doesn't seem to be a real problem because the chunk size always seems to be - * this value. * - wimlib does not provide a clone of the @b PEImg tool, or the @b Dism * functionality other than that already present in @b ImageX, that allows you * to make certain Windows-specific modifications to a Windows PE image, such @@ -265,8 +262,12 @@ * 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. + * 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 @@ -330,12 +331,6 @@ * 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 #define _WIMLIB_H @@ -352,10 +347,10 @@ #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 3 +#define WIMLIB_PATCH_VERSION 0 #ifdef __cplusplus extern "C" { @@ -426,8 +421,7 @@ 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. Currently, - * wimlib has a decompressor for this format but not a compressor. LZMS + /** 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). */ @@ -446,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, @@ -459,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. @@ -497,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, /** @@ -531,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 @@ -569,142 +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, or being an - * absolute symbolic link that points outside of the - * capture directory without ::WIMLIB_ADD_FLAG_NORPFIX. - */ + /** File is being excluded from capture due to the + * capture configuration. */ WIMLIB_SCAN_DENTRY_EXCLUDED, - /** File or directory is being excluded from capture due - * to being unsupported (e.g. an encrypted or device - * file). */ + /** File is being excluded from capture due to being + * unsupported (e.g. an encrypted or device file). */ WIMLIB_SCAN_DENTRY_UNSUPPORTED, + + /** The file is an absolute symbolic link or junction + * 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. */ + * unsupported/excluded files. + * + * Details: On Windows and in NTFS capture mode, a reparse point + * counts as a non-directory if and only if it does not have + * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link + * counts as a non-directory if and only if when fully + * dereferenced it points to a non-directory or its target is + * inaccessible. If a file has multiple names (hard links), it + * is only counted one time. */ uint64_t num_nondirs_scanned; /** Number of bytes of file data that have been detected so far. - * This data may not actually have been read yet, and it will - * not actually be written to the WIM file until wimlib_write() - * or wimlib_overwrite() has been called. */ + * + * Details: This data may not actually have been read yet, and + * it will not actually be written to the WIM file until + * wimlib_write() or wimlib_overwrite() has been called. Data + * from excluded files is not counted. This number includes + * default file contents as well as named data streams and + * reparse point data. The size of reparse point data is + * tallied after any reparse-point fixups, and in the case of + * capturing a symbolic link on a UNIX-like system, the creation + * of the reparse point data itself. If a file has multiple + * names (hard links), its size(s) are only counted one time. + * On Windows, encrypted files have their encrypted size + * counted, not their unencrypted size; however, compressed + * files have their uncompressed size counted. */ uint64_t num_bytes_scanned; } scan; - /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, + /** 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 @@ -1177,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. */ @@ -1187,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 @@ -1392,6 +1496,24 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * 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 * @{ */ @@ -1553,29 +1675,21 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_RESERVED 0x00000800 -/** When writing streams in the resulting WIM file, pack multiple streams into a +/** + * 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. - * Furthermore, 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 - * 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. */ + * 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 -/** Compress all streams independently. This produces a WIM optimized for - * random access and compatibility, as noted in the documentation for - * ::WIMLIB_WRITE_RESOURCE_FLAG_PACK_STREAMS. For wimlib_write(), this is the - * default behavior. For wimlib_overwrite(), this is the default if the WIM file - * did not already contain packed streams. Also, for wimlib_overwrite(), if the - * WIM already contained packed streams, specifying this flag but not - * ::WIMLIB_WRITE_FLAG_REBUILD will cause new streams to be written unpacked, - * but the WIM itself will not be rebuilt and may still contain packed streams. - */ -#define WIMLIB_WRITE_FLAG_NO_PACK_STREAMS 0x00002000 - /** @} */ /** @ingroup G_general * @{ */ @@ -1608,6 +1722,14 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008 +/** Default to interpreting WIM paths case sensitively (default on UNIX-like + * systems). */ +#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010 + +/** Default to interpreting WIM paths case insensitively (default on Windows). + * This does not apply to mounted images. */ +#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020 + /** @} */ /** @ingroup G_nonstandalone_wims * @{ */ @@ -1717,97 +1839,6 @@ 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; - - /** Matches with length (in bytes) longer than this - * value are immediately taken without spending time on - * minimum-cost measurements. Suggested value: 32. */ - uint32_t num_fast_bytes; - - /** 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 LZX compression context. */ -struct wimlib_lzx_context; /** @} */ /** @ingroup G_general @@ -1894,6 +1925,7 @@ enum wimlib_error_code { WIMLIB_ERR_WIM_IS_READONLY, WIMLIB_ERR_WRITE, WIMLIB_ERR_XML, + WIMLIB_ERR_WIM_IS_ENCRYPTED, }; @@ -2437,6 +2469,56 @@ wimlib_extract_image_from_pipe(int pipe_fd, const wimlib_tchar *target, int extract_flags, 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 * @@ -2605,7 +2687,8 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); * Initialization function for wimlib. Call before using any other wimlib * function except wimlib_set_print_errors(). If not done manually, this * function will be called automatically with @p init_flags set to - * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. + * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again + * after it has already successfully run. * * @param init_flags * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. @@ -2787,198 +2870,6 @@ wimlib_join(const wimlib_tchar * const *swms, int wim_write_flags, wimlib_progress_func_t progress_func); -/** - * @ingroup G_compression - * - * Decompresses a block of LZMS-compressed data. - * - * 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. - * - * This decompressor only implements "raw" decompression, which decompresses a - * single LZMS-compressed block. This behavior is the same as that of - * Decompress() in the Windows 8 compression API when using a compression handle - * created with CreateDecompressor() with the Algorithm parameter specified as - * COMPRESS_ALGORITHM_LZMS | COMPRESS_RAW. Presumably, non-raw LZMS data - * is a container format from which the locations and sizes (both compressed and - * uncompressed) of the constituent blocks can be determined. - * - * This function should not be called for blocks with compressed size equal to - * uncompressed size, since such blocks are actually stored uncompressed. - * - * @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. - * - * @return - * 0 on success; non-zero on failure. - */ -extern int -wimlib_lzms_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); - -/** - * @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 - * 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) - _wimlib_deprecated; - -/** - * @ingroup G_compression - * - * Equivalent to wimlib_lzx_compress(), but uses the specified compression - * context, allocated by wimlib_lzx_alloc_context(). - */ -extern unsigned -wimlib_lzx_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 window_size - * Size of the LZX window. Must be a power of 2 between 2^15 and 2^21, - * inclusively. - * - * @param params - * Compression parameters to use, or @c NULL to use the default 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 window size or compression parameters were invalid. - * @retval ::WIMLIB_ERR_NOMEM - * Not enough memory to allocate the compression context. - */ -extern int -wimlib_lzx_alloc_context(uint32_t window_size, - const struct wimlib_lzx_params *params, - struct wimlib_lzx_context **ctx_pp); - -/** - * @ingroup G_compression - * - * Decompresses a block of LZX-compressed data as used in the WIM file format. - * - * Note that this will NOT work unmodified for LZX as used in the cabinet - * format, which is not the same as in the WIM format! - * - * This function is exported for convenience only and should only be used by - * library clients looking to make use of wimlib's compression code for another - * purpose. - * - * @param compressed_data - * Pointer to the compressed data. - * - * @param compressed_len - * Length of the compressed data, in bytes. - * - * @param uncompressed_data - * Pointer to the buffer into which to write the uncompressed data. - * - * @param uncompressed_len - * Length of the uncompressed data. It must be 32768 bytes or less. - * - * @return - * 0 on success; non-zero on failure. - */ -extern int -wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); - -/** - * @ingroup G_compression - * - * Equivalent to wimlib_lzx_decompress(), except the window size is specified in - * @p max_window_size as any power of 2 between 2^15 and 2^21, inclusively, and - * @p uncompressed_len may be any size less than or equal to @p max_window_size. - */ -extern int -wimlib_lzx_decompress2(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len, - uint32_t max_window_size); - -/** - * @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 - * - * Set the global default LZX compression parameters. - * - * @param params - * The LZX compression parameters to set. These default parameters will be - * used by any calls to wimlib_lzx_alloc_context() with @c NULL LZX - * parameters specified, as well as by any future compression performed by - * the library itself. Passing @p NULL here resets the default LZX - * parameters to their original value. - * - * @return 0 on success; nonzero on error. - * - * @retval ::WIMLIB_ERR_INVALID_PARAM - * The compression parameters were invalid. - */ -extern int -wimlib_lzx_set_default_params(const struct wimlib_lzx_params *params); - -/** - * @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_mounting_wim_images @@ -3497,28 +3388,39 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * increased compression chunk size is limited by the size of each file being * compressed. * - * WARNING: Changing the compression chunk size to any value other than the - * default of 32768 bytes eliminates compatibility with Microsoft's software, - * except when increasing the XPRESS chunk size before Windows 8. Chunk sizes - * other than 32768 are also incompatible with wimlib v1.5.3 and earlier. + * 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 compression format supports chunk - * sizes that are powers of 2 with exponents between 15 and 26 inclusively, - * whereas the LZX compression format supports chunk sizes that are powers - * of 2 with exponents between 15 and 21 inclusively. + * 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 ctype is not a supported chunk size. + * @p chunk_size is not a supported chunk size for the currently selected + * output compression type. */ extern int wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); +/** + * @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 * @@ -3535,12 +3437,21 @@ wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size); * * @return 0 on success; nonzero on error. * - * @retval ::WIMLIB_ERR_INVALID_PARAM + * @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 * @@ -3652,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), @@ -4032,62 +3940,363 @@ wimlib_write_to_fd(WIMStruct *wim, unsigned num_threads, wimlib_progress_func_t progress_func); +/** + * @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. + */ + /** * @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. * - * Compress a chunk of data using XPRESS compression. + * @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(). * - * 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. + * @return 0 on success; nonzero on error. * - * As of wimlib v1.6.0, this function can be used with @p chunk_size greater - * than 32768 bytes and is only limited by available memory. However, the - * XPRESS format itself still caps match offsets to 65535, so if a larger chunk - * size is chosen, then the matching will effectively occur in a sliding window - * over it. + * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE + * @p ctype was not a supported compression type. + * @retval ::WIMLIB_ERR_INVALID_PARAM + * The compression parameters were invalid. + * @retval ::WIMLIB_ERR_NOMEM + * Insufficient memory to allocate the compressor. + */ +extern int +wimlib_create_compressor(enum wimlib_compression_type ctype, + size_t max_block_size, + const struct wimlib_compressor_params_header *extra_params, + struct wimlib_compressor **compressor_ret); + +/** + * Losslessly compress a block of data using a compressor previously created + * with wimlib_create_compressor(). * - * @param 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. + * @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 written to @p out in bytes, or 0 if the - * data could not be compressed to (@p chunk_size - 1) bytes or fewer. + * 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 unsigned -wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out); +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); /** - * @ingroup G_compression + * Free a compressor previously allocated with wimlib_create_compressor(). * - * Decompresses a chunk of XPRESS-compressed data. + * @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(). * - * 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 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. * - * @param compressed_data - * Pointer to the compressed data. + * @return 0 on success; nonzero on error. * - * @param compressed_len - * Length of the compressed data, in bytes. + * @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 - * Pointer to the buffer into which to write the 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(). * - * @param uncompressed_len - * Length of the uncompressed data. + * @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(). * - * @return - * 0 on success; non-zero on failure. + * @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_xpress_decompress(const void *compressed_data, unsigned compressed_len, - void *uncompressed_data, unsigned uncompressed_len); +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 }