Modifying WIMs

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);

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_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.