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