/**
* Specifies a compression format. Pass one of these values to
- * wimlib_create_new_wim(), wimlib_create_compressor(), or
- * wimlib_create_decompressor().
+ * wimlib_create_new_wim(), wimlib_set_output_compression_type(),
+ * wimlib_create_compressor(), or wimlib_create_decompressor().
*
* A WIM file has one default compression type and chunk size. Normally, each
- * resource is compressed with this compression type. However, resources may be
- * stored as uncompressed. In addition, a WIM with the new version number of
- * 3584, or "ESD file", might contain solid blocks with different compression
- * types.
+ * resource in the WIM file is compressed with this compression type. However,
+ * resources may be stored as uncompressed; for example, wimlib will do so if a
+ * resource does not compress to less than its original size. In addition, a
+ * WIM with the new version number of 3584, or "ESD file", might contain solid
+ * blocks with different compression types.
*/
enum wimlib_compression_type {
- /** No compression. */
+ /**
+ * No compression.
+ *
+ * This is a valid argument to wimlib_create_new_wim() and
+ * wimlib_set_output_compression_type(), but not to the functions in the
+ * compression API such as wimlib_create_compressor().
+ */
WIMLIB_COMPRESSION_TYPE_NONE = 0,
- /** The XPRESS compression format. This format combines Lempel-Ziv
+ /**
+ * The XPRESS compression format. This format combines Lempel-Ziv
* factorization with Huffman encoding. Compression and decompression
* are both fast. This format supports chunk sizes that are powers of 2
- * between <c>2^12</c> and <c>2^26</c>, inclusively. */
+ * between <c>2^12</c> and <c>2^16</c>, inclusively.
+ *
+ * wimlib's XPRESS compressor will, with the default settings, usually
+ * produce a better compression ratio, and work more quickly, than the
+ * implementation in Microsoft's WIMGAPI (as of Windows 8.1).
+ * Non-default compression levels are also supported. For example,
+ * level 80 will enable two-pass optimal parsing, which is significantly
+ * slower but usually improves compression by several percent over the
+ * default level of 50.
+ *
+ * If using wimlib_create_compressor() to create an XPRESS compressor
+ * directly, the @p max_block_size parameter may be any positive value
+ * up to <c>2^16</c>.
+ */
WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
- /** The LZX compression format. This format combines Lempel-Ziv
+ /**
+ * The LZX compression format. This format combines Lempel-Ziv
* factorization with Huffman encoding, but with more features and
* complexity than XPRESS. Compression is slow to somewhat fast,
* depending on the settings. Decompression is fast but slower than
* XPRESS. This format supports chunk sizes that are powers of 2
* between <c>2^15</c> and <c>2^21</c>, inclusively. Note: chunk sizes
* other than <c>2^15</c> are not compatible with the Microsoft
- * implementation. */
+ * implementation.
+ *
+ * wimlib's LZX compressor will, with the default settings, usually
+ * produce a better compression ratio, and work more quickly, than the
+ * implementation in Microsoft's WIMGAPI (as of Windows 8.1).
+ * Non-default compression levels are also supported. For example,
+ * level 20 will provide fast compression, almost as fast as XPRESS.
+ *
+ * If using wimlib_create_compressor() to create an LZX compressor
+ * directly, the @p max_block_size parameter may be any positive value
+ * up to <c>2^21</c>.
+ */
WIMLIB_COMPRESSION_TYPE_LZX = 2,
- /** The LZMS compression format. This format combines Lempel-Ziv
+ /**
+ * The LZMS compression format. This format combines Lempel-Ziv
* factorization with adaptive Huffman encoding and range coding.
* Compression and decompression are both fairly slow. This format
* supports chunk sizes that are powers of 2 between <c>2^15</c> and
* sizes. Note: LZMS compression is only compatible with wimlib v1.6.0
* and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and
* later. Also, chunk sizes larger than <c>2^26</c> are not compatible
- * with the Microsoft implementation. */
+ * with the Microsoft implementation.
+ *
+ * wimlib's LZMS compressor is currently faster but will usually not
+ * compress as much as the implementation in Microsoft's WIMGAPI
+ * (Windows 8.1).
+ *
+ * If using wimlib_create_compressor() to create an LZMS compressor
+ * directly, the @p max_block_size parameter may be any positive value
+ * up to <c>2^31 - 2</c>.
+ */
WIMLIB_COMPRESSION_TYPE_LZMS = 3,
};
* single extraction operation for optimization purposes. */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1,
+ /** This message may be sent periodically (not for every file) while
+ * files or directories are being created, prior to data stream
+ * extraction. @p info will point to ::wimlib_progress_info.extract.
+ */
+ WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE = 3,
+
/** File data is currently being extracted. @p info will point to
* ::wimlib_progress_info.extract. This is the main message to track
* the progress of an extraction operation. */
* @p info will point to ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5,
+ /** This message may be sent periodically (not for every file) while
+ * file and directory metadata is being applied, following data stream
+ * extraction. @p info will point to ::wimlib_progress_info.extract.
+ */
+ WIMLIB_PROGRESS_MSG_EXTRACT_METADATA = 6,
+
/** Confirms that the image has been successfully extracted. @p info
* will point to ::wimlib_progress_info.extract. This is paired with
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN. */
* ::wimlib_progress_info.done_with_file. This message is only received
* if ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided. */
WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26,
+
+ /** wimlib_verify_wim() is starting to verify the metadata for an image.
+ * @p info will point to ::wimlib_progress_info.verify_image. */
+ WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE = 27,
+
+ /** wimlib_verify_wim() has finished verifying the metadata for an
+ * image. @p info will point to ::wimlib_progress_info.verify_image.
+ */
+ WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE = 28,
+
+ /** wimlib_verify_wim() is verifying stream integrity. @p info will
+ * point to ::wimlib_progress_info.verify_streams. */
+ WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29,
};
/** Valid return values from user-provided progress functions
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, and
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END.
*
*/
const wimlib_tchar *path_to_file;
} done_with_file;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE and
+ * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE. */
+ struct wimlib_progress_info_verify_image {
+ const wimlib_tchar *wimfile;
+ uint32_t total_images;
+ uint32_t current_image;
+ } verify_image;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS. */
+ struct wimlib_progress_info_verify_streams {
+ const wimlib_tchar *wimfile;
+ uint64_t total_streams;
+ uint64_t total_bytes;
+ uint64_t completed_streams;
+ uint64_t completed_bytes;
+ } verify_streams;
};
/**
/** @addtogroup G_modifying_wims
* @{ */
-/** Directly capture an NTFS volume rather than a generic directory. This flag
- * cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
- * ::WIMLIB_ADD_FLAG_UNIX_DATA. */
+/** UNIX-like systems only: Directly capture an NTFS volume rather than a
+ * generic directory. This requires that wimlib was compiled with support for
+ * libntfs-3g.
+ *
+ * This flag cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA.
+ *
+ * Do not use this flag on Windows, where wimlib already supports all
+ * Windows-native filesystems, including NTFS, through the Windows APIs. */
#define WIMLIB_ADD_FLAG_NTFS 0x00000001
-/** Follow symlinks; archive and dump the files they point to. Currently only
+/** Follow symbolic links when scanning the directory tree. Currently only
* supported on UNIX-like systems. */
#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
* scanned. */
#define WIMLIB_ADD_FLAG_VERBOSE 0x00000004
-/** Mark the image being added as the bootable image of the WIM. Not valid for
- * wimlib_update_image(). */
+/** Mark the image being added as the bootable image of the WIM. This flag is
+ * valid only for wimlib_add_image() and wimlib_add_image_multisource().
+ *
+ * Note that you can also change the bootable image of a WIM using
+ * wimlib_set_wim_info().
+ *
+ * Note: ::WIMLIB_ADD_FLAG_BOOT does something different from, and independent
+ * from, ::WIMLIB_ADD_FLAG_WIMBOOT. */
#define WIMLIB_ADD_FLAG_BOOT 0x00000008
/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID
- * (major and minor number) of each file. See the documentation for the
+ * (major and minor number) of each file. Also allows capturing special files
+ * such as device nodes and FIFOs. See the documentation for the
* <b>--unix-data</b> option to <b>wimlib-imagex capture</b> for more
* information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
- * mode, or in Windows 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 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
/** Call the progress function with the message
* ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from
* capture. This is a subset of the messages provided by
- * ::WIMLIB_ADD_FLAG_VERBOSE. */
+ * ::WIMLIB_ADD_FLAG_VERBOSE. */
#define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE 0x00000080
-/** Reparse-point fixups: Modify absolute symbolic links (or junction points,
- * in the case of Windows) that point inside the directory being captured to
- * instead be absolute relative to the directory being captured, rather than the
- * current root.
+/** Reparse-point fixups: Modify absolute symbolic links (and junctions, in the
+ * case of Windows) that point inside the directory being captured to instead be
+ * absolute relative to the directory being captured.
*
- * Without this flag, the default is to do this if WIM_HDR_FLAG_RP_FIX is set in
- * the WIM header or if this is the first image being added.
- * WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is captured with
- * reparse point fixups enabled and currently cannot be unset. */
+ * Without this flag, the default is to do reparse-point fixups if
+ * WIM_HDR_FLAG_RP_FIX is set in the WIM header or if this is the first image
+ * being added. WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is
+ * captured with reparse point fixups enabled and currently cannot be unset. */
#define WIMLIB_ADD_FLAG_RPFIX 0x00000100
-/** Don't do reparse point fixups. The default behavior is described in the
- * documentation for ::WIMLIB_ADD_FLAG_RPFIX. */
+/** Don't do reparse point fixups. See ::WIMLIB_ADD_FLAG_RPFIX. */
#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200
/** Do not automatically exclude unsupported files or directories from capture;
* e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on
- * UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
- * such a file is encountered. */
+ * UNIX-like systems when not also using ::WIMLIB_ADD_FLAG_UNIX_DATA. Instead,
+ * fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered. */
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
/**
* Automatically select a capture configuration appropriate for capturing
* filesystems containing Windows operating systems. For example,
- * "pagefile.sys" and "System Volume Information" will be excluded.
+ * "/pagefile.sys" and "System Volume Information" will be excluded.
*
- * When this flag is specified, the corresponding @p config parameter or member
- * must be @c NULL.
+ * When this flag is specified, the corresponding @p config parameter (for
+ * wimlib_add_image()) or member (for wimlib_update_image()) must be @c NULL.
+ * Otherwise, ::WIMLIB_ERR_INVALID_PARAM will be returned.
*
- * Note that the default behavior--- that is, when this flag is not specified
- * and @p config is @c NULL--- is to use no capture configuration, meaning that
- * no files are excluded from capture.
+ * Note that the default behavior--- that is, when neither
+ * ::WIMLIB_ADD_FLAG_WINCONFIG nor ::WIMLIB_ADD_FLAG_WIMBOOT is specified and @p
+ * config is @c NULL--- is to use no capture configuration, meaning that no
+ * files are excluded from capture.
*/
#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
*
* since that makes access to the data faster (at the cost of a worse
* compression ratio compared to the 32768-byte LZX chunks usually used).
+ *
+ * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and
+ * independent from, ::WIMLIB_ADD_FLAG_BOOT.
*/
#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
* all streams recompressed in solid mode.
*
* Currently, new solid blocks will, by default, be written using LZMS
- * compression with 64 MiB (67108864 byte) chunks. Use
+ * compression with 32 MiB (33554432 byte) chunks. Use
* wimlib_set_output_pack_compression_type() and/or
* wimlib_set_output_pack_chunk_size() to change this. This is independent of
* the WIM's main compression type and chunk size; you can have a WIM that
*
* If a progress function is registered with @p wim, then as each image is
* extracted it will receive ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, then
- * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then
+ * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE messages, then zero
+ * or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then zero or more
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, then
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END.
*/
extern int
* The error code returned by one of wimlib's functions.
*
* @return
- * Pointer to a statically allocated string describing the error code,
- * or @c NULL if the error code is not valid.
+ * Pointer to a statically allocated string describing the error code. If
+ * the error code is for some reason not recognized by the library, the
+ * string will be "Unknown error".
*/
extern const wimlib_tchar *
wimlib_get_error_string(enum wimlib_error_code code);
const wimlib_tchar *image_name_or_num);
/**
+ * @ingroup G_general
+ *
* Sets the file to which the library will print error and warning messages.
*
* This version of the function takes a C library <c>FILE *</c> opened for
wimlib_set_error_file(FILE *fp);
/**
+ * @ingroup G_general
+ *
* Sets the path to the file to which the library will print error and warning
* messages. The library will open this file for appending.
*
* wimlib was compiled using the <c>--without-error-messages</c> option.
*/
extern int
-wimlib_set_error_file_by_name(const char *path);
+wimlib_set_error_file_by_name(const wimlib_tchar *path);
/**
* @ingroup G_modifying_wims
uint64_t part_size,
int write_flags);
+/**
+ * @ingroup G_general
+ *
+ * Perform verification checks on a WIM file.
+ *
+ * @param wim
+ * The ::WIMStruct for the WIM file to verify. Note: for an extra layer of
+ * verification, it is a good idea to have used
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY when you opened the file.
+ * <br/>
+ * If verifying a split WIM, specify the first part of the split WIM here,
+ * and reference the other parts using wimlib_reference_resource_files()
+ * before calling this function.
+ *
+ * @param verify_flags
+ * Reserved; must be 0.
+ *
+ * @retval 0 if the WIM file was successfully verified; nonzero if it failed
+ * verification or another error occurred. Some of the possible error codes
+ * are:
+ *
+ * @retval ::WIMLIB_ERR_DECOMPRESSION
+ * A compressed resource could not be decompressed.
+ * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE
+ * The metadata resource for an image is invalid.
+ * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
+ * One of the files did not decompress to its original data, as given by a
+ * cryptographic checksum.
+ * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
+ * One of the files referenced by an image could not be located.
+ *
+ * If a progress function is registered with @p wim, it will receive the
+ * following progress messages: ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE,
+ * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE, and
+ * ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS.
+ */
+extern int
+wimlib_verify_wim(WIMStruct *wim, int verify_flags);
+
/**
* @ingroup G_mounting_wim_images
*
/**
* @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.
+ * @brief Functions for XPRESS, LZX, and LZMS compression and decompression.
*
- * 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.
+ * These functions are already used by wimlib internally when appropriate for
+ * reading and writing WIM archives. But they are exported and documented so
+ * that they can be used in other applications or libraries for general-purpose
+ * lossless data compression. They are implemented in highly optimized C code,
+ * using state-of-the-art compression techniques. The main limitation is the
+ * lack of sliding window support; this has, however, allowed the algorithms to
+ * be optimized for block-based 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. */
-#define WIMLIB_LZX_ALGORITHM_FAST 0
-
- /** Slower LZX compression algorithm that provides a better compression
- * ratio. This is the default. */
-#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 can only output
- * 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;
-
- /* Note: max_matches_per_pos has been removed and no
- * longer has any effect. */
-
- uint32_t slow_reserved2[3];
-
- /** 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;
-};
-
-/** LZMS compression parameters that can optionally be passed to
- * wimlib_create_compressor() with the compression type
- * ::WIMLIB_COMPRESSION_TYPE_LZMS. */
-struct wimlib_lzms_compressor_params {
- /** hdr.size Must be set to the size of this structure, in bytes. */
- struct wimlib_compressor_params_header hdr;
-
- /** Minimum match length to output. This must be at least 2. Suggested
- * value: 2 */
- uint32_t min_match_length;
-
- /** Maximum match length to output. This must be at least @p
- * min_match_length. Suggested value: @p UINT32_MAX. */
- uint32_t max_match_length;
-
- /** Matches with length (in bytes) greater than or equal to this value
- * are immediately taken without spending time on minimum-cost
- * measurements. The minimum of @p max_match_length and @p
- * nice_match_length may not exceed 65536. Suggested value: 32. */
- uint32_t nice_match_length;
-
- /** Maximum depth to search for matches at each position. Suggested
- * value: 50. */
- uint32_t max_search_depth;
-
- /* Note: max_matches_per_pos has been removed and no longer has any
- * effect. */
-
- uint32_t reserved1;
-
- /** Length of the array for the near-optimal LZ parsing algorithm. This
- * must be at least 1. Suggested value: 1024. */
- uint32_t optim_array_length;
-
- uint64_t reserved2[4];
-};
-
/** Opaque compressor handle. */
struct wimlib_compressor;
struct wimlib_decompressor;
/**
- * Set the default compression parameters for the specified compression type.
- * This will affect both explicit and library-internal calls to
- * wimlib_create_compressor().
+ * Set the default compression level for the specified compression type. This
+ * is the compression level that wimlib_create_compressor() assumes if it is
+ * called with @p compression_level specified as 0.
+ *
+ * wimlib's WIM writing code (e.g. wimlib_write()) will pass 0 to
+ * wimlib_create_compressor() internally. Therefore, calling this function will
+ * affect the compression level of any data later written to WIM files using the
+ * specified compression type.
+ *
+ * The initial state, before this function is called, is that all compression
+ * types have a default compression level of 50.
*
* @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.
+ * Compression type for which to set the default compression level, as one
+ * of the ::wimlib_compression_type constants. Or, if this is the special
+ * value -1, the default compression levels for all compression types will
+ * be set.
+ * @param compression_level
+ * The default compression level to set. If 0, the "default default" level
+ * of 50 is restored. Otherwise, a higher value indicates higher
+ * compression, whereas a lower value indicates lower compression. See
+ * wimlib_create_compressor() for more information.
*
* @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
- * @p params were invalid.
- * @retval ::WIMLIB_ERR_NOMEM
- * Not enough memory to duplicate the parameters (perhaps @c params->size
- * was invalid).
+ * @p ctype was neither a supported compression type nor -1.
*/
extern int
-wimlib_set_default_compressor_params(enum wimlib_compression_type ctype,
- const struct wimlib_compressor_params_header *params);
+wimlib_set_default_compression_level(int ctype, unsigned int compression_level);
/**
* Returns the approximate number of bytes needed to allocate a compressor with
- * wimlib_create_compressor() for the specified compression type, block size,
- * and parameters. @p params may be @c NULL, in which case the current default
- * parameters for @p ctype are used. Returns 0 if the compression type or
- * parameters are invalid.
+ * wimlib_create_compressor() for the specified compression type, maximum block
+ * size, and compression level. @p compression_level may be 0, in which case
+ * the current default compression level for @p ctype is used. Returns 0 if the
+ * compression type is invalid.
*/
extern uint64_t
wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype,
size_t max_block_size,
- const struct wimlib_compressor_params_header *params);
+ unsigned int compression_level);
/**
* Allocate a compressor for the specified compression type using the specified
* necessary to call this to process a WIM file.
*
* @param ctype
- * Compression type for which to create the compressor.
+ * Compression type for which to create the compressor, as one of the
+ * ::wimlib_compression_type constants.
* @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. For LZMS, a pointer to
- * ::wimlib_lzms_compressor_params may be specified here. If left @c NULL,
- * the default parameters are used.
+ * The maximum compression block size to support. This specifies the
+ * maximum allowed value for the @p uncompressed_size parameter of
+ * wimlib_compress() when called using this compressor.
+ * <br/>
+ * Usually, the amount of memory used by the compressor will scale in
+ * proportion to the @p max_block_size parameter.
+ * wimlib_get_compressor_needed_memory() can be used to query the specific
+ * amount of memory that will be required.
+ * <br/>
+ * This parameter must be at least 1 and must be less than or equal to a
+ * compression-type-specific limit.
+ * <br/>
+ * In general, the same value of @p max_block_size must be passed to
+ * wimlib_create_decompressor() when the data is later decompressed.
+ * However, some compression types have looser requirements regarding this.
+ * @param compression_level
+ * The compression level to use. If 0, the default compression level (50,
+ * or another value as set through wimlib_set_default_compression_level())
+ * is used. Otherwise, a higher value indicates higher compression. The
+ * values are scaled so that 10 is low compression, 50 is medium
+ * compression, and 100 is high compression. This is not a percentage;
+ * values above 100 are also valid.
+ * <br/>
+ * Using a higher-than-default compression level can result in a better
+ * compression ratio, but can significantly reduce performance. Similarly,
+ * using a lower-than-default compression level can result in better
+ * performance, but can significantly worsen the compression ratio. The
+ * exact results will depend heavily on the compression type and what
+ * algorithms are implemented for it. If you are considering using a
+ * non-default compression level, you should run benchmarks to see if it is
+ * worthwhile for your application.
+ * <br/>
+ * The compression level does not affect the format of the compressed data.
+ * Therefore, it is a compressor-only parameter and does not need to be
+ * passed to the decompressor.
* @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().
+ * A location into which to return the pointer to the allocated compressor.
+ * The allocated compressor 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.
+ * @p max_block_size was invalid for the compression type, or @p
+ * compressor_ret was @c NULL.
* @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,
+ unsigned int compression_level,
struct wimlib_compressor **compressor_ret);
/**
- * Losslessly compress a block of data using a compressor previously created
- * with wimlib_create_compressor().
+ * Compress a buffer of data.
*
* @param uncompressed_data
* Buffer containing the data to compress.
* @param uncompressed_size
- * Size, in bytes, of the data to compress.
+ * Size, in bytes, of the data to compress. This cannot be greater than
+ * the @p max_block_size with which wimlib_create_compressor() was called.
+ * (If it is, the data will not be compressed and 0 will be returned.)
* @param compressed_data
* Buffer into which to write the compressed data.
* @param compressed_size_avail
* A compressor previously allocated with wimlib_create_compressor().
*
* @return
- * The size of the compressed data, in bytes, or 0 if the input data could
- * not be compressed to @p compressed_size_avail or fewer bytes.
+ * The size of the compressed data, in bytes, or 0 if the data could not be
+ * compressed to @p compressed_size_avail or fewer bytes.
*/
extern size_t
wimlib_compress(const void *uncompressed_data, size_t uncompressed_size,
* Free a compressor previously allocated with wimlib_create_compressor().
*
* @param compressor
- * The compressor to free.
+ * The compressor to free. If @c NULL, no action is taken.
*/
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 library-internal calls to
- * wimlib_create_decompressor().
+ * Allocate a decompressor for the specified compression type. This function is
+ * part of wimlib's compression API; it is not necessary to call this to process
+ * a WIM file.
*
* @param ctype
- * Compression type for which to set the default decompression parameters.
- * @param params
- * Compression-type specific parameters. This may be @c NULL, in which
- * case the "default default" parameters are restored.
- *
- * @return 0 on success; nonzero on error.
- *
- * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * @p ctype was not a supported compression type.
- * @retval ::WIMLIB_ERR_NOMEM
- * Not enough memory to duplicate the parameters (perhaps @c params->size
- * was invalid).
- */
-extern int
-wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype,
- const struct wimlib_decompressor_params_header *params);
-
-/**
- * Allocate a decompressor for the specified compression type using the
- * specified parameters. This function is part of wimlib's compression API; it
- * is not necessary to call this to process a WIM file.
- *
- * @param ctype
- * Compression type for which to create the decompressor.
+ * Compression type for which to create the decompressor, as one of the
+ * ::wimlib_compression_type constants.
* @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
+ * The maximum compression block size to support. This specifies the
+ * maximum allowed value for the @p uncompressed_size parameter of
* 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.
+ * <br/>
+ * In general, this parameter must be the same as the @p max_block_size
+ * that was passed to wimlib_create_compressor() when the data was
+ * compressed. However, some compression types have looser requirements
+ * regarding this.
* @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().
+ * decompressor. The allocated decompressor 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.
+ * @p max_block_size was invalid for the compression type, or @p
+ * decompressor_ret was @c NULL.
* @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().
+ * Decompress a buffer of data.
*
* @param compressed_data
* Buffer containing the data to decompress.
* @param uncompressed_data
* Buffer into which to write the uncompressed data.
* @param uncompressed_size
- * Size, in bytes, of the data when uncompressed.
+ * Size, in bytes, of the data when uncompressed. This cannot exceed the
+ * @p max_block_size with which wimlib_create_decompressor() was called.
+ * (If it does, the data will not be decompressed and a nonzero value will
+ * be returned.)
* @param decompressor
* A decompressor previously allocated with wimlib_create_decompressor().
*
* @return 0 on success; nonzero on error.
+ *
+ * No specific error codes are defined; any nonzero value indicates that the
+ * decompression failed. This can only occur if the data is truly invalid;
+ * there will never be transient errors like "out of memory", for example.
+ *
+ * This function requires that the exact uncompressed size of the data be passed
+ * as the @p uncompressed_size parameter. If this is not done correctly,
+ * decompression may fail or the data may be decompressed incorrectly.
*/
extern int
wimlib_decompress(const void *compressed_data, size_t compressed_size,
* Free a decompressor previously allocated with wimlib_create_decompressor().
*
* @param decompressor
- * The decompressor to free.
+ * The decompressor to free. If @c NULL, no action is taken.
*/
extern void
wimlib_free_decompressor(struct wimlib_decompressor *decompressor);
git://wimlib.net / wimlib / blobdiff