X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=include%2Fwimlib.h;h=037f67d6327b1ec61ab49ccaa4acc321d26df466;hb=88bfb44de205f72acaefac0d509e1e4e604496f1;hp=e880182b664ea3696f2c88f635fadcf71212bbca;hpb=864db0e0929d60b33b8b0df35ccb68d43e7f8684;p=wimlib
diff --git a/include/wimlib.h b/include/wimlib.h
index e880182b..037f67d6 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.6.2, a C
+ * This is the documentation for the library interface of wimlib 1.6.3, 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
@@ -319,7 +319,7 @@
* created from one of these on-disk files initially only partially represents
* the full WIM and needs to, in effect, be logically combined with other
* ::WIMStruct's before performing certain operations, such as extracting files
- * with wimlib_extract_image() or wimlib_extract_files(). This is done by
+ * with wimlib_extract_image() or wimlib_extract_paths(). This is done by
* calling wimlib_reference_resource_files() or wimlib_reference_resources().
*
* wimlib_write() can create delta WIMs as well as standalone WIMs, but a
@@ -345,7 +345,7 @@
#define WIMLIB_MINOR_VERSION 6
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
#ifdef __cplusplus
extern "C" {
@@ -392,6 +392,15 @@ typedef char wimlib_tchar;
# define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
#endif
+/** Use this to specify the root directory of the WIM image. */
+#define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING
+
+/** Use this to test if the specified path refers to the root directory of the
+ * WIM image. */
+#define WIMLIB_IS_WIM_ROOT_PATH(path) \
+ ((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \
+ (path)[1] == 0)
+
#ifdef __GNUC__
# define _wimlib_deprecated __attribute__((deprecated))
#else
@@ -410,11 +419,11 @@ enum wimlib_compression_type {
/** The WIM does not include any compressed resources. */
WIMLIB_COMPRESSION_TYPE_NONE = 0,
- /** Compressed resources in the WIM use LZX compression. */
- WIMLIB_COMPRESSION_TYPE_LZX = 1,
-
/** Compressed resources in the WIM use XPRESS compression. */
- WIMLIB_COMPRESSION_TYPE_XPRESS = 2,
+ WIMLIB_COMPRESSION_TYPE_XPRESS = 1,
+
+ /** Compressed resources in the WIM use LZX compression. */
+ WIMLIB_COMPRESSION_TYPE_LZX = 2,
/** Compressed resources in the WIM use LZMS compression. Note: LZMS
* compression is only compatible with wimlib v1.6.0 and later and with
@@ -439,11 +448,9 @@ enum wimlib_progress_msg {
/** One or more file or directory trees within a WIM image is about to
* be extracted. @p info will point to ::wimlib_progress_info.extract.
- * This message is received once per extraction command for
- * wimlib_extract_files(), but only once for wimlib_extract_paths() and
- * wimlib_extract_pathlist(). (In the latter cases, wimlib combines all
- * paths into a single extraction operation for optimization purposes.)
- */
+ * This message is received only once per wimlib_extract_paths() and
+ * wimlib_extract_pathlist(), since wimlib combines all paths into a
+ * single extraction operation for optimization purposes. */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
/** The directory structure and other preliminary metadata is about to
@@ -567,6 +574,20 @@ enum wimlib_progress_msg {
* ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */
WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND,
+ /** A file in the WIM image is being replaced as a result of a
+ * ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified.
+ * @p info will point to ::wimlib_progress_info.replace. This is only
+ * received when ::WIMLIB_ADD_FLAG_VERBOSE is also specified in the add
+ * command. */
+ WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM,
+
+ /** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and
+ * a file is being extracted normally (not as a WIMBoot "pointer file")
+ * due to it matching a pattern in the [PrepopulateList] section of the
+ * configuration file \Windows\System32\WimBootCompress.ini in the WIM
+ * image. @info will point to ::wimlib_progress_info.wimboot_exclude.
+ */
+ WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE,
};
/** A pointer to this union is passed to the user-supplied
@@ -650,11 +671,10 @@ union wimlib_progress_info {
int32_t compression_type;
/** Number of split WIM parts from which streams are being
- * written (may be 0 if irrelevant). */
+ * written (may be 0 if irrelevant). */
uint32_t total_parts;
- /** Number of split WIM parts from which streams have been
- * written (may be 0 if irrelevant). */
+ /** This is currently broken and will always be 0. */
uint32_t completed_parts;
} write_streams;
@@ -700,10 +720,7 @@ union wimlib_progress_info {
union {
/** Target path in the WIM image. Only valid on
* messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
- * ::WIMLIB_PROGRESS_MSG_SCAN_END. If capturing a full
- * image, this will be the empty string; otherwise it
- * will name the place in the WIM image at which the
- * directory tree is being added. */
+ * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
const wimlib_tchar *wim_target_path;
/** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
@@ -774,12 +791,6 @@ union wimlib_progress_info {
* being extracted. This is because wimlib, by default, extracts the
* individual data streams in whichever order it determines to be the
* most efficient.
- *
- * An additional caveat: wimlib_extract_files() will perform a separate
- * logical extraction operation, with separate byte counts, for each
- * extraction command (file or directory tree). On the other hand,
- * wimlib_extract_paths() and wimlib_extract_pathlist() combine all the
- * paths to extract into a single logical extraction operation.
*/
struct wimlib_progress_info_extract {
/** Number of the image from which files are being extracted
@@ -827,11 +838,8 @@ union wimlib_progress_info {
* data stream, or a reparse data buffer. */
uint64_t num_streams;
- /** When extracting files using wimlib_extract_files(), this
- * will be the path within the WIM image to the file or
- * directory tree currently being extracted. Otherwise, this
- * will be the empty string. */
- const wimlib_tchar *extract_root_wim_source_path;
+ /** Reserved. */
+ const wimlib_tchar *reserved_2;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
@@ -925,6 +933,21 @@ union wimlib_progress_info {
* finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). */
const wimlib_tchar *part_name;
} split;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM */
+ struct wimlib_progress_info_replace {
+ /** Path to the file in the WIM image that is being replaced */
+ const wimlib_tchar *path_in_wim;
+ } replace;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE */
+ struct wimlib_progress_info_wimboot_exclude {
+ /** Path to the file in the WIM image */
+ const wimlib_tchar *path_in_wim;
+
+ /** Path to which the file is being extracted */
+ const wimlib_tchar *extraction_path;
+ } wimboot_exclude;
};
/** A user-supplied function that will be called periodically during certain WIM
@@ -950,9 +973,8 @@ struct wimlib_capture_source {
* filesystem to be included in the WIM image. */
wimlib_tchar *fs_source_path;
- /** Destination path in the WIM image. Leading and trailing slashes are
- * ignored. The empty string or @c NULL means the root directory of the
- * WIM image. */
+ /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to
+ * specify the root directory of the WIM image. */
wimlib_tchar *wim_target_path;
/** Reserved; set to 0. */
@@ -1263,8 +1285,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* ::WIMLIB_ADD_FLAG_UNIX_DATA. */
#define WIMLIB_ADD_FLAG_NTFS 0x00000001
-/** Follow symlinks; archive and dump the files they point to. Cannot be used
- * with ::WIMLIB_ADD_FLAG_NTFS. */
+/** Follow symlinks; archive and dump the files they point to. Currently only
+ * supported on UNIX-like systems. */
#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
/** Call the progress function with the message
@@ -1280,7 +1302,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* alternate data stream to each regular file, symbolic link, and directory to
* contain this information. Please note that this flag is for convenience
* only; Microsoft's implementation will not understand this special
- * information. This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */
+ * information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
@@ -1317,8 +1339,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200
/** Do not automatically exclude unsupported files or directories from capture;
- * e.g. encrypted directories in NTFS-3g capture mode, or device files and FIFOs
- * on UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
+ * e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on
+ * UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
* such a file is encountered. */
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
@@ -1337,9 +1359,12 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
/**
- * Capture image as WIMBoot compatible. In addition, use the capture
- * configuration file $SOURCE/Windows/System32/WimBootCompress.ini if it
- * exists, where $SOURCE is the directory being captured.
+ * Capture image as WIMBoot compatible. In addition, if no capture
+ * configuration file is explicitly specified use the capture configuration file
+ * $SOURCE/Windows/System32/WimBootCompress.ini if it exists, where
+ * $SOURCE is the directory being captured; or, if a capture
+ * configuration file is explicitly specified, use it and also place it at
+ * /Windows/System32/WimBootCompress.ini in the WIM image.
*
* Note: this will not by itself change the compression type. Before writing
* the WIM file, it's recommended to also do:
@@ -1354,6 +1379,15 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
+/**
+ * If the add command involves adding a non-directory file to a location at
+ * which there already exists a nondirectory file in the WIM image, issue
+ * ::WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. This only has an
+ * effect when updating an existing image with wimlib_update_image().
+ * This was the default behavior in wimlib v1.6.2 and earlier.
+ */
+#define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000
+
#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
@@ -1529,7 +1563,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
*/
#define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000
-/** Windows only: Extract files as "pointers" back to the WIM archive. */
+/** Windows only: Extract files as "pointers" back to the WIM archive. See the
+ * documentation for the --wimboot option of wimlib-imagex apply
+ * for more information. */
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
/** @} */
@@ -1789,12 +1825,11 @@ enum wimlib_update_op {
/** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */
struct wimlib_add_command {
- /** Filesystem path to the file or directory tree to
- * add. */
+ /** Filesystem path to the file or directory tree to add. */
wimlib_tchar *fs_source_path;
- /** Path, specified from the root of the WIM image, at
- * which to add the file or directory tree within the
- * WIM image. */
+
+ /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to
+ * specify the root directory of the WIM image. */
wimlib_tchar *wim_target_path;
/** Path to capture configuration file to use, or @c NULL for default.
@@ -1807,25 +1842,27 @@ struct wimlib_add_command {
/** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */
struct wimlib_delete_command {
- /** Path, specified from the root of the WIM image, for
- * the file or directory tree within the WIM image to be
- * deleted. */
+
+ /** Path, specified from the root of the WIM image, for the file or
+ * directory tree within the WIM image to be deleted. */
wimlib_tchar *wim_path;
- /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */
+
+ /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */
int delete_flags;
};
/** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */
struct wimlib_rename_command {
- /** Path, specified from the root of the WIM image, for
- * the source file or directory tree within the WIM
- * image. */
+
+ /** Path, specified from the root of the WIM image, for the source file
+ * or directory tree within the WIM image. */
wimlib_tchar *wim_source_path;
- /** Path, specified from the root of the WIM image, for
- * the destination file or directory tree within the WIM
- * image. */
+
+ /** Path, specified from the root of the WIM image, for the destination
+ * file or directory tree within the WIM image. */
wimlib_tchar *wim_target_path;
- /** Reserved; set to 0. */
+
+ /** Reserved; set to 0. */
int rename_flags;
};
@@ -1842,27 +1879,6 @@ struct wimlib_update_command {
};
};
-/** @} */
-/** @ingroup G_extracting_wims
- * @{ */
-
-/** DEPRECATED: Specification of extracting a file or directory tree from a WIM
- * image. This is only used for calls to wimlib_extract_files(), which has been
- * deprecated in favor of the easier-to-use wimlib_extract_paths(). */
-struct wimlib_extract_command {
- /** Path to file or directory tree within the WIM image to extract. It
- * must be provided as an absolute path from the root of the WIM image.
- * The path separators may be either forward slashes or backslashes. */
- wimlib_tchar *wim_source_path;
-
- /** Filesystem path to extract the file or directory tree to. */
- wimlib_tchar *fs_dest_path;
-
- /** Bitwise OR of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */
- int extract_flags;
-};
-
-
/** @} */
/** @ingroup G_general
* @{ */
@@ -2252,30 +2268,6 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
int export_flags,
wimlib_progress_func_t progress_func);
-/**
- * @ingroup G_extracting_wims
- *
- * Extract zero or more files or directory trees from a WIM image.
- *
- * As of wimlib v1.6.1, this function is deprecated in favor of
- * wimlib_extract_paths() because wimlib_extract_paths() is easier to use and
- * more efficient.
- *
- * Notes: wimlib_extract_files() does not support the
- * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS flag, and
- * ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE is always implied. The same
- * hardlink/symlink extraction mode must be set on all extraction commands. An
- * independent extraction operation (like a separate call to
- * wimlib_extract_paths()) is done for each extraction command. Otherwise, the
- * documentation for wimlib_extract_paths() applies.
- */
-extern int
-wimlib_extract_files(WIMStruct *wim,
- int image,
- const struct wimlib_extract_command *cmds,
- size_t num_cmds,
- int default_extract_flags,
- wimlib_progress_func_t progress_func) _wimlib_deprecated;
/**
* @ingroup G_extracting_wims
@@ -3487,11 +3479,6 @@ wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
*
* Similar to wimlib_set_output_compression_type(), but set the compression type
* for writing packed streams (solid blocks).
- *
- * Note: based on testing, WIMGAPI is seemingly only compatible with LZMS
- * compression in packed streams. Therefore the use of this function is not
- * recommended. Also, with large chunk sizes, LZMS gives the best compression
- * ratio among the alternatives anyway.
*/
extern int
wimlib_set_output_pack_compression_type(WIMStruct *wim, int ctype);
@@ -3777,9 +3764,9 @@ wimlib_unmount_image(const wimlib_tchar *dir,
* If non-NULL, a function that will be called periodically with the
* progress of the current operation.
*
- * @return 0 on success; nonzero on error. On failure, some but not all of the
- * update commands may have been executed. No individual update command will
- * have been partially executed. Possible error codes include:
+ * @return 0 on success; nonzero on error. On failure, all update commands will
+ * be rolled back, and no visible changes shall have been made to @p wim.
+ * Possible error codes include:
*
* @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
* The capture configuration structure specified for an add command was
@@ -4338,66 +4325,10 @@ extern void
wimlib_free_decompressor(struct wimlib_decompressor *decompressor);
-struct wimlib_lzx_params_old;
-struct wimlib_lzx_context_old;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_lzx_set_default_params(const struct wimlib_lzx_params_old *params)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_lzx_alloc_context(const struct wimlib_lzx_params_old *params,
- struct wimlib_lzx_context_old **ctx_pp)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern void
-wimlib_lzx_free_context(struct wimlib_lzx_context_old *ctx)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern unsigned
-wimlib_lzx_compress2(const void *udata, unsigned ulen, void *cdata,
- struct wimlib_lzx_context_old *ctx)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern unsigned
-wimlib_lzx_compress(const void *udata, unsigned ulen, void *cdata)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern unsigned
-wimlib_xpress_compress(const void *udata, unsigned ulen, void *cdata)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_lzx_decompress(const void *cdata, unsigned clen,
- void *udata, unsigned ulen)
- _wimlib_deprecated;
-
-/** Deprecated; do not use. */
-extern int
-wimlib_xpress_decompress(const void *cdata, unsigned clen,
- void *udata, unsigned ulen)
- _wimlib_deprecated;
-
-
/**
* @}
*/
-/** @ingroup G_wim_information
- *
- * Deprecated and will return ::WIMLIB_ERR_UNSUPPORTED. Use
- * wimlib_iterate_dir_tree() instead. */
-extern int
-wimlib_print_metadata(WIMStruct *wim, int image)
- _wimlib_deprecated;
-
#ifdef __cplusplus
}