X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=529de43765e4d079fa90a67300c1b29ed338fca5;hb=5b6eaafbaab217fc69946685862a09afa28b30cb;hp=d28fd3443ecc157538e8931147f83880836dbe7a;hpb=e040fe071bd22f58716b851696a1b0a0139877c0;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index d28fd344..529de437 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -9,29 +9,10 @@
* 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
*
- * This is the documentation for the library interface of wimlib 1.7.1, a C
+ * This is the documentation for the library interface of wimlib 1.7.2, 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
@@ -71,6 +52,19 @@
* source code of wimlib-imagex, 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
@@ -385,7 +379,7 @@
#define WIMLIB_MINOR_VERSION 7
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 2
#ifdef __cplusplus
extern "C" {
@@ -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 false by default. The
+ * progress function can set this to true 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.