*
* @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.
+ * always output as one block. Suggested value: 0.
*/
uint32_t num_split_passes;
- uint32_t slow_reserved2[4];
+ /** 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
* Extracts the XML data of a WIM file to a file stream. Every WIM file
* includes a string of XML that describes the images contained in the WIM.
*
+ * See wimlib_get_xml_data() to read the XML data into memory instead.
+ *
* @param wim
* Pointer to the ::WIMStruct for a WIM file, which does not necessarily
* have to be standalone (e.g. it could be part of a split WIM).
extern int
wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info);
+/**
+ * @ingroup G_wim_information
+ *
+ * Read the XML data of a WIM file into an in-memory buffer. Every WIM file
+ * includes a string of XML that describes the images contained in the WIM.
+ *
+ * See wimlib_extract_xml_data() to extract the XML data to a file stream
+ * instead.
+ *
+ * @param wim
+ * Pointer to the ::WIMStruct for a WIM file, which does not necessarily
+ * have to be standalone (e.g. it could be part of a split WIM).
+ * @param buf_ret
+ * On success, a pointer to an allocated buffer containing the raw UTF16-LE
+ * XML data is written to this location.
+ * @param bufsize_ret
+ * The size of the XML data in bytes is written to this location.
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(), or
+ * @p buf_ret or @p bufsize_ret was @c NULL.
+ * @retval ::WIMLIB_ERR_NOMEM
+ * @retval ::WIMLIB_ERR_READ
+ * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
+ * Failed to read the XML data from the WIM.
+ */
+extern int
+wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret);
+
/**
* @ingroup G_general
*
* purpose.
*
* @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
wimlib_lzx_alloc_context(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);
+/**
+ * @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