*
* \section intro Introduction
*
+ * This is the documentation for the library interface of wimlib 1.2.0. If you
+ * have installed wimlib and want to know how to use the @c imagex program,
+ * please see the man pages instead.
+ *
* wimlib is a C library to read, write, and mount archive files in the Windows
* Imaging Format (WIM files). These files are normally created using the @c
* imagex.exe utility on Windows, but this library provides a free
#include <stdbool.h>
#include <inttypes.h>
+#define WIMLIB_MAJOR_VERSION 1
+#define WIMLIB_MINOR_VERSION 2
+#define WIMLIB_PATCH_VERSION 0
+
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
* and need not correspond to a specific on-disk file. However, a ::WIMStruct
* info will point to ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
+ /** A file or directory is being extracted. @a info will point to
+ * ::wimlib_progress_info.extract, and the @a cur_path member will be
+ * valid. */
+ WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY,
+
/** All the WIM files and directories have been extracted, and
* timestamps are about to be applied. @a info will point to
* ::wimlib_progress_info.extract. */
* ::wimlib_progress_info.scan. */
WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
+ /** A directory or file is being scanned. @a info will point to
+ * ::wimlib_progress_info.scan, and its @a cur_path member will be
+ * valid. This message is only sent if ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE
+ * is passed to wimlib_add_image(). */
+ 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. @a info will point to
* ::wimlib_progress_info.scan. */
WIMLIB_PROGRESS_MSG_SCAN_END,
- /**
+ /**
* File resources are currently being written to the WIM.
* @a info will point to ::wimlib_progress_info.write_streams. */
WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
- /**
+ /**
* The metadata resource for each image is about to be written to the
* WIM. @a info will not be valid. */
WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
- /**
+ /**
* The metadata resource for each image has successfully been writen to
* the WIM. @a info will not be valid. */
WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
struct wimlib_progress_info_scan {
/** Directory or NTFS volume that is being scanned. */
const char *source;
+
+ /** Path to the file or directory that is about to be scanned,
+ * relative to the root of the image capture or the NTFS volume.
+ * */
+ const char *cur_path;
+
+ /** True iff @a cur_path is being excluded from the image
+ * capture due to the capture configuration file. */
+ bool excluded;
} scan;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
/** Number of the image being extracted (1-based). */
int image;
+ /** Flags passed to to wimlib_extract_image() */
+ int extract_flags;
+
+ /** Full path to the WIM file being extracted. */
+ const char *wimfile_name;
+
/** Name of the image being extracted. */
const char *image_name;
* extracted. */
const char *target;
+ /** Current dentry being extracted. (Valid only if message is
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY.) */
+ const char *cur_path;
+
/** Number of bytes of uncompressed data that will be extracted.
* Takes into account hard links (they are not counted for each
* link.)
typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
const union wimlib_progress_info *info);
+
/*****************************
* WIMLIB_ADD_IMAGE_FLAG_* *
*****************************/
* with ::WIMLIB_ADD_IMAGE_FLAG_NTFS. */
#define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE 0x00000002
-/** Print the name of each file or directory as it is scanned to be included in
- * the WIM image. */
+/** Call the progress function with the message
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to
+ * be scanned. */
#define WIMLIB_ADD_IMAGE_FLAG_VERBOSE 0x00000004
/** Mark the image being added as the bootable image of the WIM. */
* together. Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
#define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004
-/** Print the name of each file or directory as it is extracted from the WIM
- * image. */
+/** Call the progress function with the argument
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY each time a file or directory is
+ * extracted. Note: these calls will be interspersed with calls for the message
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. */
#define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008
/** Read the WIM file sequentially while extracting the image. */
*/
enum wimlib_error_code {
WIMLIB_ERR_SUCCESS = 0,
+ WIMLIB_ERR_ALREADY_LOCKED,
WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
WIMLIB_ERR_DECOMPRESSION,
WIMLIB_ERR_DELETE_STAGING_DIR,
* This number should be one less than the total number of parts in the
* split WIM. Set to 0 if the WIM is a standalone WIM.
* @param staging_dir
- * Currently ignored, but may provide a way to specify the staging
- * directory in the future. Set to @c NULL.
+ * 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
+ * in @a mount_flags. If left @c NULL, the staging directory is created in
+ * the same directory as the WIM file that @a wim was originally read from.
*
* @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_ALREADY_LOCKED
+ * A read-write mount was requested, but an an exclusive advisory lock on
+ * the on-disk WIM file could not be acquired because another thread or
+ * process has mounted an image from the WIM read-write or is currently
+ * modifying the WIM in-place.
* @retval ::WIMLIB_ERR_DECOMPRESSION
* Could not decompress the metadata resource for @a image in @a wim.
* @retval ::WIMLIB_ERR_FUSE
*
* @return 0 on success; nonzero on error. This function may return any value
* returned by wimlib_write() as well as the following error codes:
+ * @retval ::WIMLIB_ERR_ALREADY_LOCKED
+ * The WIM was going to be modifien in-place (with no temporary file), but
+ * an exclusive advisory lock on the on-disk WIM file could not be acquired
+ * because another thread or process has mounted an image from the WIM
+ * read-write or is currently modifying the WIM in-place.
* @retval ::WIMLIB_ERR_NO_FILENAME
* @a wim corresponds to a WIM created with wimlib_create_new_wim() rather
* than a WIM read with wimlib_open_wim().
* image, indexed starting at 1, is returned. If the keyword "all" or "*"
* was specified, ::WIMLIB_ALL_IMAGES is returned. Otherwise,
* ::WIMLIB_NO_IMAGE is returned. If @a image_name_or_num was @c NULL or
- * the empty string, ::WIM_NO_IMAGE is returned, even if one or more images
- * in @a wim has no name.
+ * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more
+ * images in @a wim has no name.
*/
extern int wimlib_resolve_image(WIMStruct *wim, const char *image_name_or_num);
git://wimlib.net / wimlib / blobdiff