Progress Messages

Track the progress of long WIM operations. More...

Data Structures
union	wimlib_progress_info
	A pointer to this union is passed to the user-supplied wimlib_progress_func_t progress function. More...

Typedefs
typedef enum wimlib_progress_status(*	wimlib_progress_func_t) (enum wimlib_progress_msg msg_type, union wimlib_progress_info *info, void *progctx)
	A user-supplied function that will be called periodically during certain WIM operations.

Enumerations
enum	wimlib_progress_msg {   WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0 , WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1 , WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE = 3 , WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS = 4 ,   WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5 , WIMLIB_PROGRESS_MSG_EXTRACT_METADATA = 6 , WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END = 7 , WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END = 8 ,   WIMLIB_PROGRESS_MSG_SCAN_BEGIN = 9 , WIMLIB_PROGRESS_MSG_SCAN_DENTRY = 10 , WIMLIB_PROGRESS_MSG_SCAN_END = 11 , WIMLIB_PROGRESS_MSG_WRITE_STREAMS = 12 ,   WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN = 13 , WIMLIB_PROGRESS_MSG_WRITE_METADATA_END = 14 , WIMLIB_PROGRESS_MSG_RENAME = 15 , WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY = 16 ,   WIMLIB_PROGRESS_MSG_CALC_INTEGRITY = 17 , WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART = 19 , WIMLIB_PROGRESS_MSG_SPLIT_END_PART = 20 , WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND = 21 ,   WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND = 22 , WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM = 23 , WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24 , WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25 ,   WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26 , WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE = 27 , WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE = 28 , WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29 ,   WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION = 30 , WIMLIB_PROGRESS_MSG_HANDLE_ERROR = 31 }
	Possible values of the first parameter to the user-supplied wimlib_progress_func_t progress function. More...
enum	wimlib_progress_status { WIMLIB_PROGRESS_STATUS_CONTINUE = 0 , WIMLIB_PROGRESS_STATUS_ABORT = 1 }
	Valid return values from user-provided progress functions (wimlib_progress_func_t). More...

Detailed Description

Track the progress of long WIM operations.

Library users can provide a progress function which will be called periodically during operations such as extracting a WIM image or writing a WIM image. A WIMStruct can have a progress function of type wimlib_progress_func_t associated with it by calling wimlib_register_progress_function() or by opening the WIMStruct using wimlib_open_wim_with_progress(). Once this is done, the progress function will be called automatically during many operations, such as wimlib_extract_image() and wimlib_write().

Some functions that do not operate directly on a user-provided WIMStruct, such as wimlib_join(), also take the progress function directly using an extended version of the function, such as wimlib_join_with_progress().

Since wimlib v1.7.0, progress functions are no longer just unidirectional. You can now return WIMLIB_PROGRESS_STATUS_ABORT to cause the current operation to be aborted. wimlib v1.7.0 also added the third argument to wimlib_progress_func_t, which is a user-supplied context.

Typedef Documentation

wimlib_progress_func_t

typedef enum wimlib_progress_status(* wimlib_progress_func_t) (enum wimlib_progress_msg msg_type, union wimlib_progress_info *info, void *progctx)

A user-supplied function that will be called periodically during certain WIM operations.

The first argument will be the type of operation that is being performed or is about to be started or has been completed.

The second argument will be a pointer to one of a number of structures depending on the first argument. It may be NULL for some message types. Note that although this argument is not const, users should not modify it except in explicitly documented cases.

The third argument will be a user-supplied value that was provided when registering or specifying the progress function.

This function must return one of the wimlib_progress_status values. By default, you should return WIMLIB_PROGRESS_STATUS_CONTINUE (0).

Enumeration Type Documentation

wimlib_progress_msg

enum wimlib_progress_msg

Possible values of the first parameter to the user-supplied wimlib_progress_func_t progress function.

Enumerator
WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN	A WIM image is about to be extracted. info will point to 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_TREE_BEGIN	One or more file or directory trees within a WIM image is about to be extracted. info will point to wimlib_progress_info.extract. 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_FILE_STRUCTURE	This message may be sent periodically (not for every file) while files and directories are being created, prior to file data extraction. info will point to wimlib_progress_info.extract. In particular, the current_file_count and end_file_count members may be used to track the progress of this phase of extraction.
WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS	File data is currently being extracted. info will point to wimlib_progress_info.extract. This is the main message to track the progress of an extraction operation.
WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN	Starting to read a new part of a split pipable WIM over the pipe. info will point to wimlib_progress_info.extract.
WIMLIB_PROGRESS_MSG_EXTRACT_METADATA	This message may be sent periodically (not necessarily for every file) while file and directory metadata is being extracted, following file data extraction. info will point to wimlib_progress_info.extract. The current_file_count and end_file_count members may be used to track the progress of this phase of extraction.
WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END	The image has been successfully extracted. info will point to wimlib_progress_info.extract. This is paired with WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN.
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END	The files or directory trees have been successfully extracted. info will point to wimlib_progress_info.extract. This is paired with WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN.
WIMLIB_PROGRESS_MSG_SCAN_BEGIN	The directory or NTFS volume is about to be scanned for metadata. 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_DENTRY	A directory or file has been scanned. info will point to wimlib_progress_info.scan, and its cur_path member will be valid. This message is only sent if WIMLIB_ADD_FLAG_VERBOSE has been specified.
WIMLIB_PROGRESS_MSG_SCAN_END	The directory or NTFS volume has been successfully scanned. 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_WRITE_STREAMS	File data is currently being written to the WIM. 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(). Since wimlib v1.13.4 it will also be received when a split WIM part is being written by wimlib_split().
WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN	Per-image metadata is about to be written to the WIM file. info will not be valid.
WIMLIB_PROGRESS_MSG_WRITE_METADATA_END	The per-image metadata has been written to the WIM file. info will not be valid. This message is paired with a preceding WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message.
WIMLIB_PROGRESS_MSG_RENAME	wimlib_overwrite() has successfully renamed the temporary file to the original WIM file, thereby committing the changes to the WIM file. 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_VERIFY_INTEGRITY	The contents of the WIM file are being checked against the integrity table. info will point to wimlib_progress_info.integrity. This message is only received (and may be received many times) when wimlib_open_wim_with_progress() is called with the WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag.
WIMLIB_PROGRESS_MSG_CALC_INTEGRITY	An integrity table is being calculated for the WIM being written. 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_SPLIT_BEGIN_PART	A wimlib_split() operation is in progress, and a new split part is about to be started. info will point to wimlib_progress_info.split.
WIMLIB_PROGRESS_MSG_SPLIT_END_PART	A wimlib_split() operation is in progress, and a split part has been finished. info will point to wimlib_progress_info.split.
WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND	A WIM update command is about to be executed. 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	A WIM update command has been executed. 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_REPLACE_FILE_IN_WIM	A file in the image is being replaced as a result of a wimlib_add_command without WIMLIB_ADD_FLAG_NO_REPLACE specified. 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_WIMBOOT_EXCLUDE	An image is being extracted 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_UNMOUNT_BEGIN	Starting to unmount an image. info will point to wimlib_progress_info.unmount.
WIMLIB_PROGRESS_MSG_DONE_WITH_FILE	wimlib has used a file's data for the last time (including all data streams, if it has multiple). info will point to wimlib_progress_info.done_with_file. This message is only received if WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided.
WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE	wimlib_verify_wim() is starting to verify the metadata for an image. info will point to wimlib_progress_info.verify_image.
WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE	wimlib_verify_wim() has finished verifying the metadata for an image. info will point to wimlib_progress_info.verify_image.
WIMLIB_PROGRESS_MSG_VERIFY_STREAMS	wimlib_verify_wim() is verifying file data integrity. info will point to wimlib_progress_info.verify_streams.
WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION	The progress function is being asked whether a file should be excluded from capture or not. info will point to wimlib_progress_info.test_file_exclusion. This is a bidirectional message that allows the progress function to set a flag if the file should be excluded. This message is only received if the flag WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION is used. This method for file exclusions is independent of the "capture configuration file" mechanism.
WIMLIB_PROGRESS_MSG_HANDLE_ERROR	An error has occurred and the progress function is being asked whether to ignore the error or not. info will point to wimlib_progress_info.handle_error. This is a bidirectional message. This message provides a limited capability for applications to recover from "unexpected" errors (i.e. those with no in-library handling policy) arising from the underlying operating system. Normally, any such error will cause the library to abort the current operation. By implementing a handler for this message, the application can instead choose to ignore a given error. Currently, only the following types of errors will result in this progress message being sent: Directory tree scan errors, e.g. from wimlib_add_image() Most extraction errors; currently restricted to the Windows build of the library only.

wimlib_progress_status

enum wimlib_progress_status

Valid return values from user-provided progress functions (wimlib_progress_func_t).

(Note: if an invalid value is returned, WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS will be issued.)

Enumerator
WIMLIB_PROGRESS_STATUS_CONTINUE	The operation should be continued. This is the normal return value.
WIMLIB_PROGRESS_STATUS_ABORT	The operation should be aborted. This will cause the current operation to fail with WIMLIB_ERR_ABORTED_BY_PROGRESS.