X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=src%2Fwimlib.h;h=d3b0c9a6212188bb9e614da412d69c230ff7e519;hb=7e7070982833be4292431b7dbffa8280e27b3d8a;hp=4b46f21cac02965af253f4cb14cf1267afa00ab2;hpb=34c830edf813567274416e84816947d3383a6ac5;p=wimlib

diff --git a/src/wimlib.h b/src/wimlib.h
index 4b46f21c..d3b0c9a6 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -31,7 +31,7 @@
  *
  * \section intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.3.1.  If you
+ * This is the documentation for the library interface of wimlib 1.3.2.  If you
  * have installed wimlib and want to know how to use the @b wimlib-imagex
  * program, please see the man pages instead.  Also: the actual project page
  * where you can download the source code for the library is at <a
@@ -191,16 +191,16 @@
  * \section encodings Locales and character encodings
  *
  * To support Windows as well as UNIX, wimlib's API typically takes and returns
- * strings of "tchars", which are in a platform-dependent encoding.
+ * strings of ::wimlib_tchar, which are in a platform-dependent encoding.
  *
- * On Windows, each "tchar" is 2 bytes and is the same as a "wchar_t", and the
- * encoding is UTF-16LE.
+ * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t",
+ * and the encoding is UTF-16LE.
  *
- * On UNIX, each "tchar" is 1 byte and is simply a "char", and the encoding is
- * the locale-dependent multibyte encoding.  I recommend you set your locale to a
- * UTF-8 capable locale to avoid any issues.  Also, by default, wimlib on UNIX
- * will assume the locale is UTF-8 capable unless you call wimlib_global_init()
- * after having set your desired locale.
+ * On UNIX, each ::wimlib_tchar is 1 byte and is simply a "char", and the
+* encoding is the locale-dependent multibyte encoding.  I recommend you set your
+* locale to a UTF-8 capable locale to avoid any issues.  Also, by default,
+	* wimlib on UNIX will assume the locale is UTF-8 capable unless you call
+* wimlib_global_init() after having set your desired locale.
  *
  * \section Limitations
  *
@@ -210,8 +210,7 @@
  *   without mounting it, other than by adding, removing, or extracting an
  *   entire image.  The FUSE mount feature should be used for this purpose.
  * - Currently, Microsoft's @a image.exe can create slightly smaller WIM files
- *   than wimlib when using maximum (LZX) compression because it knows how to
- *   split up LZX compressed blocks, which is not yet implemented in wimlib.
+ *   than wimlib (~2% or 3% smaller) when using maximum (LZX) compression.
  * - wimlib is experimental and likely contains bugs; use Microsoft's @a
  *   imagex.exe if you want to make sure your WIM files are made "correctly".
  * - The old WIM format from Vista pre-releases is not supported.
@@ -254,7 +253,7 @@
 #define WIMLIB_MINOR_VERSION 3
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 2
 
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
@@ -274,6 +273,7 @@ typedef struct WIMStruct WIMStruct;
 #ifdef __WIN32__
 typedef wchar_t wimlib_tchar;
 #else
+/** See \ref encodings */
 typedef char wimlib_tchar;
 #endif
 
@@ -430,6 +430,8 @@ union wimlib_progress_info {
 		 * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or
 		 * ::WIMLIB_COMPRESSION_TYPE_LZX. */
 		int	 compression_type;
+
+		uint64_t _private;
 	} write_streams;
 
 	/** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
@@ -605,6 +607,46 @@ struct wimlib_capture_source {
 	long reserved;
 };
 
+/** Structure that specifies a list of path patterns. */
+struct wimlib_pattern_list {
+	/** Array of patterns.  The patterns may be modified by library code,
+	 * but the @a pats pointer itself will not.  See the man page for
+	 * <b>wimlib-imagex capture</b> for more information about allowed
+	 * patterns. */
+	tchar **pats;
+
+	/** Number of patterns in the @a pats array. */
+	size_t num_pats;
+
+	/** Ignored; may be used by the calling code. */
+	size_t num_allocated_pats;
+};
+
+/** A structure that contains lists of wildcards that match paths to treat
+ * specially when capturing a WIM image. */
+struct wimlib_capture_config {
+	/** Paths matching any pattern this list are excluded from being
+	 * captured, except if the same path appears in @a
+	 * exclusion_exception_pats. */
+	struct wimlib_pattern_list exclusion_pats;
+
+	/** Paths matching any pattern in this list are never excluded from
+	 * being captured. */
+	struct wimlib_pattern_list exclusion_exception_pats;
+
+	/** Reserved for future capture configuration options. */
+	struct wimlib_pattern_list reserved1;
+
+	/** Reserved for future capture configuration options. */
+	struct wimlib_pattern_list reserved2;
+
+	/** Library internal use only. */
+	tchar *_prefix;
+
+	/** Library internal use only. */
+	size_t _prefix_num_tchars;
+};
+
 
 /*****************************
  * WIMLIB_ADD_IMAGE_FLAG_*   *
@@ -638,6 +680,19 @@ struct wimlib_capture_source {
  * mode, or in Win32 native builds. */
 #define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS			0x00000020
 
+/** Fail immediately if the full security descriptor of any file or directory
+ * cannot be accessed.  Only has an effect in Win32 native builds.  The default
+ * behavior without this flag is to first try omitting the SACL from the
+ * security descriptor, then to try omitting the security descriptor entirely.
+ * */
+#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS		0x00000040
+
+/** Call the progress function with the message
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from
+ * capture.  This is a subset of the messages provided by
+ * ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE. */
+#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE		0x00000080
+
 /******************************
  * WIMLIB_EXPORT_FLAG_* *
  ******************************/
@@ -676,7 +731,14 @@ struct wimlib_capture_source {
 
 /** Do not extract security descriptors.  Only has an effect in NTFS apply mode,
  * or in Win32 native builds. */
-#define WIMLIB_EXTRACT_FLAG_NOACLS			0x00000040
+#define WIMLIB_EXTRACT_FLAG_NO_ACLS			0x00000040
+
+/** Fail immediately if the full security descriptor of any file or directory
+ * cannot be set exactly as specified in the WIM file.  The default behavior
+ * without this flag is to fall back to setting the security descriptor with the
+ * SACL omitted, then only the default inherited security descriptor, if we do
+ * not have permission to set the desired one. */
+#define WIMLIB_EXTRACT_FLAG_STRICT_ACLS			0x00000080
 
 /******************************
  * WIMLIB_MOUNT_FLAG_*        *
@@ -837,8 +899,7 @@ struct wimlib_modify_command {
  * added at the end to maintain a compatible ABI, except when it's being broken
  * anyway. */
 enum wimlib_error_code {
-	WIMLIB_ERR_SUCCESS = 0,
-	WIMLIB_ERR_ALREADY_LOCKED,
+	WIMLIB_ERR_ALREADY_LOCKED = 1,
 	WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
 	WIMLIB_ERR_DECOMPRESSION,
 	WIMLIB_ERR_DELETE_STAGING_DIR,
@@ -858,14 +919,16 @@ enum wimlib_error_code {
 	WIMLIB_ERR_INVALID_IMAGE,
 	WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
 	WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY,
+	WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
+	WIMLIB_ERR_INVALID_OVERLAY,
 	WIMLIB_ERR_INVALID_PARAM,
 	WIMLIB_ERR_INVALID_PART_NUMBER,
 	WIMLIB_ERR_INVALID_RESOURCE_HASH,
 	WIMLIB_ERR_INVALID_RESOURCE_SIZE,
 	WIMLIB_ERR_INVALID_SECURITY_DATA,
 	WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
-	WIMLIB_ERR_INVALID_UTF8_STRING,
 	WIMLIB_ERR_INVALID_UTF16_STRING,
+	WIMLIB_ERR_INVALID_UTF8_STRING,
 	WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
 	WIMLIB_ERR_LINK,
 	WIMLIB_ERR_MKDIR,
@@ -877,8 +940,8 @@ enum wimlib_error_code {
 	WIMLIB_ERR_NTFS_3G,
 	WIMLIB_ERR_OPEN,
 	WIMLIB_ERR_OPENDIR,
-	WIMLIB_ERR_READLINK,
 	WIMLIB_ERR_READ,
+	WIMLIB_ERR_READLINK,
 	WIMLIB_ERR_RENAME,
 	WIMLIB_ERR_REOPEN,
 	WIMLIB_ERR_RESOURCE_ORDER,
@@ -886,14 +949,13 @@ enum wimlib_error_code {
 	WIMLIB_ERR_SPLIT_INVALID,
 	WIMLIB_ERR_SPLIT_UNSUPPORTED,
 	WIMLIB_ERR_STAT,
+	WIMLIB_ERR_SUCCESS = 0,
 	WIMLIB_ERR_TIMEOUT,
+	WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
 	WIMLIB_ERR_UNKNOWN_VERSION,
 	WIMLIB_ERR_UNSUPPORTED,
 	WIMLIB_ERR_WRITE,
 	WIMLIB_ERR_XML,
-	WIMLIB_ERR_INVALID_OVERLAY,
-	WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
-	WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
 };
 
 
@@ -930,12 +992,9 @@ enum wimlib_error_code {
  * @param name
  * 	The name to give the image.  This must be non-@c NULL.
  * @param config
- * 	Pointer to the contents of an image capture configuration file.  If @c
- * 	NULL, a default string is used.  Please see the manual page for
- * 	<b>wimlib-imagex capture</b> for more information.
- * @param config_len
- * 	Length of the string @a config in bytes, not including an optional
- * 	null-terminator.  Ignored if @a config is @c NULL.
+ * 	Capture configuration that specifies files, directories, or path globs
+ * 	to exclude from being captured.  If @c NULL, a dummy configuration where
+ * 	no paths are treated specially is used.
  * @param add_image_flags
  * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
  * @param progress_func
@@ -990,8 +1049,7 @@ extern int
 wimlib_add_image(WIMStruct *wim,
 		 const wimlib_tchar *source,
 		 const wimlib_tchar *name,
-		 const wimlib_tchar *config,
-		 size_t config_len,
+		 struct wimlib_capture_config *config,
 		 int add_image_flags,
 		 wimlib_progress_func_t progress_func);
 
@@ -1022,8 +1080,7 @@ wimlib_add_image_multisource(WIMStruct *w,
 			     struct wimlib_capture_source *sources,
 			     size_t num_sources,
 			     const wimlib_tchar *name,
-			     const wimlib_tchar *config_str,
-			     size_t config_len,
+			     struct wimlib_capture_config *config,
 			     int add_image_flags,
 			     wimlib_progress_func_t progress_func);