wimlib
Macros | Functions
Creating and Opening WIMs

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

Macros

#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY   0x00000001
 Verify the WIM contents against the WIM's integrity table, if present. More...
 
#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. More...
 
#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. More...
 

Functions

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

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

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
ctypeThe "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_retOn success, a pointer to the new WIMStruct is written to the memory location pointed to by this parameter. This WIMStruct must be freed using using wimlib_free() when finished with it.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_COMPRESSION_TYPEctype was not a supported compression type.
WIMLIB_ERR_NOMEMInsufficient memory to allocate a new WIMStruct.

◆ wimlib_open_wim()

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_fileThe path to the WIM file to open.
open_flagsBitwise OR of flags prefixed with WIMLIB_OPEN_FLAG.
wim_retOn 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 using wimlib_free() when finished with it.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_IMAGE_COUNTThe 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_INTEGRITYWIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in open_flags, and the WIM file failed the integrity check.
WIMLIB_ERR_INVALID_CHUNK_SIZEThe library did not recognize the compression chunk size of the WIM as valid for its compression type.
WIMLIB_ERR_INVALID_COMPRESSION_TYPEThe library did not recognize the compression type of the WIM.
WIMLIB_ERR_INVALID_HEADERThe header of the WIM was otherwise invalid.
WIMLIB_ERR_INVALID_INTEGRITY_TABLEWIMLIB_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_ENTRYThe lookup table of the WIM was invalid.
WIMLIB_ERR_INVALID_PARAMwim_ret was NULL; or, wim_file was not a nonempty string.
WIMLIB_ERR_IS_SPLIT_WIMThe WIM was a split WIM and WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was specified in open_flags.
WIMLIB_ERR_NOT_A_WIM_FILEThe file did not begin with the magic characters that identify a WIM file.
WIMLIB_ERR_OPENFailed 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_READFailed to read data from the WIM file.
WIMLIB_ERR_UNEXPECTED_END_OF_FILEUnexpected end-of-file while reading data from the WIM file.
WIMLIB_ERR_UNKNOWN_VERSIONThe WIM version number was not recognized. (May be a pre-Vista WIM.)
WIMLIB_ERR_WIM_IS_ENCRYPTEDThe WIM cannot be opened because it contains encrypted segments. (It may be a Windows 8 "ESD" file.)
WIMLIB_ERR_WIM_IS_INCOMPLETEThe WIM file is not complete (e.g. the program which wrote it was terminated before it finished)
WIMLIB_ERR_WIM_IS_READONLYWIMLIB_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_XMLThe XML data of the WIM was invalid.

◆ wimlib_open_wim_with_progress()

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.