X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=src%2Fwimlib.h;h=c81b42f49f576eaa9244765558e7dde8314cfeb0;hb=999a45964048b4b34e8751a6ca06d834a1958bde;hp=0dd705c7e038449e338ac4f136237b92f447ed0f;hpb=bde99a849d3e7a479cb04a4e16e405b0c2f022dd;p=wimlib diff --git a/src/wimlib.h b/src/wimlib.h index 0dd705c7..c81b42f4 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -31,6 +31,10 @@ * * \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 @@ -211,6 +215,10 @@ #include #include +#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 @@ -263,6 +271,11 @@ enum wimlib_progress_msg { * 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. */ @@ -277,22 +290,28 @@ enum wimlib_progress_msg { * ::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, @@ -375,6 +394,15 @@ union wimlib_progress_info { 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, @@ -386,6 +414,12 @@ union wimlib_progress_info { /** 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; @@ -393,6 +427,10 @@ union wimlib_progress_info { * 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.) @@ -506,6 +544,7 @@ union wimlib_progress_info { typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, const union wimlib_progress_info *info); + /***************************** * WIMLIB_ADD_IMAGE_FLAG_* * *****************************/ @@ -517,8 +556,9 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * 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. */ @@ -547,8 +587,10 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * 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. */ @@ -635,6 +677,7 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, */ 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, @@ -1362,10 +1405,17 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * 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 @@ -1543,6 +1593,11 @@ extern int wimlib_open_wim(const char *wim_file, int open_flags, * * @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(). @@ -1712,8 +1767,8 @@ extern void wimlib_print_wim_information(const WIMStruct *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);