X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;ds=sidebyside;f=include%2Fwimlib.h;h=c2cd9f03043231272b2ad9bc7843d22c31d18e45;hb=345d31902b50d440b918d2ec3a16c0f4bfff08ad;hp=ab1b78b2b772c2b197f8e62bd8ed64020e16df29;hpb=157b27cfdcdb01215cacfa3d16b2252f3eb889bd;p=wimlib

diff --git a/include/wimlib.h b/include/wimlib.h
index ab1b78b2..c2cd9f03 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.3, a C
+ * This is the documentation for the library interface of wimlib 1.6.0, 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
@@ -262,8 +262,12 @@
  * Another function, wimlib_extract_files(), is also provided.  It can extract
  * certain files or directories from a WIM image, instead of a full image.
  *
- * A third function, wimlib_extract_image_from_pipe(), allows an image to be
- * extracted from a pipable WIM sent over a pipe; see @ref subsec_pipable_wims.
+ * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a set
+ * of paths from a WIM image in a manner that may be easier to use than
+ * wimlib_extract_files(), and also can wildcard characters.
+ *
+ * wimlib_extract_image_from_pipe() allows an image to be extracted from a
+ * pipable WIM sent over a pipe; see @ref subsec_pipable_wims.
  *
  * Note that some details of how image extraction/application works are
  * documented more fully in the manual pages for <b>wimlib-imagex apply</b> and
@@ -343,10 +347,10 @@
 #define WIMLIB_MAJOR_VERSION 1
 
 /** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 5
+#define WIMLIB_MINOR_VERSION 6
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 3
+#define WIMLIB_PATCH_VERSION 0
 
 #ifdef __cplusplus
 extern "C" {
@@ -417,8 +421,7 @@ enum wimlib_compression_type {
 	/** Compressed resources in the WIM use XPRESS compression. */
 	WIMLIB_COMPRESSION_TYPE_XPRESS = 2,
 
-	/** Compressed resources in the WIM use LZMS compression.  Currently,
-	 * wimlib has a decompressor for this format but not a compressor.  LZMS
+	/** Compressed resources in the WIM use LZMS compression.  Note: LZMS
 	 * compression is only compatible with wimlib v1.6.0 and later and with
 	 * WIMGAPI Windows 8 and later (and some restrictions apply on the
 	 * latter).  */
@@ -437,8 +440,8 @@ enum wimlib_progress_msg {
 	 * ::wimlib_progress_info.extract. */
 	WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0,
 
-	/** A file or directory tree within a WIM image (not the full image) is
-	 * about to be extracted.  @p info will point to
+	/** One or more file or directory trees within a WIM image (not the full
+	 * image) is about to be extracted.  @p info will point to
 	 * ::wimlib_progress_info.extract. */
 	WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
 
@@ -690,7 +693,8 @@ union wimlib_progress_info {
 
 		/** Path to the root dentry within the WIM for the tree that is
 		 * being extracted.  Will be the empty string when extracting a
-		 * full image. */
+		 * full image, or when extracting a set of paths using
+		 * wimlib_extract_paths() or wimlib_extract_pathlist().  */
 		const wimlib_tchar *extract_root_wim_source_path;
 
 		/** Currently only used for
@@ -1383,6 +1387,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * performance.  */
 #define WIMLIB_EXTRACT_FLAG_FILE_ORDER			0x00020000
 
+/** For wimlib_extract_paths() and wimlib_extract_pathlist() only:  Treat the
+ * paths in the WIM as case-insensitive globs which may contain the characters
+ * '?' and '*'.  The '?' character matches any character, whereas the '*'
+ * character matches zero or more characters in the same path component.  */
+#define WIMLIB_EXTRACT_FLAG_GLOB_PATHS			0x00040000
+
+/** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error
+ * (::WIMLIB_ERR_PATH_DOES_NOT_EXIST) rather than a warning to be issued when
+ * one of the provided globs did not match a file.  */
+#define WIMLIB_EXTRACT_FLAG_STRICT_GLOB			0x00080000
+
 /** @} */
 /** @ingroup G_mounting_wim_images
  * @{ */
@@ -1544,29 +1559,21 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 
 #define WIMLIB_WRITE_FLAG_RESERVED			0x00000800
 
-/** When writing streams in the resulting WIM file, pack multiple streams into a
+/**
+ * When writing streams in the resulting WIM file, pack multiple streams into a
  * single WIM resource instead of compressing them independently.  This tends to
  * produce a better compression ratio at the cost of less random access.
- * Furthermore, WIMs created with this flag are only compatible with wimlib
- * v1.6.0 or later and WIMGAPI Windows 8 or later, seemingly for Windows Setup
- * only and <b>not including ImageX and Dism</b>.  WIMs created with this flag
- * use version number 3584 in their header instead of 68864.  If this flag is
- * passed to wimlib_overwrite() and the WIM did not previously contain packed
- * streams, the WIM's version number will be changed to 3584 and the new streams
- * will be written packed.  */
+ * However, WIMs created with this flag are only compatible with wimlib v1.6.0
+ * or later and WIMGAPI Windows 8 or later, seemingly for Windows Setup only and
+ * <b>not including ImageX and Dism</b>.  WIMs created with this flag must use
+ * version number 3584 in their header instead of 68864.
+ *
+ * If this flag is passed to wimlib_overwrite() and the WIM did not previously
+ * contain packed streams, the WIM's version number will be changed to 3584 and
+ * the new streams will be written packed.  Use ::WIMLIB_WRITE_FLAG_REBUILD to
+ * force the WIM to be fully rebuilt.  */
 #define WIMLIB_WRITE_FLAG_PACK_STREAMS			0x00001000
 
-/** Compress all streams independently.  This produces a WIM optimized for
- * random access and compatibility, as noted in the documentation for
- * ::WIMLIB_WRITE_RESOURCE_FLAG_PACK_STREAMS.  For wimlib_write(), this is the
- * default behavior. For wimlib_overwrite(), this is the default if the WIM file
- * did not already contain packed streams.  Also, for wimlib_overwrite(), if the
- * WIM already contained packed streams, specifying this flag but not
- * ::WIMLIB_WRITE_FLAG_REBUILD will cause new streams to be written unpacked,
- * but the WIM itself will not be rebuilt and may still contain packed streams.
- */
-#define WIMLIB_WRITE_FLAG_NO_PACK_STREAMS		0x00002000
-
 /** @} */
 /** @ingroup G_general
  * @{ */
@@ -1599,6 +1606,14 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES	0x00000008
 
+/** Default to interpreting WIM paths case sensitively (default on UNIX-like
+ * systems).  */
+#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE		0x00000010
+
+/** Default to interpreting WIM paths case insensitively (default on Windows).
+ * This does not apply to mounted images.  */
+#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE	0x00000020
+
 /** @} */
 /** @ingroup G_nonstandalone_wims
  * @{ */
@@ -2337,6 +2352,40 @@ wimlib_extract_image_from_pipe(int pipe_fd,
 			       const wimlib_tchar *target, int extract_flags,
 			       wimlib_progress_func_t progress_func);
 
+/**
+ * Similar to wimlib_extract_paths(), but the paths to extract from the WIM
+ * image specified in the UTF-8 text file @p path_list_file which itself
+ * contains the list of paths to use, one per line.  Leading and trailing
+ * whitespace, and otherwise empty lines and lines beginning with the ';'
+ * character are ignored.  No quotes are needed as paths are otherwise delimited
+ * by the newline character.
+ */
+extern int
+wimlib_extract_pathlist(WIMStruct *wim, int image,
+			const wimlib_tchar *target,
+			const wimlib_tchar *path_list_file,
+			int extract_flags,
+			wimlib_progress_func_t progress_func);
+
+/**
+ * Similar to wimlib_extract_files(), but the files or directories to extract
+ * from the WIM image are specified as an array of paths.  Each path will be
+ * extracted to a corresponding location in @p target based on its location in
+ * the WIM image.
+ *
+ * With ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified in @p extract_flags, this
+ * function additionally allows paths to be globs using the wildcard characters
+ * '*' and '?'.
+ */
+extern int
+wimlib_extract_paths(WIMStruct *wim,
+		     int image,
+		     const wimlib_tchar *target,
+		     const wimlib_tchar * const *paths,
+		     size_t num_paths,
+		     int extract_flags,
+		     wimlib_progress_func_t progress_func);
+
 /**
  * @ingroup G_wim_information
  *
@@ -3216,7 +3265,9 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
  *	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.
+ *	of 2 with exponents between 15 and 21 inclusively.  As a special case,
+ *	if @p out_chunk_size is specified as 0, the chunk size is set to the
+ *	default for the currently selected output compression type.
  *
  * @return 0 on success; nonzero on error.
  *
@@ -3226,6 +3277,15 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
 extern int
 wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size);
 
+/**
+ * @ingroup G_writing_and_overwriting_wims
+ *
+ * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing
+ * packed streams.
+ */
+extern int
+wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size);
+
 /**
  * @ingroup G_writing_and_overwriting_wims
  *
@@ -3242,12 +3302,21 @@ wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size);
  *
  * @return 0 on success; nonzero on error.
  *
- * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
  *	@p ctype did not specify a valid compression type.
  */
 extern int
 wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
 
+/**
+ * @ingroup G_writing_and_overwriting_wims
+ *
+ * Similar to wimlib_set_output_compression_type(), but set the compression type
+ * for writing packed streams.
+ */
+extern int
+wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
+
 /**
  * @ingroup G_modifying_wims
  *