*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.5.0, 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 0
+#define WIMLIB_PATCH_VERSION 3
#ifdef __cplusplus
extern "C" {
* already implied for wimlib_overwrite(). */
#define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400
+#define WIMLIB_WRITE_FLAG_RESERVED 0x00000800
+
/** @} */
/** @ingroup G_general
* @{ */
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;
+
+ /** 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: 0.
+ */
+ uint32_t num_split_passes;
+
+ /** 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
* @{ */
* 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
*
* format and therefore requires (@p chunk_size <= 32768).
*/
extern unsigned
-wimlib_lzx_compress(const void *chunk, unsigned chunk_size, void *out);
+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
+ * <code>*ctx_ret == NULL</code>, the new context is allocated. If
+ * <code>*ctx_ret != NULL</code>, 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
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