Loading...
Searching...
No Matches
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.