Macros
#define	WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001
	Verify the WIM contents against the WIM's integrity table, if present.

#define	WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002
	Issue an error (WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split WIM.

#define	WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
	Check if the WIM is writable and issue an error (WIMLIB_ERR_WIM_IS_READONLY) if it is not.

Functions
WIMLIBAPI int	wimlib_create_new_wim (enum wimlib_compression_type ctype, WIMStruct **wim_ret)
	Create a WIMStruct which initially contains no images and is not backed by an on-disk file.

WIMLIBAPI int	wimlib_open_wim (const wimlib_tchar wim_file, int open_flags, WIMStruct *wim_ret)
	Open a WIM file and create a WIMStruct for it.

WIMLIBAPI int	wimlib_open_wim_with_progress (const wimlib_tchar wim_file, int open_flags, WIMStruct wim_ret, wimlib_progress_func_t progfunc, void progctx)
	Same as wimlib_open_wim(), but allows specifying a progress function and progress context.

Detailed Description

Open an existing WIM file as a WIMStruct, or create a new WIMStruct which can be used to create a new WIM file.

Macro Definition Documentation

◆ WIMLIB_OPEN_FLAG_CHECK_INTEGRITY

#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001

Verify the WIM contents against the WIM's integrity table, if present.

The integrity table stores checksums for the raw data of the WIM file, divided into fixed size chunks. Verification will compute checksums and compare them with the stored values. If there are any mismatches, then WIMLIB_ERR_INTEGRITY will be issued. If the WIM file does not contain an integrity table, then this flag has no effect.

◆ WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT

#define WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002

Issue an error (WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split WIM.

Software can provide this flag for convenience if it explicitly does not want to support split WIMs.

◆ WIMLIB_OPEN_FLAG_WRITE_ACCESS

#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004

Check if the WIM is writable and issue an error (WIMLIB_ERR_WIM_IS_READONLY) if it is not.

A WIM is considered writable only if it is writable at the filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned set. It is not required to provide this flag before attempting to make changes to the WIM, but with this flag you get an error immediately rather than potentially much later, when wimlib_overwrite() is finally called.

Function Documentation

◆ wimlib_create_new_wim()

WIMLIBAPI int wimlib_create_new_wim	(	enum wimlib_compression_type	ctype,
		WIMStruct **	wim_ret )

Create a WIMStruct which initially contains no images and is not backed by an on-disk file.

Parameters

ctype The "output compression type" to assign to the WIMStruct. This is the compression type that will be used if the WIMStruct is later persisted to an on-disk file using wimlib_write().
This choice is not necessarily final. If desired, it can still be changed at any time before wimlib_write() is called, using wimlib_set_output_compression_type(). In addition, if you wish to use a non-default compression chunk size, then you will need to call wimlib_set_output_chunk_size().

wim_ret On success, a pointer to the new WIMStruct is written to the memory location pointed to by this parameter. This WIMStruct must be freed using wimlib_free() when finished with it.

Returns: 0 on success; a wimlib_error_code value on failure.

Return values

WIMLIB_ERR_INVALID_COMPRESSION_TYPE	`ctype` was not a supported compression type.
WIMLIB_ERR_NOMEM	Insufficient memory to allocate a new WIMStruct.

◆ wimlib_open_wim()

WIMLIBAPI int wimlib_open_wim	(	const wimlib_tchar *	wim_file,
		int	open_flags,
		WIMStruct **	wim_ret )

Open a WIM file and create a WIMStruct for it.

Parameters

wim_file	The path to the WIM file to open.
open_flags	Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG.
wim_ret	On success, a pointer to a new WIMStruct backed by the specified on-disk WIM file is written to the memory location pointed to by this parameter. This WIMStruct must be freed using wimlib_free() when finished with it.

Returns: 0 on success; a wimlib_error_code value on failure.

Return values

WIMLIB_ERR_IMAGE_COUNT	The number of metadata resources found in the WIM did not match the image count specified in the WIM header, or the number of <IMAGE> elements in the XML data of the WIM did not match the image count specified in the WIM header.
WIMLIB_ERR_INTEGRITY	WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in `open_flags`, and the WIM file failed the integrity check.
WIMLIB_ERR_INVALID_CHUNK_SIZE	The library did not recognize the compression chunk size of the WIM as valid for its compression type.
WIMLIB_ERR_INVALID_COMPRESSION_TYPE	The library did not recognize the compression type of the WIM.
WIMLIB_ERR_INVALID_HEADER	The header of the WIM was otherwise invalid.
WIMLIB_ERR_INVALID_INTEGRITY_TABLE	WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in `open_flags` and the WIM contained an integrity table, but the integrity table was invalid.
WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY	The lookup table of the WIM was invalid.
WIMLIB_ERR_INVALID_PARAM	`wim_ret` was `NULL`; or, `wim_file` was not a nonempty string.
WIMLIB_ERR_IS_SPLIT_WIM	The WIM was a split WIM and WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was specified in `open_flags`.
WIMLIB_ERR_NOT_A_WIM_FILE	The file did not begin with the magic characters that identify a WIM file.
WIMLIB_ERR_OPEN	Failed to open the WIM file for reading. Some possible reasons: the WIM file does not exist, or the calling process does not have permission to open it.
WIMLIB_ERR_READ	Failed to read data from the WIM file.
WIMLIB_ERR_UNEXPECTED_END_OF_FILE	Unexpected end-of-file while reading data from the WIM file.
WIMLIB_ERR_UNKNOWN_VERSION	The WIM version number was not recognized. (May be a pre-Vista WIM.)
WIMLIB_ERR_WIM_IS_ENCRYPTED	The WIM cannot be opened because it contains encrypted segments. (It may be a Windows 8 "ESD" file.)
WIMLIB_ERR_WIM_IS_INCOMPLETE	The WIM file is not complete (e.g. the program which wrote it was terminated before it finished)
WIMLIB_ERR_WIM_IS_READONLY	WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was considered read-only because of any of the reasons mentioned in the documentation for the WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
WIMLIB_ERR_XML	The XML data of the WIM was invalid.

◆ wimlib_open_wim_with_progress()

WIMLIBAPI int wimlib_open_wim_with_progress	(	const wimlib_tchar *	wim_file,
		int	open_flags,
		WIMStruct **	wim_ret,
		wimlib_progress_func_t	progfunc,
		void *	progctx )

Same as wimlib_open_wim(), but allows specifying a progress function and progress context.

If successful, the progress function will be registered in the newly open WIMStruct, as if by an automatic call to wimlib_register_progress_function(). In addition, if WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in open_flags, then the progress function will receive WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages while checking the WIM file's integrity.

Macros

Functions