X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=fd55ebf8c23f0b70c8b641dc9923a3599fa7c52b;hp=372bb760af96f9ad73beb09b8e60a8bffca2f680;hb=d1bfffba93b1d841e243c923e739e0e39ee692f2;hpb=62e209e9aeaa36ba9e3c2a174428805b7264e0e7
diff --git a/include/wimlib.h b/include/wimlib.h
index 372bb760..fd55ebf8 100644
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -10,7 +10,7 @@
*/
/*
- * Copyright (C) 2012, 2013 Eric Biggers
+ * Copyright (C) 2012, 2013, 2014 Eric Biggers
*
* This file is part of wimlib, a library for working with WIM files.
*
@@ -33,7 +33,7 @@
*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.6.0, a C
+ * This is the documentation for the library interface of wimlib 1.6.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
@@ -251,27 +251,22 @@
*
* @brief Extract files, directories, and images from a WIM.
*
- * wimlib_extract_image() extracts, or "applies", an image from a WIM
- * (represented, as usual, by a ::WIMStruct). This normally extracts the image
- * to a directory, but when supported by the build of the library there is also
- * a special NTFS volume extraction mode (entered when
- * ::WIMLIB_EXTRACT_FLAG_NTFS is specified) that allows extracting a WIM image
- * directly to an unmounted NTFS volume. Various other flags allow further
- * customization of image extraction.
+ * wimlib_extract_image() extracts, or "applies", an image from a WIM,
+ * represented by a ::WIMStruct. This normally extracts the image to a
+ * directory, but when supported by the build of the library there is also a
+ * special NTFS volume extraction mode (entered when ::WIMLIB_EXTRACT_FLAG_NTFS
+ * is specified) that allows extracting a WIM image directly to an unmounted
+ * NTFS volume. Various other flags allow further customization of image
+ * extraction.
*
- * Another function, wimlib_extract_files(), is also provided. It can extract
- * certain files or directories from a WIM image, instead of a full image.
+ * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a list
+ * of (possibly wildcard) paths from a WIM image.
*
- * wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a set
- * of paths from a WIM image in a manner that may be easier to use than
- * wimlib_extract_files(), and also allow wildcard patterns.
+ * wimlib_extract_image_from_pipe() extracts an image from a pipable WIM sent
+ * over a pipe; see @ref subsec_pipable_wims.
*
- * wimlib_extract_image_from_pipe() allows an image to be extracted from a
- * pipable WIM sent over a pipe; see @ref subsec_pipable_wims.
- *
- * Note that some details of how image extraction/application works are
- * documented more fully in the manual pages for wimlib-imagex apply and
- * wimlib-imagex extract.
+ * Some details of how WIM extraction works are documented more fully in the
+ * manual pages for wimlib-imagex apply and wimlib-imagex extract.
*/
/** @defgroup G_mounting_wim_images Mounting WIM images
@@ -350,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 0
+#define WIMLIB_PATCH_VERSION 2
#ifdef __cplusplus
extern "C" {
@@ -437,91 +432,115 @@ enum wimlib_compression_type {
enum wimlib_progress_msg {
/** A WIM image is about to be extracted. @p info will point to
- * ::wimlib_progress_info.extract. */
+ * ::wimlib_progress_info.extract. This message is received once per
+ * image for calls to wimlib_extract_image() and
+ * wimlib_extract_image_from_pipe(). */
WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0,
- /** One or more file or directory trees within a WIM image (not the full
- * image) is about to be extracted. @p info will point to
- * ::wimlib_progress_info.extract. */
+ /** 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.)
+ */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
- /** The directory structure of the WIM image is about to be extracted.
- * @p info will point to ::wimlib_progress_info.extract. */
+ /** The directory structure and other preliminary metadata is about to
+ * be extracted. @p info will point to ::wimlib_progress_info.extract.
+ * This message is received once after either
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN or
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */
WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN,
- /** The directory structure of the WIM image has been successfully
- * extracted. @p info will point to ::wimlib_progress_info.extract. */
+ /** Confirms that the directory structure and other preliminary metadata
+ * has been successfully extracted. @p info will point to
+ * ::wimlib_progress_info.extract. This message is paired with a
+ * preceding ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN message.
+ */
WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END,
/** File data is currently being extracted. @p info will point to
- * ::wimlib_progress_info.extract. */
+ * ::wimlib_progress_info.extract. This is the main message to track
+ * the progress of an extraction operation. */
WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
/** Starting to read a new part of a split pipable WIM over the pipe.
* @p info will point to ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN,
- /** All the WIM files and directories have been extracted, and
- * timestamps are about to be applied. @p info will point to
- * ::wimlib_progress_info.extract. */
+ /** All data for WIM files and directories have been extracted, and
+ * final metadata such as timestamps is about to be extracted. @p info
+ * will point to ::wimlib_progress_info.extract. This message is
+ * received once before ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END or
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END. */
WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS,
- /** A WIM image has been successfully extracted. @p info will point to
- * ::wimlib_progress_info.extract. */
+ /** Confirms that the image has been successfully extracted. @p info
+ * will point to ::wimlib_progress_info.extract. This is paired with
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN. */
WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END,
- /** A file or directory tree within a WIM image (not the full image) has
- * been successfully extracted. @p info will point to
- * ::wimlib_progress_info.extract. */
+ /** Confirms that the files or directory trees have been successfully
+ * extracted. @p info will point to ::wimlib_progress_info.extract.
+ * This is paired with ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END,
- /** The directory or NTFS volume is about to be scanned to build a tree
- * of WIM dentries in-memory. @p info will point to
- * ::wimlib_progress_info.scan. */
+ /** The directory or NTFS volume is about to be scanned for metadata.
+ * @p info will point to ::wimlib_progress_info.scan. This message is
+ * received once per call to wimlib_add_image(), or once per capture
+ * source passed to wimlib_add_image_multisource(), or once per add
+ * command passed to wimlib_update_image(). */
WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
- /** A directory or file is being scanned. @p info will point to
+ /** A directory or file has been scanned. @p info will point to
* ::wimlib_progress_info.scan, and its @p cur_path member will be
- * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE
- * is passed to wimlib_add_image(). */
+ * valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE has
+ * been specified. */
WIMLIB_PROGRESS_MSG_SCAN_DENTRY,
- /** The directory or NTFS volume has been successfully scanned, and a
- * tree of WIM dentries has been built in-memory. @p info will point to
- * ::wimlib_progress_info.scan. */
+ /** Confirms that the directory or NTFS volume has been successfully
+ * scanned. @p info will point to ::wimlib_progress_info.scan. This is
+ * paired with a previous ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN message,
+ * possibly with many intervening ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY
+ * messages. */
WIMLIB_PROGRESS_MSG_SCAN_END,
/** File resources ("streams") are currently being written to the WIM.
- * @p info will point to ::wimlib_progress_info.write_streams. */
+ * @p info will point to ::wimlib_progress_info.write_streams. This
+ * message may be received many times while the WIM file is being
+ * written or appended to with wimlib_write(), wimlib_overwrite(), or
+ * wimlib_write_to_fd(). */
WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
- /**
- * The metadata resource for each image is about to be written to the
- * WIM. @p info will not be valid. */
+ /** Per-image metadata is about to be written to the WIM file. @p info
+ * will not be valid. */
WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
- /**
- * The metadata resource for each image has successfully been writen to
- * the WIM. @p info will not be valid. */
+ /** Confirms that per-image metadata has been successfully been written
+ * to the WIM file. @p info will not be valid. This message is paired
+ * with a preceding ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message.
+ */
WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
- /**
- * The temporary file has successfully been renamed to the original WIM
- * file. Only happens when wimlib_overwrite() is called and the
- * overwrite is not done in-place.
- * @p info will point to ::wimlib_progress_info.rename. */
+ /** wimlib_overwrite() has successfully renamed the temporary file to
+ * the original WIM file, thereby committing the update. @p info will
+ * point to ::wimlib_progress_info.rename. Note: this message is not
+ * received if wimlib_overwrite() chose to append to the WIM file
+ * in-place. */
WIMLIB_PROGRESS_MSG_RENAME,
- /** The contents of the WIM are being checked against the integrity
- * table. Only happens when wimlib_open_wim() is called with the
- * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. @p info will point to
- * ::wimlib_progress_info.integrity. */
+ /** The contents of the WIM file are being checked against the integrity
+ * table. @p info will point to ::wimlib_progress_info.integrity. This
+ * message is only received (and may be received many times) when
+ * wimlib_open_wim() is called with the
+ * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. */
WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY,
/** An integrity table is being calculated for the WIM being written.
- * Only happens when wimlib_write() or wimlib_overwrite() is called with
- * the ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY flag. @p info will point to
- * ::wimlib_progress_info.integrity. */
+ * @p info will point to ::wimlib_progress_info.integrity. This message
+ * is only received (and may be received many times) when a WIM file is
+ * being written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
WIMLIB_PROGRESS_MSG_CALC_INTEGRITY,
/** Reserved. */
@@ -529,23 +548,23 @@ enum wimlib_progress_msg {
/** A wimlib_split() operation is in progress, and a new split part is
* about to be started. @p info will point to
- * ::wimlib_progress_info.split. */
+ * ::wimlib_progress_info.split. */
WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART,
/** A wimlib_split() operation is in progress, and a split part has been
- * finished. @p info will point to ::wimlib_progress_info.split. */
+ * finished. @p info will point to ::wimlib_progress_info.split. */
WIMLIB_PROGRESS_MSG_SPLIT_END_PART,
- /**
- * A WIM update command is just about to be executed; @p info will point
- * to ::wimlib_progress_info.update.
- */
+ /** A WIM update command is just about to be executed. @p info will
+ * point to ::wimlib_progress_info.update. This message is received
+ * once per update command when wimlib_update_image() is called with the
+ * flag ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */
WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND,
- /**
- * A WIM update command has just been executed; @p info will point to
- * ::wimlib_progress_info.update.
- */
+ /** A WIM update command has just been executed. @p info will point to
+ * ::wimlib_progress_info.update. This message is received once per
+ * update command when wimlib_update_image() is called with the flag
+ * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */
WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND,
};
@@ -688,8 +707,8 @@ union wimlib_progress_info {
const wimlib_tchar *wim_target_path;
/** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
- * of ::WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is the
- * target of the absolute symbolic link or junction
+ * of @p WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is
+ * the target of the absolute symbolic link or junction
* point. */
const wimlib_tchar *symlink_target;
};
@@ -754,14 +773,21 @@ union wimlib_progress_info {
* general, actually provide information about which "file" is currently
* being extracted. This is because wimlib, by default, extracts the
* individual data streams in whichever order it determines to be the
- * most efficient. */
+ * 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
* (1-based). */
- int image;
+ uint32_t image;
/** Extraction flags being used. */
- int extract_flags;
+ uint32_t extract_flags;
/** Full path to the WIM file from which files are being
* extracted, or @c NULL if the WIMStruct has no associated
@@ -809,11 +835,11 @@ union wimlib_progress_info {
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
- unsigned part_number;
+ uint32_t part_number;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
- unsigned total_parts;
+ uint32_t total_parts;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
@@ -1285,7 +1311,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* scanned. */
#define WIMLIB_ADD_FLAG_VERBOSE 0x00000004
-/** Mark the image being added as the bootable image of the WIM. */
+/** Mark the image being added as the bootable image of the WIM. Not valid for
+ * wimlib_update_image(). */
#define WIMLIB_ADD_FLAG_BOOT 0x00000008
/** Store the UNIX owner, group, and mode. This is done by adding a special
@@ -1414,11 +1441,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001
/** When identical files are extracted from the WIM, always hard link them
- * together. */
+ * together. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_SYMLINK.
+ */
#define WIMLIB_EXTRACT_FLAG_HARDLINK 0x00000002
/** When identical files are extracted from the WIM, always symlink them
- * together. */
+ * together. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_HARDLINK.
+ */
#define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004
/** This flag no longer does anything but is reserved for future use. */
@@ -1434,31 +1463,35 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* specified. */
#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
-/** Do not extract security descriptors. */
+/** Do not extract security descriptors. This flag cannot be combined with
+ * ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS. */
#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. On Windows, 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. */
+ * behavior without this flag when wimlib does not have permission to set the
+ * correct security descriptor is to fall back to setting the security
+ * descriptor with the SACL omitted, then with the DACL omitted, then with the
+ * owner omitted, then not at all. This flag cannot be combined with
+ * ::WIMLIB_EXTRACT_FLAG_NO_ACLS. */
#define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080
/** This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX. This forces
* reparse-point fixups on, so absolute symbolic links or junction points will
- * be fixed to be absolute relative to the actual extraction root. Reparse
- * point fixups are done by default if WIM_HDR_FLAG_RP_FIX is set in the WIM
- * header. This flag may only be specified when extracting a full image (not a
- * file or directory tree within one). */
+ * be fixed to be absolute relative to the actual extraction root. Reparse-
+ * point fixups are done by default for wimlib_extract_image() and
+ * wimlib_extract_image_from_pipe() if WIM_HDR_FLAG_RP_FIX is set in the WIM
+ * header. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX. */
#define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100
/** Force reparse-point fixups on extraction off, regardless of the state of the
- * WIM_HDR_FLAG_RP_FIX flag in the WIM header. */
+ * WIM_HDR_FLAG_RP_FIX flag in the WIM header. This flag cannot be combined
+ * with ::WIMLIB_EXTRACT_FLAG_RPFIX. */
#define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200
-/** Extract the specified file to standard output. This is only valid in an
- * extraction command that specifies the extraction of a regular file in the WIM
- * image. */
+/** Extract the paths, each of which must name a regular file, to standard
+ * output. Not valid for wimlib_extract_image() and
+ * wimlib_extract_image_from_pipe(). */
#define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400
/** Instead of ignoring files and directories with names that cannot be
@@ -1497,16 +1530,14 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
#define WIMLIB_EXTRACT_FLAG_FILE_ORDER 0x00020000
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the
- * paths in the WIM as "glob" patterns which may contain the wildcard characters
- * '?' and '*'. The '?' character matches any character except a path
- * separator, whereas the '*' character matches zero or more non-path-separator
- * characters. Each glob pattern may match zero or more paths in the WIM file.
- * If a glob pattern ends in a path separator, it will only match directories
- * (including reparse points with FILE_ATTRIBUTE_DIRECTORY set). By default, if
- * a glob pattern does not match any files, a warning but not an error will be
- * issued, even if the glob pattern did not actually contain wildcard
- * characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error instead.
- */
+ * paths to extract as wildcard patterns ("globs") which may contain the
+ * wildcard characters @c ? and @c *. The @c ? character matches any
+ * non-path-separator character, whereas the @c * character matches zero or more
+ * non-path-separator characters. Consequently, each glob may match zero or
+ * more actual paths in the WIM image. By default, if a glob does not match any
+ * files, a warning but not an error will be issued, even if the glob did not
+ * actually contain wildcard characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB
+ * to get an error instead. */
#define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000
/** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error
@@ -1514,6 +1545,15 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
* one of the provided globs did not match a file. */
#define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000
+/** Do not extract Windows file attributes such as readonly, hidden, etc. */
+#define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000
+
+/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not
+ * preserve the directory structure of the archive when extracting --- that is,
+ * place each extracted file or directory tree directly in the target directory.
+ */
+#define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000
+
/** @} */
/** @ingroup G_mounting_wim_images
* @{ */
@@ -1588,6 +1628,11 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */
#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010
+/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted
+ * image, causes the modified image to be committed as a new, unnamed image
+ * appended to the archive. The original image will be unmodified. */
+#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020
+
/** @} */
/** @ingroup G_modifying_wims
* @{ */
@@ -1734,16 +1779,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
/** @ingroup G_nonstandalone_wims
* @{ */
-/** wimlib_reference_resource_files() only: Enable shell-style filename
- * globbing. */
+/** For wimlib_reference_resource_files(), enable shell-style filename globbing.
+ * Ignored by wimlib_reference_resources(). */
#define WIMLIB_REF_FLAG_GLOB_ENABLE 0x00000001
-/** wimlib_reference_resource_files() only: Issue an error
+/** For wimlib_reference_resource_files(), issue an error
* (::WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files. The
* default behavior without this flag is to issue no error at that point, but
* then attempt to open the glob as a literal path, which of course will fail
* anyway if no file exists at that path. No effect if
- * ::WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. */
+ * ::WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. Ignored by
+ * wimlib_reference_resources(). */
#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002
/** @} */
@@ -1824,8 +1870,9 @@ struct wimlib_update_command {
/** @ingroup G_extracting_wims
* @{ */
-/** Specification of a file or directory tree to extract from a WIM image. Used
- * in calls to wimlib_extract_files(). */
+/** 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.
@@ -1835,7 +1882,7 @@ struct wimlib_extract_command {
/** 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. */
+ /** Bitwise OR of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */
int extract_flags;
};
@@ -1935,6 +1982,8 @@ enum wimlib_error_code {
/** Used to specify all images in the WIM. */
#define WIMLIB_ALL_IMAGES (-1)
+/** @} */
+
/**
* @ingroup G_modifying_wims
*
@@ -2069,9 +2118,8 @@ wimlib_add_image_multisource(WIMStruct *wim,
* images. No on-disk file is created until wimlib_write() is called.
*
* @param ctype
- * The type of compression to be used in the new WIM file. Must be
- * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX, or
- * ::WIMLIB_COMPRESSION_TYPE_XPRESS.
+ * The type of compression to be used in the new WIM file, as one of the
+ * ::wimlib_compression_type constants.
* @param wim_ret
* On success, a pointer to an opaque ::WIMStruct for the new WIM file is
* written to the memory location pointed to by this paramater. The
@@ -2079,8 +2127,7 @@ wimlib_add_image_multisource(WIMStruct *wim,
* it.
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
- * @p ctype was not ::WIMLIB_COMPRESSION_TYPE_NONE,
- * ::WIMLIB_COMPRESSION_TYPE_LZX, or ::WIMLIB_COMPRESSION_TYPE_XPRESS.
+ * @p ctype was not a supported compression type.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate needed memory.
*/
@@ -2228,59 +2275,17 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
*
* Extract zero or more files or directory trees from a WIM image.
*
- * This generalizes the single-image extraction functionality of
- * wimlib_extract_image() to allow extracting only the specified subsets of the
- * image.
- *
- * @param wim
- * The WIM from which to extract the files, specified as a pointer to the
- * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a
- * split WIM. In the case of a WIM file that is not standalone, this
- * ::WIMStruct must have had any needed external resources previously
- * referenced using wimlib_reference_resources() or
- * wimlib_reference_resource_files().
- *
- * @param image
- * The 1-based number of the image in @p wim from which the files or
- * directory trees are to be extracted. It cannot be ::WIMLIB_ALL_IMAGES.
- *
- * @param cmds
- * An array of ::wimlib_extract_command structures that specifies the
- * extractions to perform.
- *
- * @param num_cmds
- * Number of commands in the @p cmds array.
- *
- * @param default_extract_flags
- * Default extraction flags; the behavior shall be as if these flags had
- * been specified in the ::wimlib_extract_command.extract_flags member in
- * each extraction command, in combination with any flags already present.
- *
- * @param progress_func
- * If non-NULL, a function that will be called periodically with the
- * progress of the current operation.
- *
- * @return 0 on success; nonzero on error. The possible error codes include
- * most of those documented as returned by wimlib_extract_image() as well as the
- * following additional error codes:
- *
- * @retval ::WIMLIB_ERR_INVALID_IMAGE
- * @p image was ::WIMLIB_ALL_IMAGES (or was not otherwise a valid image in
- * the WIM file).
- * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST
- * The ::wimlib_extract_command.wim_source_path member in one of the
- * extract commands did not exist in the WIM.
- * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE
- * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified for an extraction command
- * in which ::wimlib_extract_command.wim_source_path existed but was not a
- * regular file or directory.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK was
- * specified for some commands but not all; or
- * ::wimlib_extract_command.fs_dest_path was @c NULL or the empty string
- * for one or more commands; or ::WIMLIB_EXTRACT_FLAG_RPFIX was specified
- * for a command in which ::wimlib_extract_command.wim_source_path did not
- * specify the root directory of the 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,
@@ -2288,13 +2293,13 @@ wimlib_extract_files(WIMStruct *wim,
const struct wimlib_extract_command *cmds,
size_t num_cmds,
int default_extract_flags,
- wimlib_progress_func_t progress_func);
+ wimlib_progress_func_t progress_func) _wimlib_deprecated;
/**
* @ingroup G_extracting_wims
*
- * Extracts an image, or all images, from a WIM to a directory or directly to a
- * NTFS volume image.
+ * Extracts an image, or all images, from a WIM to a directory or NTFS volume
+ * image.
*
* The exact behavior of how wimlib extracts files from a WIM image is
* controllable by the @p extract_flags parameter, but there also are
@@ -2303,12 +2308,6 @@ wimlib_extract_files(WIMStruct *wim,
* special "NTFS volume extraction mode" entered by providing
* ::WIMLIB_EXTRACT_FLAG_NTFS.
*
- * All extracted data is SHA1-summed, and ::WIMLIB_ERR_INVALID_RESOURCE_HASH is
- * returned if any resulting SHA1 message digests do not match the values
- * provided in the WIM file. Therefore, if this function is successful, you can
- * be fairly sure that any compressed data in the WIM was uncompressed
- * correctly.
- *
* @param wim
* The WIM from which to extract the image(s), specified as a pointer to
* the ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1
@@ -2317,51 +2316,55 @@ wimlib_extract_files(WIMStruct *wim,
* referenced using wimlib_reference_resources() or
* wimlib_reference_resource_files().
* @param image
- * The image to extract. Can be the number of an image, or ::WIMLIB_ALL_IMAGES
- * to specify that all images are to be extracted. ::WIMLIB_ALL_IMAGES cannot
- * be used if ::WIMLIB_EXTRACT_FLAG_NTFS is specified in @p extract_flags.
+ * The image to extract, specified as either the 1-based index of a single
+ * image to extract, or ::WIMLIB_ALL_IMAGES to specify that all images are
+ * to be extracted. ::WIMLIB_ALL_IMAGES cannot be used if
+ * ::WIMLIB_EXTRACT_FLAG_NTFS is specified in @p extract_flags.
* @param target
- * Directory to extract the WIM image(s) to (created if it does not already
- * exist); or, with ::WIMLIB_EXTRACT_FLAG_NTFS in @p extract_flags, the
- * path to the unmounted NTFS volume to extract the image to.
+ * Directory to extract the WIM image(s) to; or, with
+ * ::WIMLIB_EXTRACT_FLAG_NTFS specified in @p extract_flags, the path to
+ * the unmounted NTFS volume to which to extract the image.
* @param extract_flags
- * Bitwise OR of the flags prefixed with WIMLIB_EXTRACT_FLAG.
+ * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG.
* @param progress_func
- * If non-NULL, a function that will be called periodically with the
- * progress of the current operation.
+ * If non-NULL, a function that will be called periodically with the
+ * progress of the current operation. The main message to look for is
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS; however, there are others as
+ * well.
*
* @return 0 on success; nonzero on error.
* @retval ::WIMLIB_ERR_DECOMPRESSION
- * Failed to decompress a resource to be extracted.
+ * Failed to decompress data contained in the WIM.
+ * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE
+ * The metadata for one of the images to extract was invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * Both ::WIMLIB_EXTRACT_FLAG_HARDLINK and ::WIMLIB_EXTRACT_FLAG_SYMLINK
- * were specified in @p extract_flags; or both
- * ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS and ::WIMLIB_EXTRACT_FLAG_NO_ACLS were
- * specified in @p extract_flags; or both ::WIMLIB_EXTRACT_FLAG_RPFIX and
- * ::WIMLIB_EXTRACT_FLAG_NORPFIX were specified in @p extract_flags; or
- * ::WIMLIB_EXTRACT_FLAG_RESUME was specified in @p extract_flags; or if
- * ::WIMLIB_EXTRACT_FLAG_NTFS was specified in @p extract_flags and
- * @p image was ::WIMLIB_ALL_IMAGES.
+ * The extraction flags were invalid; more details may be found in the
+ * documentation for the specific extraction flags that were specified. Or
+ * @p target was @c NULL or the empty string, or @p wim was @c NULL.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
- * The SHA1 message digest of an extracted stream did not match the SHA1
- * message digest given in the WIM file.
+ * The SHA1 message digest of an extracted stream did not match the SHA1
+ * message digest given in the WIM.
* @retval ::WIMLIB_ERR_LINK
- * Failed to create a symbolic link or a hard link.
+ * Failed to create a symbolic link or a hard link.
+ * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND
+ * The metadata resource for one of the images to extract was not found.
+ * This can happen if @p wim represents a non-first part of a split WIM.
* @retval ::WIMLIB_ERR_MKDIR
- * Failed create a directory.
+ * Failed create a directory.
* @retval ::WIMLIB_ERR_NOMEM
- * Failed to allocate needed memory.
+ * Failed to allocate needed memory.
* @retval ::WIMLIB_ERR_OPEN
- * Could not create a file, or failed to open an already-extracted file.
+ * Could not create a file, or failed to open an already-extracted file.
* @retval ::WIMLIB_ERR_READ
- * Failed to read data from the WIM file associated with @p wim.
+ * Failed to read data from the WIM.
* @retval ::WIMLIB_ERR_READLINK
* Failed to determine the target of a symbolic link in the WIM.
* @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED
* Failed to fix the target of an absolute symbolic link (e.g. if the
- * target would have exceeded the maximum allowed length). (Only if
- * reparse data was supported by the extraction mode and
- * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS was specified in @p extract_flags.)
+ * target would have exceeded the maximum allowed length). (Only if
+ * reparse data was supported by the extraction mode and
+ * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS was specified in @p
+ * extract_flags.)
* @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
* One of the files or directories that needed to be extracted referenced a
* stream not present in the WIM's lookup table (or in any of the lookup
@@ -2382,8 +2385,7 @@ wimlib_extract_files(WIMStruct *wim,
* Failed to set timestamps on a file (only if
* ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS was specified in @p extract_flags).
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
- * Unexpected end-of-file occurred when reading data from the WIM file
- * associated with @p wim.
+ * Unexpected end-of-file occurred when reading data from the WIM.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* A requested extraction flag, or the data or metadata that must be
* extracted to support it, is unsupported in the build and configuration
@@ -2395,21 +2397,13 @@ wimlib_extract_files(WIMStruct *wim,
* ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS, ::WIMLIB_EXTRACT_FLAG_SYMLINK,
* and ::WIMLIB_EXTRACT_FLAG_HARDLINK. For example, if
* ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES is specified in @p
- * extract_flags,
- * ::WIMLIB_ERR_UNSUPPORTED will be returned if the WIM image contains one
- * or more files with short names, but extracting short names is not
- * supported --- on Windows, this occurs if the target volume does not
- * support short names, while on non-Windows, this occurs if
+ * extract_flags, ::WIMLIB_ERR_UNSUPPORTED will be returned if the WIM
+ * image contains one or more files with short names, but extracting short
+ * names is not supported --- on Windows, this occurs if the target volume
+ * does not support short names, while on non-Windows, this occurs if
* ::WIMLIB_EXTRACT_FLAG_NTFS was not specified in @p extract_flags.
* @retval ::WIMLIB_ERR_WRITE
* Failed to write data to a file being extracted.
- *
- * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
- * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
- * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or
- * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for
- * different reasons) to read the metadata resource for an image that needed to
- * be extracted.
*/
extern int
wimlib_extract_image(WIMStruct *wim, int image,
@@ -2420,8 +2414,8 @@ wimlib_extract_image(WIMStruct *wim, int image,
/**
* @ingroup G_extracting_wims
*
- * Since wimlib v1.5.0: Extract one or more images from a pipe on which a
- * pipable WIM is being sent.
+ * Since wimlib v1.5.0: Extract one image from a pipe on which a pipable WIM is
+ * being sent.
*
* See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information
* about pipable WIMs.
@@ -2446,17 +2440,16 @@ wimlib_extract_image(WIMStruct *wim, int image,
* Same as the corresponding parameter to wimlib_extract_image().
* @param extract_flags
* Same as the corresponding parameter to wimlib_extract_image(), except
- * for the following exceptions: ::WIMLIB_EXTRACT_FLAG_SEQUENTIAL is
- * always implied, since data is always read from @p pipe_fd sequentially
- * in this mode; also, ::WIMLIB_EXTRACT_FLAG_TO_STDOUT is invalid and will
+ * that ::WIMLIB_EXTRACT_FLAG_FILE_ORDER cannot be specified and will
* result in ::WIMLIB_ERR_INVALID_PARAM being returned.
* @param progress_func
* Same as the corresponding parameter to wimlib_extract_image(), except
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN messages will also be
- * received.
+ * received by the progress function.
*
* @return 0 on success; nonzero on error. The possible error codes include
- * those returned by wimlib_extract_image() as well as the following:
+ * those returned by wimlib_extract_image() and wimlib_open_wim() as well as the
+ * following:
*
* @retval ::WIMLIB_ERR_INVALID_PIPABLE_WIM
* Data read from the pipable WIM was invalid.
@@ -2470,12 +2463,19 @@ wimlib_extract_image_from_pipe(int pipe_fd,
wimlib_progress_func_t progress_func);
/**
- * Similar to wimlib_extract_paths(), but the paths to extract from the WIM
- * image are specified in the UTF-8 text file named by @p path_list_file which
- * itself contains the list of paths to use, one per line. Leading and trailing
- * whitespace, and otherwise empty lines and lines beginning with the ';'
- * character are ignored. No quotes are needed as paths are otherwise delimited
- * by the newline character.
+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to
+ * extract from the WIM image are specified in the UTF-8 text file named by @p
+ * path_list_file which itself contains the list of paths to use, one per line.
+ * Leading and trailing whitespace, and otherwise empty lines and lines
+ * beginning with the ';' character are ignored. No quotes are needed as paths
+ * are otherwise delimited by the newline character.
+ *
+ * The error codes are the same as those returned by wimlib_extract_paths(),
+ * except that wimlib_extract_pathlist() returns an appropriate error code if it
+ * cannot read the path list file (::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT,
+ * ::WIMLIB_ERR_READ, ::WIMLIB_ERR_NOMEM, or ::WIMLIB_ERR_INVALID_UTF8_STRING).
*/
extern int
wimlib_extract_pathlist(WIMStruct *wim, int image,
@@ -2485,30 +2485,83 @@ wimlib_extract_pathlist(WIMStruct *wim, int image,
wimlib_progress_func_t progress_func);
/**
- * Similar to wimlib_extract_files(), but the files or directories to extract
- * from the WIM image are specified as an array of paths.
- *
- * Each path will be extracted to a corresponding subdirectory of the @p target
- * based on its location in the WIM image. For example, if one of the paths to
- * extract is "/Windows/explorer.exe" and the target is "outdir", the file will
- * be extracted to "outdir/Windows/explorer.exe". Each path to extract must be
- * specified as the absolute path to a directory within the WIM image.
- * Separators in the paths to extract may be either forwards or backwards
- * slashes, and leading path separators are optional. Symbolic links are not
- * dereferenced when interpreting paths to extract. Paths to extract will be
- * interpreted either case-sensitively (UNIX default) or case-insensitively
- * (Windows default); this can be changed by wimlib_global_init().
- *
- * The @p target path, on the other hand, is expected to be a native path. On
- * UNIX-like systems it may not contain backslashes, for example.
- *
- * By default, if any paths to extract do not exist,
- * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is issued. This behavior changes if
- * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified.
- *
- * With ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified in @p extract_flags, this
- * function additionally allows paths to be globs using the wildcard characters
- * '*' and '?'.
+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0: Extract zero or more paths (files or directory trees)
+ * from the specified WIM image.
+ *
+ * By default, each path will be extracted to a corresponding subdirectory of
+ * the target based on its location in the WIM image. For example, if one of
+ * the paths to extract is "/Windows/explorer.exe" and the target is "outdir",
+ * the file will be extracted to "outdir/Windows/explorer.exe". This behavior
+ * can be changed by providing the flag
+ * ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE, which will cause each file
+ * or directory tree to be placed directly in the target directory --- so the
+ * same example would extract "/Windows/explorer.exe" to "outdir/explorer.exe".
+ *
+ * Symbolic links will not be dereferenced when paths in the WIM image are
+ * interpreted.
+ *
+ * @param wim
+ * WIM from which to extract the paths, specified as a pointer to the
+ * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a
+ * split WIM. In the case of a WIM file that is not standalone, this
+ * ::WIMStruct must have had any needed external resources previously
+ * referenced using wimlib_reference_resources() or
+ * wimlib_reference_resource_files().
+ * @param image
+ * 1-based index of the WIM image from which to extract the paths.
+ * @param paths
+ * Array of paths to extract. Each element must be the absolute path to a
+ * file or directory within the WIM image. Separators may be either
+ * forwards or backwards slashes, and leading path separators are optional.
+ * The paths will be interpreted either case-sensitively (UNIX default) or
+ * case-insensitively (Windows default); this can be changed by
+ * wimlib_global_init().
+ *
+ * By default, the characters @c * and @c ? are interpreted literally.
+ * This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p
+ * extract_flags.
+ *
+ * By default, if any paths to extract do not exist, the error code
+ * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is returned. This behavior changes if
+ * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified in @p extract_flags.
+ * @param num_paths
+ * Number of paths specified in @p paths.
+ * @param target
+ * Directory to which to extract the paths; or with
+ * ::WIMLIB_EXTRACT_FLAG_NTFS specified in @p extract_flags, the path to an
+ * unmounted NTFS volume to which to extract the paths. Unlike the @p
+ * paths being extracted, the @p target must be native path. On UNIX-like
+ * systems it may not contain backslashes, for example.
+ * @param extract_flags
+ * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG.
+ * @param progress_func
+ * If non-NULL, a function that will be called periodically with the
+ * progress of the current operation. The main message to look for is
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS; however, there are others as
+ * well. Note: because the extraction code is stream-based and not
+ * file-based, there is no way to get information about which path is
+ * currently being extracted, but based on byte count you can still
+ * calculate an approximate percentage complete for the extraction overall
+ * which may be all you really need anyway.
+ *
+ * @return 0 on success; nonzero on error. Most of the error codes are the same
+ * as those returned by wimlib_extract_image(). Below, some of the error codes
+ * returned in situations specific to path-mode extraction are documented:
+ *
+ * @retval ::WIMLIB_ERR_INVALID_IMAGE
+ * @p image was ::WIMLIB_ALL_IMAGES or was otherwise not a valid single
+ * image in the WIM.
+ * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST
+ * One of the paths to extract did not exist in the WIM image. This error
+ * code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not
+ * specified in @p extract_flags, or if both
+ * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS and ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB
+ * were specified in @p extract_flags.
+ * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE
+ * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified in @p extract_flags, but
+ * one of the paths to extract did not name a regular file.
*/
extern int
wimlib_extract_paths(WIMStruct *wim,
@@ -2566,12 +2619,11 @@ wimlib_free(WIMStruct *wim);
* Converts a ::wimlib_compression_type value into a string.
*
* @param ctype
- * ::WIMLIB_COMPRESSION_TYPE_NONE, ::WIMLIB_COMPRESSION_TYPE_LZX,
- * ::WIMLIB_COMPRESSION_TYPE_XPRESS, or another value.
+ * The ::wimlib_compression_type value to convert.
*
* @return
- * A statically allocated string: "None", "LZX", "XPRESS", or "Invalid",
- * respectively.
+ * A statically allocated string naming the compression algorithm,
+ * such as "None", "LZX", "XPRESS", or "Invalid".
*/
extern const wimlib_tchar *
wimlib_get_compression_type_string(int ctype);
@@ -2633,6 +2685,19 @@ wimlib_get_image_description(const WIMStruct *wim, int image);
extern const wimlib_tchar *
wimlib_get_image_name(const WIMStruct *wim, int image);
+/**
+ * @ingroup G_general
+ *
+ * Returns the version of wimlib as a 32-bit number whose top 12 bits contain
+ * the major version, the next 10 bits contain the minor version, and the low 10
+ * bits contain the patch version.
+ *
+ * In other words, the returned value is equal to ((WIMLIB_MAJOR_VERSION
+ * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION) for the
+ * corresponding header file.
+ */
+extern uint32_t
+wimlib_get_version(void);
/**
* @ingroup G_wim_information
@@ -2905,7 +2970,7 @@ wimlib_join(const wimlib_tchar * const *swms,
* @param dir
* The path to an existing empty directory to mount the image on.
* @param mount_flags
- * Bitwise OR of the flags prefixed with WIMLIB_MOUNT_FLAG.
+ * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG.
* @param staging_dir
* If non-NULL, the name of a directory in which the staging directory will
* be created. Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified
@@ -2994,10 +3059,10 @@ wimlib_mount_image(WIMStruct *wim,
* in the integrity table.
* @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE
* Resources in @p wim_file are compressed, but the chunk size was invalid
- * for the WIM's compression format.
+ * for the WIM's compression type.
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
* The header of @p wim_file says that resources in the WIM are compressed,
- * but the header flag indicating LZX or XPRESS compression is not set.
+ * but the header flag for a recognized compression type is not set.
* @retval ::WIMLIB_ERR_INVALID_HEADER
* The header of @p wim_file was otherwise invalid.
* @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE
@@ -3005,9 +3070,7 @@ wimlib_mount_image(WIMStruct *wim,
* wim_file contains an integrity table, but the integrity table is
* invalid.
* @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY
- * The lookup table for the WIM contained duplicate entries that are not
- * for metadata resources, or it contained an entry with a SHA1 message
- * digest of all 0's.
+ * The lookup table for the WIM was invalid.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p wim_ret was @c NULL.
* @retval ::WIMLIB_ERR_IS_SPLIT_WIM
@@ -3024,8 +3087,10 @@ wimlib_mount_image(WIMStruct *wim,
* @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE
* Unexpected end-of-file while reading data from @p wim_file.
* @retval ::WIMLIB_ERR_UNKNOWN_VERSION
- * A number other than 0x10d00 is written in the version field of the WIM
- * header of @p wim_file. (May be a pre-Vista WIM.)
+ * The WIM version number was not recognized. (May be a pre-Vista WIM.)
+ * @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED
+ * The WIM cannot be opened because it contains encrypted segments. (It
+ * may be a Windows 8 "ESD" file).
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
@@ -3146,15 +3211,6 @@ wimlib_print_available_images(const WIMStruct *wim, int image);
extern void
wimlib_print_header(const WIMStruct *wim) _wimlib_deprecated;
-/**
- * @ingroup G_wim_information
- *
- * Deprecated in favor of wimlib_iterate_dir_tree(), which provides the
- * information in a way that can be accessed programatically.
- */
-extern int
-wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated;
-
/**
* @ingroup G_nonstandalone_wims
*
@@ -3383,25 +3439,23 @@ wimlib_set_image_descripton(WIMStruct *wim, int image,
* Set the compression chunk size of a WIM to use in subsequent calls to
* wimlib_write() or wimlib_overwrite().
*
- * A compression chunk size will result in a greater compression ratio, but the
- * speed of random access to the WIM will be reduced, and the effect of an
- * increased compression chunk size is limited by the size of each file being
- * compressed.
+ * For compatibility reasons, using this function is not generally recommended.
+ * See the documentation for the @c --chunk-size option of wimlib-imagex
+ * capture for more information.
*
- * WARNING: Microsoft's software is seemingly incompatible with LZX chunk
- * sizes other than 32768. Chunk sizes other than 32768 (for any format) are
- * also incompatible with wimlib v1.5.3 and earlier.
+ * A larger compression chunk size will likely result in a better compression
+ * ratio, but the speed of random access to the WIM will be reduced.
+ * Furthermore, the effect of a larger compression chunk size is limited by the
+ * size of each stream ("file") being compressed.
*
* @param wim
* ::WIMStruct for a WIM.
- * @param out_chunk_size
+ * @param chunk_size
* The chunk size (in bytes) to set. The valid chunk sizes are dependent
- * on the compression format. The XPRESS and LZMS compression formats
- * support chunk sizes that are powers of 2 with exponents between 15 and
- * 26 inclusively, whereas the LZX compression format supports chunk sizes
- * that are powers of 2 with exponents between 15 and 21 inclusively. As a
- * special case, if @p out_chunk_size is specified as 0, the chunk size is
- * set to the default for the currently selected output compression type.
+ * on the compression format; see the documentation for the @c --chunk-size
+ * option of wimlib-imagex capture for more information. As a
+ * special case, if @p chunk_size is specified as 0, the chunk size is set
+ * to the default for the currently selected output compression type.
*
* @return 0 on success; nonzero on error.
*
@@ -3447,7 +3501,12 @@ wimlib_set_output_compression_type(WIMStruct *wim, int ctype);
* @ingroup G_writing_and_overwriting_wims
*
* Similar to wimlib_set_output_compression_type(), but set the compression type
- * for writing packed streams.
+ * 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);
@@ -3952,10 +4011,7 @@ wimlib_write_to_fd(WIMStruct *wim,
* decompressors currently support sliding windows, and there also exist
* slightly different variants of these formats that are not supported
* unmodified.
- */
-
-/**
- * @ingroup G_compression
+ *
* @{
*/
@@ -4118,6 +4174,8 @@ struct wimlib_decompressor;
*
* @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE
* @p ctype was not a supported compression type.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p params were invalid.
* @retval ::WIMLIB_ERR_NOMEM
* Not enough memory to duplicate the parameters (perhaps @c params->size
* was invalid).
@@ -4126,6 +4184,18 @@ extern int
wimlib_set_default_compressor_params(enum wimlib_compression_type ctype,
const struct wimlib_compressor_params_header *params);
+/**
+ * Returns the approximate number of bytes needed to allocate a compressor with
+ * wimlib_create_compressor() for the specified compression type, block size,
+ * and parameters. @p params may be @c NULL, in which case the current default
+ * parameters for @p ctype are used. Returns 0 if the compression type or
+ * parameters are invalid.
+ */
+extern uint64_t
+wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype,
+ size_t max_block_size,
+ const struct wimlib_compressor_params_header *params);
+
/**
* Allocate a compressor for the specified compression type using the specified
* parameters.
@@ -4330,8 +4400,18 @@ 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