*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.5.2, a C
+ * This is the documentation for the library interface of wimlib 1.5.3, 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
#define WIMLIB_MINOR_VERSION 5
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
#ifdef __cplusplus
extern "C" {
* already implied for wimlib_overwrite(). */
#define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400
-/** Use the slow LZX compression algorithm (rather than the default fast LZX
- * compression algorithm) to try to achieve a higher compression ratio. Only
- * has an effect if the WIM uses LZX compression; not to be confused with "fast"
- * (XPRESS) compression. This can be combined with
- * ::WIMLIB_WRITE_FLAG_RECOMPRESS. */
-#define WIMLIB_WRITE_FLAG_COMPRESS_SLOW 0x00000800
+#define WIMLIB_WRITE_FLAG_RESERVED 0x00000800
/** @} */
/** @ingroup G_general
uint32_t slow_reserved1 : 31;
- /** This is the maximum match length to return from the
- * binary tree match-finder. Any match reaching this
- * limit is still extended as far as possible. Must be
- * at least 3 and no more than 257. Suggested value:
- * 32. */
+ /** 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
* algorithm that attempts to minimize the cost of the
* match/literal sequence by using a cost model provided
* by the previous iteration. Must be at least 1.
- * Suggested value: 3. */
+ * Suggested value: 2. */
uint32_t num_optim_passes;
- /** The number of times to attempt to recursively split
- * each LZX block. Up to (2**(num_split_passes)
- * sub-blocks can be created for a given input. This
- * parameter can be 0, in which case the full input is
- * always output as one block. Suggested value: 3.
- */
- uint32_t num_split_passes;
+ /** 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;
- uint32_t slow_reserved2[4];
+ /** 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
* 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 algorithm
- * and parameters.
+ * 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
* @return 0 on success; nonzero on error.
*
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * The compression parameters were invalid.
+ * 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(const struct wimlib_lzx_params *params,
+wimlib_lzx_alloc_context(uint32_t window_size,
+ const struct wimlib_lzx_params *params,
struct wimlib_lzx_context **ctx_pp);
-/**
- * @ingroup G_compression
- *
- * Free the specified LZX compression context, allocated with
- * wimlib_lzx_alloc_context().
- */
-extern void
-wimlib_lzx_free_context(struct wimlib_lzx_context *ctx);
-
/**
* @ingroup G_compression
*
wimlib_lzx_decompress(const void *compressed_data, unsigned compressed_len,
void *uncompressed_data, unsigned uncompressed_len);
+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
wimlib_set_image_descripton(WIMStruct *wim, int image,
const wimlib_tchar *description);
+/**
+ * @ingroup G_writing_and_overwriting_wims
+ *
+ * Set the compression chunk size of a WIM to use in subsequent calls to
+ * wimlib_write() or wimlib_overwrite().
+ *
+ * A compression chunk size will result in a greater compression ratio, but the
+ * speed of random access to the WIM will be reduced, and the effect of an
+ * increased compression chunk size is limited by the size of each file being
+ * compressed.
+ *
+ * <b>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.</b>
+ *
+ * @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.
+ *
+ * @return 0 on success; nonzero on error.
+ *
+ * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE
+ * @p ctype is not a supported chunk size.
+ */
+extern int
+wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size);
+
+/**
+ * @ingroup G_writing_and_overwriting_wims
+ *
+ * Set the compression type of a WIM to use in subsequent calls to
+ * wimlib_write() or wimlib_overwrite().
+ *
+ * @param wim
+ * ::WIMStruct for a WIM.
+ * @param ctype
+ * The compression type to set (one of ::wimlib_compression_type). If this
+ * compression type is incompatible with the current output chunk size
+ * (either the default or as set with wimlib_set_output_chunk_size()), the
+ * output chunk size is reset to the default for that compression type.
+ *
+ * @return 0 on success; nonzero on error.
+ *
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p ctype did not specify a valid compression type.
+ */
+extern int
+wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
+
/**
* @ingroup G_modifying_wims
*
/**
* @ingroup G_compression
*
- * This function is equivalent to wimlib_lzx_compress(), but instead compresses
- * the data using "XPRESS" compression.
+ * Compress a chunk of data using XPRESS 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.
+ *
+ * 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.
+ *
+ * @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.
*/
extern unsigned
wimlib_xpress_compress(const void *chunk, unsigned chunk_size, void *out);
/**
* @ingroup G_compression
*
- * This function is equivalent to wimlib_lzx_decompress(), but instead assumes
- * the data is compressed using "XPRESS" compression.
+ * Decompresses a chunk of XPRESS-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.
+ *
+ * @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_xpress_decompress(const void *compressed_data, unsigned compressed_len,
git://wimlib.net / wimlib / blobdiff