Loading...
Searching...
No Matches
Modifying WIMs

Make changes to a WIMStruct, in preparation of persisting the WIMStruct to an on-disk file. More...

## Data Structures

struct | wimlib_capture_source
| An array of these structures is passed to wimlib_add_image_multisource() to specify the sources from which to create a WIM image. More...
struct | wimlib_add_command
| Data for a WIMLIB_UPDATE_OP_ADD operation. More...
struct | wimlib_delete_command
| Data for a WIMLIB_UPDATE_OP_DELETE operation. More...
struct | wimlib_rename_command
| Data for a WIMLIB_UPDATE_OP_RENAME operation. More...
struct | wimlib_update_command
| Specification of an update to perform on a WIM image. More...

## Macros

#define | WIMLIB_CHANGE_READONLY_FLAG 0x00000001
| Set or unset the "readonly" WIM header flag (`WIM_HDR_FLAG_READONLY` in Microsoft's documentation), based on the wimlib_wim_info.is_marked_readonly member of the `info` parameter.
#define | WIMLIB_CHANGE_GUID 0x00000002
| Set the GUID (globally unique identifier) of the WIM file to the value specified in wimlib_wim_info.guid of the `info` parameter.
#define | WIMLIB_CHANGE_BOOT_INDEX 0x00000004
| Change the bootable image of the WIM to the value specified in wimlib_wim_info.boot_index of the `info` parameter.
#define | WIMLIB_CHANGE_RPFIX_FLAG 0x00000008
| Change the `WIM_HDR_FLAG_RP_FIX` flag of the WIM file to the value specified in wimlib_wim_info.has_rpfix of the `info` parameter.
#define | WIMLIB_ADD_FLAG_NTFS 0x00000001
| UNIX-like systems only: Directly capture an NTFS volume rather than a generic directory.
#define | WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
| Follow symbolic links when scanning the directory tree.
#define | WIMLIB_ADD_FLAG_VERBOSE 0x00000004
| Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been scanned.
#define | WIMLIB_ADD_FLAG_BOOT 0x00000008
| Mark the image being added as the bootable image of the WIM.
#define | WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
| UNIX-like systems only: Store the UNIX owner, group, mode, and device ID (major and minor number) of each file.
#define | WIMLIB_ADD_FLAG_NO_ACLS 0x00000020
| Do not capture security descriptors.
#define | WIMLIB_ADD_FLAG_STRICT_ACLS 0x00000040
| Fail immediately if the full security descriptor of any file or directory cannot be accessed.
#define | WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE 0x00000080
| Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from capture.
#define | WIMLIB_ADD_FLAG_RPFIX 0x00000100
| Reparse-point fixups: Modify absolute symbolic links (and junctions, in the case of Windows) that point inside the directory being captured to instead be absolute relative to the directory being captured.
#define | WIMLIB_ADD_FLAG_NORPFIX 0x00000200
| Don't do reparse point fixups.
#define | WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
| Do not automatically exclude unsupported files or directories from capture, such as encrypted files in NTFS-3G capture mode, or device files and FIFOs on UNIX-like systems when not also using WIMLIB_ADD_FLAG_UNIX_DATA.
#define | WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
| Automatically select a capture configuration appropriate for capturing filesystems containing Windows operating systems.
#define | WIMLIB_ADD_FLAG_WIMBOOT 0x00001000
| Capture image as "WIMBoot compatible".
#define | WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000
| If the add command involves adding a non-directory file to a location at which there already exists a nondirectory file in the image, issue WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file.
#define | WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
| Send WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress function.
#define | WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000
| Since wimlib v1.9.0: create a temporary filesystem snapshot of the source directory and add the files from it.
#define | WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED 0x00010000
| Since wimlib v1.9.0: permit the library to discard file paths after the initial scan.
#define | WIMLIB_DELETE_FLAG_FORCE 0x00000001
| Do not issue an error if the path to delete does not exist.
#define | WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002
| Delete the file or directory tree recursively; if not specified, an error is issued if the path to delete is a directory.
#define | WIMLIB_EXPORT_FLAG_BOOT 0x00000001
| If a single image is being exported, mark it bootable in the destination WIM.
#define | WIMLIB_EXPORT_FLAG_NO_NAMES 0x00000002
| Give the exported image(s) no names.
#define | WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004
| Give the exported image(s) no descriptions.
#define | WIMLIB_EXPORT_FLAG_GIFT 0x00000008
| This advises the library that the program is finished with the source WIMStruct and will not attempt to access it after the call to wimlib_export_image(), with the exception of the call to wimlib_free().
#define | WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010
| Mark each exported image as WIMBoot-compatible.
#define | WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001
| Send WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages.

## Enumerations

enum | wimlib_update_op { WIMLIB_UPDATE_OP_ADD = 0 , WIMLIB_UPDATE_OP_DELETE = 1 , WIMLIB_UPDATE_OP_RENAME = 2 }
| The specific type of update to perform. More...

## Functions

WIMLIBAPI int | wimlib_add_empty_image (WIMStruct *wim, const wimlib_tchar *name, int *new_idx_ret)
| Append an empty image to a WIMStruct.
WIMLIBAPI int | wimlib_add_image (WIMStruct *wim, const wimlib_tchar *source, const wimlib_tchar *name, const wimlib_tchar *config_file, int add_flags)
| Add an image to a WIMStruct from an on-disk directory tree or NTFS volume.
WIMLIBAPI int | wimlib_add_image_multisource (WIMStruct *wim, const struct wimlib_capture_source *sources, size_t num_sources, const wimlib_tchar *name, const wimlib_tchar *config_file, int add_flags)
| This function is equivalent to wimlib_add_image() except it allows for multiple sources to be combined into a single WIM image.
WIMLIBAPI int | wimlib_add_tree (WIMStruct *wim, int image, const wimlib_tchar *fs_source_path, const wimlib_tchar *wim_target_path, int add_flags)
| Add the file or directory tree at `fs_source_path` on the filesystem to the location `wim_target_path` within the specified `image` of the `wim`.
WIMLIBAPI int | wimlib_delete_image (WIMStruct *wim, int image)
| Delete an image, or all images, from a WIMStruct.
WIMLIBAPI int | wimlib_delete_path (WIMStruct *wim, int image, const wimlib_tchar *path, int delete_flags)
| Delete the `path` from the specified `image` of the `wim`.
WIMLIBAPI int | wimlib_export_image (WIMStruct *src_wim, int src_image, WIMStruct *dest_wim, const wimlib_tchar *dest_name, const wimlib_tchar *dest_description, int export_flags)
| Export an image, or all images, from a WIMStruct into another WIMStruct.
WIMLIBAPI int | wimlib_reference_template_image (WIMStruct *wim, int new_image, WIMStruct *template_wim, int template_image, int flags)
| Declare that a newly added image is mostly the same as a prior image, but captured at a later point in time, possibly with some modifications in the intervening time.
WIMLIBAPI int | wimlib_rename_path (WIMStruct *wim, int image, const wimlib_tchar *source_path, const wimlib_tchar *dest_path)
| Rename the `source_path` to the `dest_path` in the specified `image` of the `wim`.
WIMLIBAPI int | wimlib_set_image_descripton (WIMStruct *wim, int image, const wimlib_tchar *description)
| Change the description of a WIM image.
WIMLIBAPI int | wimlib_set_image_flags (WIMStruct *wim, int image, const wimlib_tchar *flags)
| Change what is stored in the <FLAGS> element in the WIM XML document (usually something like "Core" or "Ultimate").
WIMLIBAPI int | wimlib_set_image_name (WIMStruct *wim, int image, const wimlib_tchar *name)
| Change the name of a WIM image.
WIMLIBAPI int | wimlib_set_image_property (WIMStruct *wim, int image, const wimlib_tchar *property_name, const wimlib_tchar *property_value)
| Since wimlib v1.8.3: add, modify, or remove a per-image property from the WIM's XML document.
WIMLIBAPI int | wimlib_set_wim_info (WIMStruct *wim, const struct wimlib_wim_info *info, int which)
| Set basic information about a WIM.
WIMLIBAPI int | wimlib_update_image (WIMStruct *wim, int image, const struct wimlib_update_command *cmds, size_t num_cmds, int update_flags)
| Update a WIM image by adding, deleting, and/or renaming files or directories.

## Detailed Description

Make changes to a WIMStruct, in preparation of persisting the WIMStruct to an on-disk file.

# Capturing and adding WIM images

As described in Basic WIM handling concepts, capturing a new WIM or appending an image to an existing WIM is a multi-step process, but at its core is wimlib_add_image() or an equivalent function. Normally, wimlib_add_image() takes an on-disk directory tree and logically adds it to a WIMStruct as a new image. However, when supported by the build of the library, there is also a special NTFS volume capture mode (entered when WIMLIB_ADD_FLAG_NTFS is specified) that allows adding the image directly from an unmounted NTFS volume.

Another function, wimlib_add_image_multisource() is also provided. It generalizes wimlib_add_image() to allow combining multiple files or directory trees into a single WIM image in a configurable way.

For maximum customization of WIM image creation, it is also possible to add a completely empty WIM image with wimlib_add_empty_image(), then update it with wimlib_update_image(). (This is in fact what wimlib_add_image() and wimlib_add_image_multisource() do internally.)

Note that some details of how image addition/capture works are documented more fully in the documentation for wimcapture.

# Deleting WIM images

wimlib_delete_image() can delete an image from a WIMStruct. But as usual, wimlib_write() or wimlib_overwrite() must be called to cause the changes to be made persistent in an on-disk WIM file.

# Exporting WIM images

wimlib_export_image() can copy, or "export", an image from one WIM to another.

# Other modifications

wimlib_update_image() can add, delete, and rename files in a WIM image.

wimlib_set_image_property() can change other image metadata.

wimlib_set_wim_info() can change information about the WIM file itself, such as the boot index.

## Macro Definition Documentation

## WIMLIB_CHANGE_READONLY_FLAG

#define WIMLIB_CHANGE_READONLY_FLAG 0x00000001

Set or unset the "readonly" WIM header flag (`WIM_HDR_FLAG_READONLY` in Microsoft's documentation), based on the wimlib_wim_info.is_marked_readonly member of the `info` parameter.

This is distinct from basic file permissions; this flag can be set on a WIM file that is physically writable.

wimlib disallows modifying on-disk WIM files with the readonly flag set. However, wimlib_overwrite() with WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG will override this — and in fact, this is necessary to set the readonly flag persistently on an existing WIM file.

## WIMLIB_CHANGE_GUID

#define WIMLIB_CHANGE_GUID 0x00000002

Set the GUID (globally unique identifier) of the WIM file to the value specified in wimlib_wim_info.guid of the `info` parameter.

## WIMLIB_CHANGE_BOOT_INDEX

#define WIMLIB_CHANGE_BOOT_INDEX 0x00000004

Change the bootable image of the WIM to the value specified in wimlib_wim_info.boot_index of the `info` parameter.

## WIMLIB_CHANGE_RPFIX_FLAG

#define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008

Change the `WIM_HDR_FLAG_RP_FIX` flag of the WIM file to the value specified in wimlib_wim_info.has_rpfix of the `info` parameter.

This flag generally indicates whether an image in the WIM has been captured with reparse-point fixups enabled. wimlib also treats this flag as specifying whether to do reparse-point fixups by default when capturing or applying WIM images.

## WIMLIB_ADD_FLAG_NTFS

#define WIMLIB_ADD_FLAG_NTFS 0x00000001

UNIX-like systems only: Directly capture an NTFS volume rather than a generic directory.

This requires that wimlib was compiled with support for libntfs-3g.

This flag cannot be combined with WIMLIB_ADD_FLAG_DEREFERENCE or WIMLIB_ADD_FLAG_UNIX_DATA.

Do not use this flag on Windows, where wimlib already supports all Windows-native filesystems, including NTFS, through the Windows APIs.

## WIMLIB_ADD_FLAG_DEREFERENCE

#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002

Follow symbolic links when scanning the directory tree.

Currently only supported on UNIX-like systems.

## WIMLIB_ADD_FLAG_VERBOSE

#define WIMLIB_ADD_FLAG_VERBOSE 0x00000004

Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been scanned.

## WIMLIB_ADD_FLAG_BOOT

#define WIMLIB_ADD_FLAG_BOOT 0x00000008

Mark the image being added as the bootable image of the WIM.

This flag is valid only for wimlib_add_image() and wimlib_add_image_multisource().

Note that you can also change the bootable image of a WIM using wimlib_set_wim_info().

Note: WIMLIB_ADD_FLAG_BOOT does something different from, and independent from, WIMLIB_ADD_FLAG_WIMBOOT.

## WIMLIB_ADD_FLAG_UNIX_DATA

#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010

UNIX-like systems only: Store the UNIX owner, group, mode, and device ID (major and minor number) of each file.

In addition, capture special files such as device nodes and FIFOs. Since wimlib v1.11.0, on Linux also capture extended attributes. See the documentation for the –unix-data option to wimcapture for more information.

## WIMLIB_ADD_FLAG_NO_ACLS

#define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020

Do not capture security descriptors.

Only has an effect in NTFS-3G capture mode, or in Windows native builds.

## WIMLIB_ADD_FLAG_STRICT_ACLS

#define WIMLIB_ADD_FLAG_STRICT_ACLS 0x00000040

Fail immediately if the full security descriptor of any file or directory cannot be accessed.

Only has an effect in Windows native builds. The default behavior without this flag is to first try omitting the SACL from the security descriptor, then to try omitting the security descriptor entirely.

## WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE

#define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE 0x00000080

Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from capture.

This is a subset of the messages provided by WIMLIB_ADD_FLAG_VERBOSE.

## WIMLIB_ADD_FLAG_RPFIX

#define WIMLIB_ADD_FLAG_RPFIX 0x00000100

Reparse-point fixups: Modify absolute symbolic links (and junctions, in the case of Windows) that point inside the directory being captured to instead be absolute relative to the directory being captured.

Without this flag, the default is to do reparse-point fixups if `WIM_HDR_FLAG_RP_FIX` is set in the WIM header or if this is the first image being added.

## WIMLIB_ADD_FLAG_NORPFIX

#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200

Don't do reparse point fixups.

See WIMLIB_ADD_FLAG_RPFIX.

## WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE

#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400

Do not automatically exclude unsupported files or directories from capture, such as encrypted files in NTFS-3G capture mode, or device files and FIFOs on UNIX-like systems when not also using WIMLIB_ADD_FLAG_UNIX_DATA.

Instead, fail with WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered.

## WIMLIB_ADD_FLAG_WINCONFIG

#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800

Automatically select a capture configuration appropriate for capturing filesystems containing Windows operating systems.

For example, `/pagefile.sys` and `"/System Volume Information"` will be excluded.

When this flag is specified, the corresponding `config` parameter (for wimlib_add_image()) or member (for wimlib_update_image()) must be `NULL`. Otherwise, WIMLIB_ERR_INVALID_PARAM will be returned.

Note that the default behavior— that is, when neither WIMLIB_ADD_FLAG_WINCONFIG nor WIMLIB_ADD_FLAG_WIMBOOT is specified and `config` is `NULL---` is to use no capture configuration, meaning that no files are excluded from capture.

## WIMLIB_ADD_FLAG_WIMBOOT

#define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000

Capture image as "WIMBoot compatible".

In addition, if no capture configuration file is explicitly specified use the capture configuration file `$SOURCE/Windows/System32/WimBootCompress.ini` if it exists, where `$SOURCE` is the directory being captured; or, if a capture configuration file is explicitly specified, use it and also place it at `/Windows/System32/WimBootCompress.ini` in the WIM image.

This flag does not, by itself, change the compression type or chunk size. Before writing the WIM file, you may wish to set the compression format to be the same as that used by WIMGAPI and DISM:

wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS);
wimlib_set_output_chunk_size(wim, 4096);
WIMLIB_COMPRESSION_TYPE_XPRESS
@ WIMLIB_COMPRESSION_TYPE_XPRESS
The XPRESS compression format.
Definition wimlib.h:547
wimlib_set_output_chunk_size
WIMLIBAPI int wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size)
Set a WIMStruct's output compression chunk size.
wimlib_set_output_compression_type
WIMLIBAPI int wimlib_set_output_compression_type(WIMStruct *wim, enum wimlib_compression_type ctype)
Set a WIMStruct's output compression type.

However, "WIMBoot" also works with other XPRESS chunk sizes as well as LZX with 32768 byte chunks.

Note: WIMLIB_ADD_FLAG_WIMBOOT does something different from, and independent from, WIMLIB_ADD_FLAG_BOOT.

Since wimlib v1.8.3, WIMLIB_ADD_FLAG_WIMBOOT also causes offline WIM-backed files to be added as the "real" files rather than as their reparse points, provided that their data is already present in the WIM. This feature can be useful when updating a backing WIM file in an "offline" state.

## WIMLIB_ADD_FLAG_NO_REPLACE

#define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000

If the add command involves adding a non-directory file to a location at which there already exists a nondirectory file in the image, issue WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file.

This was the default behavior before wimlib v1.7.0.

## WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION

#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000

Send WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress function.

Note: This method for file exclusions is independent from the capture configuration file mechanism.

## WIMLIB_ADD_FLAG_SNAPSHOT

#define WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000

Since wimlib v1.9.0: create a temporary filesystem snapshot of the source directory and add the files from it.

Currently, this option is only supported on Windows, where it uses the Volume Shadow Copy Service (VSS). Using this option, you can create a consistent backup of the system volume of a running Windows system without running into problems with locked files. For the VSS snapshot to be successfully created, your application must be run as an Administrator, and it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then your application must be 64-bit as well).

## WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED

#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED 0x00010000

Since wimlib v1.9.0: permit the library to discard file paths after the initial scan.

If the application won't use WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM archive, this flag can be used to allow the library to enable optimizations such as opening files by inode number rather than by path. Currently this only makes a difference on Windows.

## WIMLIB_DELETE_FLAG_FORCE

#define WIMLIB_DELETE_FLAG_FORCE 0x00000001

Do not issue an error if the path to delete does not exist.

## WIMLIB_DELETE_FLAG_RECURSIVE

#define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002

Delete the file or directory tree recursively; if not specified, an error is issued if the path to delete is a directory.

## WIMLIB_EXPORT_FLAG_BOOT

#define WIMLIB_EXPORT_FLAG_BOOT 0x00000001

If a single image is being exported, mark it bootable in the destination WIM.

Alternatively, if WIMLIB_ALL_IMAGES is specified as the image to export, the image in the source WIM (if any) that is marked as bootable is also marked as bootable in the destination WIM.

## WIMLIB_EXPORT_FLAG_NO_NAMES

#define WIMLIB_EXPORT_FLAG_NO_NAMES 0x00000002

Give the exported image(s) no names.

Avoids problems with image name collisions.

## WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS

#define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS 0x00000004

Give the exported image(s) no descriptions.

## WIMLIB_EXPORT_FLAG_GIFT

#define WIMLIB_EXPORT_FLAG_GIFT 0x00000008

This advises the library that the program is finished with the source WIMStruct and will not attempt to access it after the call to wimlib_export_image(), with the exception of the call to wimlib_free().

## WIMLIB_EXPORT_FLAG_WIMBOOT

#define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010

Mark each exported image as WIMBoot-compatible.

Note: by itself, this does change the destination WIM's compression type, nor does it add the file `\Windows\System32\WimBootCompress.ini` in the WIM image. Before writing the destination WIM, it's recommended to do something like:

wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS);
wimlib_set_output_chunk_size(wim, 4096);
wimlib_add_tree(wim, image, L"myconfig.ini",
L"\\Windows\\System32\\WimBootCompress.ini", 0);
wimlib_add_tree
WIMLIBAPI int wimlib_add_tree(WIMStruct *wim, int image, const wimlib_tchar *fs_source_path, const wimlib_tchar *wim_target_path, int add_flags)
Add the file or directory tree at fs_source_path on the filesystem to the location wim_target_path wi...

## WIMLIB_UPDATE_FLAG_SEND_PROGRESS

#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001

Send WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages.

## Enumeration Type Documentation

## wimlib_update_op

enum wimlib_update_op

The specific type of update to perform.

Enumerator
WIMLIB_UPDATE_OP_ADD | Add a new file or directory tree to the image.
WIMLIB_UPDATE_OP_DELETE | Delete a file or directory tree from the image.
WIMLIB_UPDATE_OP_RENAME | Rename a file or directory tree in the image.

## Function Documentation

## wimlib_add_empty_image()

WIMLIBAPI int wimlib_add_empty_image | ( | WIMStruct * | wim,
|  | const wimlib_tchar * | name,
|  | int * | new_idx_ret )

Append an empty image to a WIMStruct.

The new image will initially contain no files or directories, although if written without further modifications, then a root directory will be created automatically for it.

After calling this function, you can use wimlib_update_image() to add files to the new image. This gives you more control over making the new image compared to calling wimlib_add_image() or wimlib_add_image_multisource().

Parameters

  wim | Pointer to the WIMStruct to which to add the image.
  name | Name to give the new image. If `NULL` or empty, the new image is given no name. If nonempty, it must specify a name that does not already exist in `wim`.
  new_idx_ret | If non-`NULL`, the index of the newly added image is returned in this location.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_IMAGE_NAME_COLLISION | The WIM already contains an image with the requested name.

## wimlib_add_image()

WIMLIBAPI int wimlib_add_image | ( | WIMStruct * | wim,
|  | const wimlib_tchar * | source,
|  | const wimlib_tchar * | name,
|  | const wimlib_tchar * | config_file,
|  | int | add_flags )

Add an image to a WIMStruct from an on-disk directory tree or NTFS volume.

The directory tree or NTFS volume is scanned immediately to load the dentry tree into memory, and file metadata is read. However, actual file data may not be read until the WIMStruct is persisted to disk using wimlib_write() or wimlib_overwrite().

See the documentation for the wimlib-imagex program for more information about the "normal" capture mode versus the NTFS capture mode (entered by providing the flag WIMLIB_ADD_FLAG_NTFS).

Note that no changes are committed to disk until wimlib_write() or wimlib_overwrite() is called.

Parameters

  wim | Pointer to the WIMStruct to which to add the image.
  source | A path to a directory or unmounted NTFS volume that will be captured as a WIM image.
  name | Name to give the new image. If `NULL` or empty, the new image is given no name. If nonempty, it must specify a name that does not already exist in `wim`.

  config_file

  Path to capture configuration file, or `NULL`. This file may specify, among other things, which files to exclude from capture. See the documentation for wimcapture (–config option) for details of the file format. If `NULL`, the default capture configuration will be used. Ordinarily, the default capture configuration will result in no files being excluded from capture purely based on name; however, the WIMLIB_ADD_FLAG_WINCONFIG and WIMLIB_ADD_FLAG_WIMBOOT flags modify the default.

  add_flags | Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG.

Returns
  0 on success; a wimlib_error_code value on failure.

This function is implemented by calling wimlib_add_empty_image(), then calling wimlib_update_image() with a single "add" command, so any error code returned by wimlib_add_empty_image() may be returned, as well as any error codes returned by wimlib_update_image() other than ones documented as only being returned specifically by an update involving delete or rename commands.

If a progress function is registered with `wim`, then it will receive the messages WIMLIB_PROGRESS_MSG_SCAN_BEGIN and WIMLIB_PROGRESS_MSG_SCAN_END. In addition, if WIMLIB_ADD_FLAG_VERBOSE is specified in `add_flags`, it will receive WIMLIB_PROGRESS_MSG_SCAN_DENTRY.

## wimlib_add_image_multisource()

WIMLIBAPI int wimlib_add_image_multisource | ( | WIMStruct * | wim,
|  | const struct wimlib_capture_source * | sources,
|  | size_t | num_sources,
|  | const wimlib_tchar * | name,
|  | const wimlib_tchar * | config_file,
|  | int | add_flags )

This function is equivalent to wimlib_add_image() except it allows for multiple sources to be combined into a single WIM image.

This is done by specifying the `sources` and `num_sources` parameters instead of the `source` parameter of wimlib_add_image(). The rest of the parameters are the same as wimlib_add_image(). See the documentation for wimcapture for full details on how this mode works.

## wimlib_add_tree()

WIMLIBAPI int wimlib_add_tree | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | fs_source_path,
|  | const wimlib_tchar * | wim_target_path,
|  | int | add_flags )

Add the file or directory tree at `fs_source_path` on the filesystem to the location `wim_target_path` within the specified `image` of the `wim`.

This just builds an appropriate wimlib_add_command and passes it to wimlib_update_image().

## wimlib_delete_image()

WIMLIBAPI int wimlib_delete_image | ( | WIMStruct * | wim,
|  | int | image )

Delete an image, or all images, from a WIMStruct.

Note that no changes are committed to disk until wimlib_write() or wimlib_overwrite() is called.

Parameters

  wim | Pointer to the WIMStruct from which to delete the image.
  image | The 1-based index of the image to delete, or WIMLIB_ALL_IMAGES to delete all images.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_INVALID_IMAGE | `image` does not exist in the WIM.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, 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 deleted.

If this function fails when `image` was WIMLIB_ALL_IMAGES, then it's possible that some but not all of the images were deleted.

## wimlib_delete_path()

WIMLIBAPI int wimlib_delete_path | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | path,
|  | int | delete_flags )

Delete the `path` from the specified `image` of the `wim`.

This just builds an appropriate wimlib_delete_command and passes it to wimlib_update_image().

## wimlib_export_image()

WIMLIBAPI int wimlib_export_image | ( | WIMStruct * | src_wim,
|  | int | src_image,
|  | WIMStruct * | dest_wim,
|  | const wimlib_tchar * | dest_name,
|  | const wimlib_tchar * | dest_description,
|  | int | export_flags )

Export an image, or all images, from a WIMStruct into another WIMStruct.

Specifically, if the destination WIMStruct contains n images, then the source image(s) will be appended, in order, starting at destination index n + 1. By default, all image metadata will be exported verbatim, but certain changes can be made by passing appropriate parameters.

wimlib_export_image() is only an in-memory operation; no changes are committed to disk until wimlib_write() or wimlib_overwrite() is called.

A limitation of the current implementation of wimlib_export_image() is that the directory tree of a source or destination image cannot be updated following an export until one of the two images has been freed from memory.

Parameters

  src_wim | The WIM from which to export the images, 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().
  src_image | The 1-based index of the image from `src_wim` to export, or WIMLIB_ALL_IMAGES.
  dest_wim | The WIMStruct to which to export the images.
  dest_name | For single-image exports, the name to give the exported image in `dest_wim`. If left `NULL`, the name from `src_wim` is used. For WIMLIB_ALL_IMAGES exports, this parameter must be left `NULL`; in that case, the names are all taken from `src_wim`. This parameter is overridden by WIMLIB_EXPORT_FLAG_NO_NAMES.
  dest_description | For single-image exports, the description to give the exported image in the new WIM file. If left `NULL`, the description from `src_wim` is used. For WIMLIB_ALL_IMAGES exports, this parameter must be left `NULL`; in that case, the description are all taken from `src_wim`. This parameter is overridden by WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS.
  export_flags | Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE | One or more of the source images had already been exported into the destination WIM.
  WIMLIB_ERR_IMAGE_NAME_COLLISION | One or more of the names being given to an exported image was already in use in the destination WIM.
  WIMLIB_ERR_INVALID_IMAGE | `src_image` does not exist in `src_wim`.
  WIMLIB_ERR_METADATA_NOT_FOUND | At least one of `src_wim` and `dest_wim` does not contain image metadata; for example, one of them represents a non-first part of a split WIM.
  WIMLIB_ERR_RESOURCE_NOT_FOUND | A file data blob that needed to be exported could not be found in the blob lookup table of `src_wim`. See Creating and handling non-standalone WIMs.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, 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 in `src_wim` that needed to be exported.

## wimlib_reference_template_image()

WIMLIBAPI int wimlib_reference_template_image | ( | WIMStruct * | wim,
|  | int | new_image,
|  | WIMStruct * | template_wim,
|  | int | template_image,
|  | int | flags )

Declare that a newly added image is mostly the same as a prior image, but captured at a later point in time, possibly with some modifications in the intervening time.

This is designed to be used in incremental backups of the same filesystem or directory tree.

This function compares the metadata of the directory tree of the newly added image against that of the old image. Any files that are present in both the newly added image and the old image and have timestamps that indicate they haven't been modified are deemed not to have been modified and have their checksums copied from the old image. Because of this and because WIM uses single-instance streams, such files need not be read from the filesystem when the WIM is being written or overwritten. Note that these unchanged files will still be "archived" and will be logically present in the new image; the optimization is that they don't need to actually be read from the filesystem because the WIM already contains them.

This function is provided to optimize incremental backups. The resulting WIM file will still be the same regardless of whether this function is called. (This is, however, assuming that timestamps have not been manipulated or unmaintained as to trick this function into thinking a file has not been modified when really it has. To partly guard against such cases, other metadata such as file sizes will be checked as well.)

This function must be called after adding the new image (e.g. with wimlib_add_image()), but before writing the updated WIM file (e.g. with wimlib_overwrite()).

Parameters

  wim | Pointer to the WIMStruct containing the newly added image.
  new_image | The 1-based index in `wim` of the newly added image.
  template_wim | Pointer to the WIMStruct containing the template image. This can be, but does not have to be, the same WIMStruct as `wim`.
  template_image | The 1-based index in `template_wim` of the template image.
  flags | Reserved; must be 0.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_INVALID_IMAGE | `new_image` does not exist in `wim` or `template_image` does not exist in `template_wim`.
  WIMLIB_ERR_METADATA_NOT_FOUND | At least one of `wim` and `template_wim` does not contain image metadata; for example, one of them represents a non-first part of a split WIM.
  WIMLIB_ERR_INVALID_PARAM | Identical values were provided for the template and new image; or `new_image` specified an image that had not been modified since opening the WIM.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, WIMLIB_ERR_READ, or WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for different reasons) to read the metadata resource for the template image.

## wimlib_rename_path()

WIMLIBAPI int wimlib_rename_path | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | source_path,
|  | const wimlib_tchar * | dest_path )

Rename the `source_path` to the `dest_path` in the specified `image` of the `wim`.

This just builds an appropriate wimlib_rename_command and passes it to wimlib_update_image().

## wimlib_set_image_descripton()

WIMLIBAPI int wimlib_set_image_descripton | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | description )

Change the description of a WIM image.

Equivalent to wimlib_set_image_property(wim, image, "DESCRIPTION", description).

Note that "description" is misspelled in the name of this function.

## wimlib_set_image_flags()

WIMLIBAPI int wimlib_set_image_flags | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | flags )

Change what is stored in the <FLAGS> element in the WIM XML document (usually something like "Core" or "Ultimate").

Equivalent to wimlib_set_image_property(wim, image, "FLAGS", flags).

## wimlib_set_image_name()

WIMLIBAPI int wimlib_set_image_name | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | name )

Change the name of a WIM image.

Equivalent to wimlib_set_image_property(wim, image, "NAME", name).

## wimlib_set_image_property()

WIMLIBAPI int wimlib_set_image_property | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | property_name,
|  | const wimlib_tchar * | property_value )

Since wimlib v1.8.3: add, modify, or remove a per-image property from the WIM's XML document.

This is an alternative to wimlib_set_image_name(), wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows manipulating any simple string property.

Parameters

  wim | Pointer to the WIMStruct for the WIM.
  image | The 1-based index of the image for which to set the property.

  property_name

  The name of the image property in the same format documented for wimlib_get_image_property().
  Note: if creating a new element using a bracketed index such as "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified is one greater than the number of existing elements with that same name, excluding the index. That means that if you are adding a list of new elements, they must be added sequentially from the first index (1) to the last index (n).

  property_value | If not NULL and not empty, the property is set to this value. Otherwise, the property is removed from the XML document.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_IMAGE_NAME_COLLISION | The user requested to set the image name (the NAME property), but another image in the WIM already had the requested name.
  WIMLIB_ERR_INVALID_IMAGE | `image` does not exist in `wim`.
  WIMLIB_ERR_INVALID_PARAM | `property_name` has an unsupported format, or `property_name` included a bracketed index that was too high.

## wimlib_set_wim_info()

WIMLIBAPI int wimlib_set_wim_info | ( | WIMStruct * | wim,
|  | const struct wimlib_wim_info * | info,
|  | int | which )

Set basic information about a WIM.

Parameters

  wim | Pointer to the WIMStruct for a WIM.
  info | Pointer to a wimlib_wim_info structure that contains the information to set. Only the information explicitly specified in the `which` flags need be valid.
  which | Flags that specify which information to set. This is a bitwise OR of WIMLIB_CHANGE_READONLY_FLAG, WIMLIB_CHANGE_GUID, WIMLIB_CHANGE_BOOT_INDEX, and/or WIMLIB_CHANGE_RPFIX_FLAG.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_IMAGE_COUNT | WIMLIB_CHANGE_BOOT_INDEX was specified, but wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image index in the WIM.

## wimlib_update_image()

WIMLIBAPI int wimlib_update_image | ( | WIMStruct * | wim,
|  | int | image,
|  | const struct wimlib_update_command * | cmds,
|  | size_t | num_cmds,
|  | int | update_flags )

Update a WIM image by adding, deleting, and/or renaming files or directories.

Parameters

  wim | Pointer to the WIMStruct containing the image to update.
  image | The 1-based index of the image to update.
  cmds | An array of wimlib_update_command's that specify the update operations to perform.
  num_cmds | Number of commands in `cmds`.
  update_flags | WIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0.

Returns
  0 on success; a wimlib_error_code value on failure. On failure, all update commands will be rolled back, and no visible changes will have been made to `wim`.

Return values

  WIMLIB_ERR_FVE_LOCKED_VOLUME | Windows-only: One of the "add" commands attempted to add files from an encrypted BitLocker volume that hasn't yet been unlocked.
  WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES | There are currently multiple references to the image as a result of a call to wimlib_export_image(). Free one before attempting the update.
  WIMLIB_ERR_INVALID_CAPTURE_CONFIG | The contents of a capture configuration file were invalid.
  WIMLIB_ERR_INVALID_IMAGE | `image` did not exist in `wim`.
  WIMLIB_ERR_INVALID_OVERLAY | An add command with WIMLIB_ADD_FLAG_NO_REPLACE specified attempted to replace an existing nondirectory file.
  WIMLIB_ERR_INVALID_PARAM | An unknown operation type was provided in the update commands; or unknown or incompatible flags were provided in a flags parameter; or there was another problem with the provided parameters.
  WIMLIB_ERR_INVALID_REPARSE_DATA | While executing an add command, a reparse point had invalid data.
  WIMLIB_ERR_IS_DIRECTORY | An add command attempted to replace a directory with a non-directory; or a delete command without WIMLIB_DELETE_FLAG_RECURSIVE attempted to delete a directory; or a rename command attempted to rename a directory to a non-directory.
  WIMLIB_ERR_NOTDIR | An add command attempted to replace a non-directory with a directory; or an add command attempted to set the root of the image to a non-directory; or a rename command attempted to rename a directory to a non-directory; or a component of an image path that was used as a directory was not, in fact, a directory.
  WIMLIB_ERR_NOTEMPTY | A rename command attempted to rename a directory to a non-empty directory; or a rename command would have created a loop.
  WIMLIB_ERR_NTFS_3G | While executing an add command with WIMLIB_ADD_FLAG_NTFS specified, an error occurred while reading data from the NTFS volume using libntfs-3g.
  WIMLIB_ERR_OPEN | Failed to open a file to be captured while executing an add command.
  WIMLIB_ERR_OPENDIR | Failed to open a directory to be captured while executing an add command.
  WIMLIB_ERR_PATH_DOES_NOT_EXIST | A delete command without WIMLIB_DELETE_FLAG_FORCE specified was for a WIM path that did not exist; or a rename command attempted to rename a file that does not exist.
  WIMLIB_ERR_READ | While executing an add command, failed to read data from a file or directory to be captured.
  WIMLIB_ERR_READLINK | While executing an add command, failed to read the target of a symbolic link, junction, or other reparse point.
  WIMLIB_ERR_STAT | While executing an add command, failed to read metadata for a file or directory.
  WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG | A capture configuration file could not be read.
  WIMLIB_ERR_UNSUPPORTED | A command had flags provided that are not supported on this platform or in this build of the library.
  WIMLIB_ERR_UNSUPPORTED_FILE | An add command with WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified discovered a file that was not of a supported type.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, 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 updated.