X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=b3f0537e5428480ac85d22f27c700e22c683eafa;hp=d28fd3443ecc157538e8931147f83880836dbe7a;hb=bb1dafa9009afdacb0276e3ef00007e59a4a5111;hpb=e040fe071bd22f58716b851696a1b0a0139877c0

diff --git a/include/wimlib.h b/include/wimlib.h
index d28fd344..b3f0537e 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -9,25 +9,6 @@
  * in this header.
  */
 
-/*
- * Copyright (C) 2012, 2013, 2014 Eric Biggers
- *
- * This file is part of wimlib, a library for working with WIM files.
- *
- * wimlib is free software; you can redistribute it and/or modify it under the
- * terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 3 of the License, or (at your option)
- * any later version.
- *
- * wimlib is distributed in the hope that it will be useful, but WITHOUT ANY
- * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- * A PARTICULAR PURPOSE. See the GNU General Public License for more
- * details.
- *
- * You should have received a copy of the GNU General Public License
- * along with wimlib; if not, see http://www.gnu.org/licenses/.
- */
-
 /**
  * @mainpage
  *
@@ -71,6 +52,19 @@
  * source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
  * capabilities of wimlib.
  *
+ * @section backwards_compatibility Backwards Compatibility
+ *
+ * New releases of wimlib are intended to be API/ABI compatible with old
+ * releases, except when the libtool "age" is reset.  This most recently
+ * occurred for the v1.4.0 (libwim7), v1.5.0 (libwim9), and v1.7.0 (libwim15)
+ * releases.  However, the library is becoming increasingly stable, and the goal
+ * is to maintain the current API/ABI for as long as possible unless there is a
+ * strong reason not to.  Even for the v1.7.0 release (libwim15), the changes
+ * were fairly limited.
+ *
+ * As with any other library, applications should not rely on internal
+ * implementation details that may be subject to change.
+ *
  * @section sec_basic_wim_handling_concepts Basic WIM handling concepts
  *
  * wimlib wraps up a WIM file in an opaque ::WIMStruct structure.   There are
@@ -700,6 +694,20 @@ enum wimlib_progress_msg {
 	/** wimlib_verify_wim() is verifying stream integrity.  @p info will
 	 * point to ::wimlib_progress_info.verify_streams.  */
 	WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29,
+
+	/**
+	 * The progress function is being asked whether a file should be
+	 * excluded from capture or not.  @p info will point to
+	 * ::wimlib_progress_info.test_file_exclusion.  This is a bidirectional
+	 * message that allows the progress function to set a flag if the file
+	 * should be excluded.
+	 *
+	 * This message is only received if the flag
+	 * ::WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION is used.  This method for file
+	 * exclusions is independent of the "capture configuration file"
+	 * mechanism.
+	 */
+	WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION = 30,
 };
 
 /** Valid return values from user-provided progress functions
@@ -1170,6 +1178,32 @@ union wimlib_progress_info {
 		uint64_t completed_streams;
 		uint64_t completed_bytes;
 	} verify_streams;
+
+	/** Valid on messages ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION.  */
+	struct wimlib_progress_info_test_file_exclusion {
+
+		/**
+		 * Path to the file for which exclusion is being tested.
+		 *
+		 * UNIX capture mode:  The path will be a standard relative or
+		 * absolute UNIX filesystem path.
+		 *
+		 * NTFS-3g capture mode:  The path will be given relative to the
+		 * root of the NTFS volume, with a leading slash.
+		 *
+		 * Windows capture mode:  The path will be a Win32 namespace
+		 * path to the file.
+		 */
+		const wimlib_tchar *path;
+
+		/**
+		 * Indicates whether the file or directory will be excluded from
+		 * capture or not.  This will be <tt>false</tt> by default.  The
+		 * progress function can set this to <tt>true</tt> if it decides
+		 * that the file needs to be excluded.
+		 */
+		bool will_exclude;
+	} test_file_exclusion;
 };
 
 /**
@@ -1682,6 +1716,15 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_ADD_FLAG_NO_REPLACE		0x00002000
 
+/**
+ * Send ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress
+ * function.
+ *
+ * Note: This method for file exclusions is independent from the capture
+ * configuration file mechanism.
+ */
+#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
+
 #define WIMLIB_ADD_IMAGE_FLAG_NTFS		WIMLIB_ADD_FLAG_NTFS
 #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE	WIMLIB_ADD_FLAG_DEREFERENCE
 #define WIMLIB_ADD_IMAGE_FLAG_VERBOSE		WIMLIB_ADD_FLAG_VERBOSE
@@ -2385,6 +2428,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY              = 79,
 	WIMLIB_ERR_NOT_A_MOUNTPOINT                   = 80,
 	WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT           = 81,
+	WIMLIB_ERR_FVE_LOCKED_VOLUME		      = 82,
 };
 
 
@@ -4290,6 +4334,9 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir,
  * be rolled back, and no visible changes shall have been made to @p wim.
  * Possible error codes include:
  *
+ * @retval ::WIMLIB_ERR_FVE_LOCKED_VOLUME
+ *	Windows-only: One of the "add" commands attempted to add files from an
+ *	encrypted BitLocker volume that hasn't yet been unlocked.
  * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
  *	The capture configuration structure specified for an add command was
  *	invalid.