X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=49bbffed1729ccc3b2885fcd59c71bb25b8b5a39;hp=7e89f4a7676076027da8c4a87fdba6f54bd3fff3;hb=4f9ccdbed3ee79171d0b861c4ba93b54ce8feaac;hpb=6f1261c57e213d6f12cb7aa8f858f2971bee687e

diff --git a/include/wimlib.h b/include/wimlib.h
index 7e89f4a7..49bbffed 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.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
@@ -355,7 +355,7 @@
 #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" {
@@ -1501,12 +1501,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * 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
@@ -1692,11 +1687,9 @@ struct wimlib_lzx_params {
 
 			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
@@ -1704,18 +1697,21 @@ struct wimlib_lzx_params {
 			 * 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
@@ -2374,6 +2370,8 @@ wimlib_extract_image_from_pipe(int pipe_fd,
  * 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).
@@ -2498,6 +2496,36 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
 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
  *
@@ -2710,7 +2738,8 @@ wimlib_join(const wimlib_tchar * const *swms,
  * 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
@@ -2731,9 +2760,12 @@ wimlib_lzx_compress2(const void *chunk, unsigned chunk_size, void *out,
  * 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
@@ -2745,23 +2777,15 @@ wimlib_lzx_compress2(const void *chunk, unsigned chunk_size, void *out,
  * @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
  *
@@ -2793,6 +2817,49 @@ extern int
 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
@@ -3299,6 +3366,60 @@ extern int
 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
  *
@@ -3793,8 +3914,28 @@ wimlib_write_to_fd(WIMStruct *wim,
 /**
  * @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);
@@ -3802,8 +3943,26 @@ 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,