X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=c1290e1f8fd75b3258893a70ef743713dca6b639;hp=82dd1afcea633d7f42342a325e80af55ad75d3e6;hb=7ac341b9d43bf1becd7d05f9ad2eed3d221de2d6;hpb=49a63aa13cdeb4c1348697ccd92207a1a65ec7b0
diff --git a/include/wimlib.h b/include/wimlib.h
index 82dd1afc..c1290e1f 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" {
@@ -425,6 +420,12 @@ 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,
};
/** @} */
@@ -439,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,
@@ -452,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.
@@ -524,9 +525,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
@@ -601,85 +600,176 @@ union wimlib_progress_info {
unsigned 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
@@ -944,48 +1034,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;
- /** 1 if this resource was not found in the lookup table of the
+ /** 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;
- uint32_t reserved_flags : 27;
- uint64_t reserved[4];
+ /** 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. */
@@ -1136,8 +1242,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. */
@@ -1146,17 +1252,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
@@ -1279,7 +1385,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
@@ -1342,6 +1450,31 @@ 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
+/** 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
* @{ */
@@ -1503,6 +1636,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
+ * 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
* @{ */
@@ -1535,6 +1683,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
* @{ */
@@ -1644,97 +1800,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
@@ -2364,6 +2429,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 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
*
@@ -2532,7 +2647,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.
@@ -2714,142 +2830,6 @@ wimlib_join(const wimlib_tchar * const *swms,
int wim_write_flags,
wimlib_progress_func_t progress_func);
-/**
- * @ingroup G_compression
- *
- * Compress a chunk of a WIM resource using LZX compression.
- *
- * This function is exported for convenience only and should only be used by
- * 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 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 compression parameters were invalid.
- * @retval ::WIMLIB_ERR_NOMEM
- * Not enough memory to allocate the compression context.
- */
-extern int
-wimlib_lzx_alloc_context(const struct wimlib_lzx_params *params,
- struct wimlib_lzx_context **ctx_pp);
-
-/**
- * @ingroup G_compression
- *
- * 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
- *
- * 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
@@ -2973,7 +2953,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.
@@ -3362,14 +3343,25 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
* 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 compression format supports chunk
* sizes that are powers of 2 with exponents between 15 and 26 inclusively,
- * whereas the LZX compression format currently only supports a chunk size
- * of 32768.
+ * 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.
*
@@ -3379,6 +3371,15 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
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
*
@@ -3395,12 +3396,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
*
@@ -3512,10 +3522,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),
@@ -3892,62 +3899,362 @@ 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) 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 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().
*
- * Compress a chunk of data using XPRESS compression.
+ * @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.
*
- * 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.5.4, 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_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_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().
+ *
+ * @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.
*
- * Decompresses a chunk of XPRESS-compressed data.
+ * @return 0 on success; nonzero on error.
*
- * 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.
+ * @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 compressed_data
- * Pointer to the compressed data.
+ * @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().
*
- * @param compressed_len
- * Length of the compressed data, in bytes.
+ * @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
}