X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=1256f689e4f5c1c01dda5ea56490736a68f6f5fd;hp=094622789c07fc264ead7f6c658536a7ece9b640;hb=b3d0fd77eb71d6e20eddfac6586c16418f46e1be;hpb=51df3b63c594a7e35446d2e2e19637e54240b0b2
diff --git a/include/wimlib.h b/include/wimlib.h
index 09462278..1256f689 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -11,7 +11,7 @@
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.8.3, a C
+ * This is the documentation for the library interface of wimlib 1.9.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
@@ -377,10 +377,10 @@
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 8
+#define WIMLIB_MINOR_VERSION 9
/** 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" {
@@ -856,13 +856,11 @@ union wimlib_progress_info {
uint64_t num_dirs_scanned;
/** The number of non-directories scanned so far, not counting
- * excluded/unsupported files. If a file has multiple names
- * (hard links), it is only counted one time. */
+ * excluded/unsupported files. */
uint64_t num_nondirs_scanned;
/** The number of bytes of file data detected so far, not
- * counting excluded/unsupported files. If a file has multiple
- * names (hard links), its data is counted only one time. */
+ * counting excluded/unsupported files. */
uint64_t num_bytes_scanned;
} scan;
@@ -1747,23 +1745,27 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
-/* Note: the WIMLIB_ADD_IMAGE_FLAG names are retained for source compatibility.
- * Use the WIMLIB_ADD_FLAG names in new code. */
-#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
-#define WIMLIB_ADD_IMAGE_FLAG_BOOT WIMLIB_ADD_FLAG_BOOT
-#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA WIMLIB_ADD_FLAG_UNIX_DATA
-#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS WIMLIB_ADD_FLAG_NO_ACLS
-#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS WIMLIB_ADD_FLAG_STRICT_ACLS
-#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE
-#define WIMLIB_ADD_IMAGE_FLAG_RPFIX WIMLIB_ADD_FLAG_RPFIX
-#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX WIMLIB_ADD_FLAG_NORPFIX
-#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \
- WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE
-#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG
-#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT WIMLIB_ADD_FLAG_WIMBOOT
+/**
+ * EXPERIMENTAL, since wimlib v1.9.0: create a temporary filesystem snapshot of
+ * the source directory and add the files from it. Currently, this option is
+ * only supported on Windows, where it uses the Volume Shadow Copy Service
+ * (VSS). Using this option, you can create a consistent backup of the system
+ * volume of a running Windows system without running into problems with locked
+ * files. For the VSS snapshot to be successfully created, your application
+ * must be run as an Administrator, and it cannot be run in WoW64 mode (i.e. if
+ * Windows is 64-bit, then your application must be 64-bit as well).
+ */
+#define WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000
+/**
+ * Since wimlib v1.9.0: permit the library to discard file paths after the
+ * initial scan. If the application won't use
+ * WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM archive,
+ * this flag can be used to allow the library to enable optimizations such as
+ * opening files by inode number rather than by path. Currently this only makes
+ * a difference on Windows.
+ */
+#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED 0x00010000
/** @} */
/** @addtogroup G_modifying_wims
@@ -1904,9 +1906,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* only allows the Administrator to create symbolic links. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
-/** Reserved for future use. */
-#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000
-
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the
* paths to extract as wildcard patterns ("globs") which may contain the
* wildcard characters @c ? and @c *. The @c ? character matches any
@@ -2245,12 +2244,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_WRITE_FLAG_SOLID 0x00001000
-/**
- * Deprecated: this is the old name for ::WIMLIB_WRITE_FLAG_SOLID, retained for
- * source compatibility.
- */
-#define WIMLIB_WRITE_FLAG_PACK_STREAMS WIMLIB_WRITE_FLAG_SOLID
-
/**
* Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM
* file. This is only needed in the unusual case that the library user needs to
@@ -2505,6 +2498,7 @@ enum wimlib_error_code {
WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86,
WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87,
WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88,
+ WIMLIB_ERR_SNAPSHOT_FAILURE = 89,
};
@@ -3133,19 +3127,8 @@ wimlib_get_error_string(enum wimlib_error_code code);
/**
* @ingroup G_wim_information
*
- * Get the description of the specified image.
- *
- * @param wim
- * Pointer to the ::WIMStruct to query. This need not represent a
- * standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- * The 1-based index of the image for which to query the description.
- *
- * @return
- * The description of the image, or @c NULL if there is no such image, or
- * @c NULL if the specified image has no description. The string may not
- * remain valid after later library calls, so the caller should duplicate
- * it if needed.
+ * Get the description of the specified image. Equivalent to
+ * wimlib_get_image_property(wim, image, "DESCRIPTION").
*/
extern const wimlib_tchar *
wimlib_get_image_description(const WIMStruct *wim, int image);
@@ -3153,18 +3136,10 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
/**
* @ingroup G_wim_information
*
- * Get the name of the specified image.
- *
- * @param wim
- * Pointer to the ::WIMStruct to query. This need not represent a
- * standalone WIM (e.g. it could represent part of a split WIM).
- * @param image
- * The 1-based index of the image for which to query the name.
- *
- * @return
- * The name of the image, or @c NULL if there is no such image, or an empty
- * string if the image is unnamed. The string may not remain valid after
- * later library calls, so the caller should duplicate it if needed.
+ * Get the name of the specified image. Equivalent to
+ * wimlib_get_image_property(wim, image, "NAME"), except that
+ * wimlib_get_image_name() will return an empty string if the image is unnamed
+ * whereas wimlib_get_image_property() may return @c NULL in that case.
*/
extern const wimlib_tchar *
wimlib_get_image_name(const WIMStruct *wim, int image);
@@ -3186,7 +3161,11 @@ wimlib_get_image_name(const WIMStruct *wim, int image);
* "TOTALBYTES". The name can contain forward slashes to indicate a nested
* XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD
* element nested within the VERSION element nested within the WINDOWS
- * element. The [ character is reserved for future use.
+ * element. Since wimlib v1.9.0, a bracketed number can be used to
+ * indicate one of several identically-named elements; for example,
+ * "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element
+ * nested within the "WINDOWS/LANGUAGES" element. Note that element names
+ * are case sensitive.
*
* @return
* The property's value as a ::wimlib_tchar string, or @c NULL if there is
@@ -3963,20 +3942,8 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path);
/**
* @ingroup G_modifying_wims
*
- * Change the description of a WIM image.
- *
- * @param wim
- * Pointer to the ::WIMStruct for the WIM.
- * @param image
- * The 1-based index of the image for which to change the description.
- * @param description
- * The new description to give the image. It may be @c NULL, which
- * indicates that the image is to be given no description.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image does not exist in @p wim.
+ * Change the description of a WIM image. Equivalent to
+ * wimlib_set_image_property(wim, image, "DESCRIPTION", description).
*/
extern int
wimlib_set_image_descripton(WIMStruct *wim, int image,
@@ -3986,20 +3953,8 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
* @ingroup G_modifying_wims
*
* Change what is stored in the \ element in the WIM XML document
- * (usually something like "Core" or "Ultimate")
- *
- * @param wim
- * Pointer to the ::WIMStruct for the WIM.
- * @param image
- * The 1-based index of the image for which to change the flags.
- * @param flags
- * The new \ element to give the image. It may be @c NULL, which
- * indicates that the image is to be given no \ element.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image does not exist in @p wim.
+ * (usually something like "Core" or "Ultimate"). Equivalent to
+ * wimlib_set_image_property(wim, image, "FLAGS", flags).
*/
extern int
wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
@@ -4007,23 +3962,8 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
/**
* @ingroup G_modifying_wims
*
- * Change the name of a WIM image.
- *
- * @param wim
- * Pointer to the ::WIMStruct for the WIM.
- * @param image
- * The 1-based index of the image for which to change the name.
- * @param name
- * New name to give the new image. If @c NULL or empty, the new image is
- * given no name. Otherwise, it must specify a name that does not already
- * exist in @p wim.
- *
- * @return 0 on success; a ::wimlib_error_code value on failure.
- *
- * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
- * The WIM already contains an image with the requested name.
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image does not exist in @p wim.
+ * Change the name of a WIM image. Equivalent to
+ * wimlib_set_image_property(wim, image, "NAME", name).
*/
extern int
wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
@@ -4043,16 +3983,27 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
* @param property_name
* The name of the image property in the same format documented for
* wimlib_get_image_property().
+ *
+ * Note: if creating a new element using a bracketed index such as
+ * "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified
+ * is one greater than the number of existing elements with that same name,
+ * excluding the index. That means that if you are adding a list of new
+ * elements, they must be added sequentially from the first index (1) to
+ * the last index (n).
* @param property_value
* If not NULL and not empty, the property is set to this value.
* Otherwise, the property is removed from the XML document.
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
+ * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
+ * The user requested to set the image name (the NAME property),
+ * but another image in the WIM already had the requested name.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not exist in @p wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p property_name has an unsupported format.
+ * @p property_name has an unsupported format, or @p property_name included
+ * a bracketed index that was too high.
*/
extern int
wimlib_set_image_property(WIMStruct *wim, int image,