Loading...
Searching...
No Matches
Retrieving WIM information and directory listings

Retrieve information about a WIM or WIM image. More...

## Data Structures

struct | wimlib_wim_info
| General information about a WIM file. More...
struct | wimlib_resource_entry
| Information about a "blob", which is a fixed length sequence of binary data. More...
struct | wimlib_stream_entry
| Information about a stream of a particular file in the WIM. More...
struct | wimlib_object_id
| Since wimlib v1.9.1: an object ID, which is an extra piece of metadata that may be associated with a file on NTFS filesystems. More...
struct | wimlib_dir_entry
| Structure passed to the wimlib_iterate_dir_tree() callback function. More...

## Macros

#define | WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001
| For wimlib_iterate_dir_tree(): Iterate recursively on children rather than just on the specified path.
#define | WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002
| For wimlib_iterate_dir_tree(): Don't iterate on the file or directory itself; only its children (in the case of a non-empty directory).
#define | WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED 0x00000004
| Return WIMLIB_ERR_RESOURCE_NOT_FOUND if any file data blobs needed to fill in the wimlib_resource_entry's for the iteration cannot be found in the blob lookup table of the WIMStruct.

## Typedefs

typedef int(* | wimlib_iterate_dir_tree_callback_t) (const struct wimlib_dir_entry *dentry, void *user_ctx)
| Type of a callback function to wimlib_iterate_dir_tree().
typedef int(* | wimlib_iterate_lookup_table_callback_t) (const struct wimlib_resource_entry *resource, void *user_ctx)
| Type of a callback function to wimlib_iterate_lookup_table().

## Functions

WIMLIBAPI int | wimlib_extract_xml_data (WIMStruct *wim, FILE *fp)
| Similar to wimlib_get_xml_data(), but the XML document will be written to the specified standard C `FILE*` instead of retrieved in an in-memory buffer.
WIMLIBAPI const wimlib_tchar * | wimlib_get_image_description (const WIMStruct *wim, int image)
| Get the description of the specified image.
WIMLIBAPI const wimlib_tchar * | wimlib_get_image_name (const WIMStruct *wim, int image)
| Get the name of the specified image.
WIMLIBAPI const wimlib_tchar * | wimlib_get_image_property (const WIMStruct *wim, int image, const wimlib_tchar *property_name)
| Since wimlib v1.8.3: get a per-image property from the WIM's XML document.
WIMLIBAPI int | wimlib_get_wim_info (WIMStruct *wim, struct wimlib_wim_info *info)
| Get basic information about a WIM file.
WIMLIBAPI int | wimlib_get_xml_data (WIMStruct *wim, void **buf_ret, size_t *bufsize_ret)
| Read a WIM file's XML document into an in-memory buffer.
WIMLIBAPI bool | wimlib_image_name_in_use (const WIMStruct *wim, const wimlib_tchar *name)
| Determine if an image name is already used by some image in the WIM.
WIMLIBAPI int | wimlib_iterate_dir_tree (WIMStruct *wim, int image, const wimlib_tchar *path, int flags, wimlib_iterate_dir_tree_callback_t cb, void *user_ctx)
| Iterate through a file or directory tree in a WIM image.
WIMLIBAPI int | wimlib_iterate_lookup_table (WIMStruct *wim, int flags, wimlib_iterate_lookup_table_callback_t cb, void *user_ctx)
| Iterate through the blob lookup table of a WIMStruct.
WIMLIBAPI void | wimlib_print_available_images (const WIMStruct *wim, int image)
| (Deprecated) Print information about one image, or all images, contained in a WIM.
WIMLIBAPI void | wimlib_print_header (const WIMStruct *wim)
| Print the header of the WIM file (intended for debugging only).
WIMLIBAPI int | wimlib_resolve_image (WIMStruct *wim, const wimlib_tchar *image_name_or_num)
| Translate a string specifying the name or number of an image in the WIM into the number of the image.

## Detailed Description

Retrieve information about a WIM or WIM image.

## Macro Definition Documentation

## WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE

#define WIMLIB_ITERATE_DIR_TREE_FLAG_RECURSIVE 0x00000001

For wimlib_iterate_dir_tree(): Iterate recursively on children rather than just on the specified path.

## WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN

#define WIMLIB_ITERATE_DIR_TREE_FLAG_CHILDREN 0x00000002

For wimlib_iterate_dir_tree(): Don't iterate on the file or directory itself; only its children (in the case of a non-empty directory).

## WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED

#define WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED 0x00000004

Return WIMLIB_ERR_RESOURCE_NOT_FOUND if any file data blobs needed to fill in the wimlib_resource_entry's for the iteration cannot be found in the blob lookup table of the WIMStruct.

The default behavior without this flag is to fill in the sha1_hash and set the is_missing flag.

## Typedef Documentation

## wimlib_iterate_dir_tree_callback_t

typedef int(* wimlib_iterate_dir_tree_callback_t) (const struct wimlib_dir_entry *dentry, void *user_ctx)

Type of a callback function to wimlib_iterate_dir_tree().

Must return 0 on success.

## wimlib_iterate_lookup_table_callback_t

typedef int(* wimlib_iterate_lookup_table_callback_t) (const struct wimlib_resource_entry *resource, void *user_ctx)

Type of a callback function to wimlib_iterate_lookup_table().

Must return 0 on success.

## Function Documentation

## wimlib_extract_xml_data()

WIMLIBAPI int wimlib_extract_xml_data | ( | WIMStruct * | wim,
|  | FILE * | fp )

Similar to wimlib_get_xml_data(), but the XML document will be written to the specified standard C `FILE*` instead of retrieved in an in-memory buffer.

Returns
  0 on success; a wimlib_error_code value on failure. This may return any error code which can be returned by wimlib_get_xml_data() as well as the following error codes:

Return values

  WIMLIB_ERR_WRITE | Failed to write the data to the requested file.

## wimlib_get_image_description()

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

Get the description of the specified image.

Equivalent to wimlib_get_image_property(wim, image, "DESCRIPTION").

## wimlib_get_image_name()

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

Get the name of the specified image.

Equivalent to wimlib_get_image_property(wim, image, "NAME"), except that wimlib_get_image_name() will return an empty string if the image is unnamed whereas wimlib_get_image_property() may return `NULL` in that case.

## wimlib_get_image_property()

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

Since wimlib v1.8.3: get a per-image property from the WIM's XML document.

This is an alternative to wimlib_get_image_name() and wimlib_get_image_description() which allows getting any simple string property.

Parameters

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

  property_name

  The name of the image property, for example "NAME", "DESCRIPTION", or "TOTALBYTES". The name can contain forward slashes to indicate a nested XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD element nested within the VERSION element nested within the WINDOWS element. Since wimlib v1.9.0, a bracketed number can be used to indicate one of several identically-named elements; for example, "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element nested within the "WINDOWS/LANGUAGES" element. Note that element names are case sensitive.

Returns
  The property's value as a wimlib_tchar string, or `NULL` if there is no such property. The string may not remain valid after later library calls, so the caller should duplicate it if needed.

## wimlib_get_wim_info()

WIMLIBAPI int wimlib_get_wim_info | ( | WIMStruct * | wim,
|  | struct wimlib_wim_info * | info )

Get basic information about a WIM file.

Parameters

  wim | Pointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
  info | A wimlib_wim_info structure that will be filled in with information about the WIM file.

Returns
  0

## wimlib_get_xml_data()

WIMLIBAPI int wimlib_get_xml_data | ( | WIMStruct * | wim,
|  | void ** | buf_ret,
|  | size_t * | bufsize_ret )

Read a WIM file's XML document into an in-memory buffer.

The XML document contains metadata about the WIM file and the images stored in it.

Parameters

  wim | Pointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
  buf_ret | On success, a pointer to an allocated buffer containing the raw UTF16-LE XML document is written to this location.
  bufsize_ret | The size of the XML document in bytes is written to this location.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_NO_FILENAME | `wim` is not backed by a file and therefore does not have an XML document.
  WIMLIB_ERR_READ | Failed to read the XML document from the WIM file.
  WIMLIB_ERR_UNEXPECTED_END_OF_FILE | Failed to read the XML document from the WIM file.

## wimlib_image_name_in_use()

WIMLIBAPI bool wimlib_image_name_in_use | ( | const WIMStruct * | wim,
|  | const wimlib_tchar * | name )

Determine if an image name is already used by some image in the WIM.

Parameters

  wim | Pointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
  name | The name to check.

Returns
  `true` if there is already an image in `wim` named `name`; `false` if there is no image named `name` in `wim`. If `name` is `NULL` or the empty string, then `false` is returned.

## wimlib_iterate_dir_tree()

WIMLIBAPI int wimlib_iterate_dir_tree | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | path,
|  | int | flags,
|  | wimlib_iterate_dir_tree_callback_t | cb,
|  | void * | user_ctx )

Iterate through a file or directory tree in a WIM image.

By specifying appropriate flags and a callback function, you can get the attributes of a file in the image, get a directory listing, or even get a listing of the entire image.

Parameters

  wim | The WIMStruct containing the image(s) over which to iterate. This WIMStruct must contain image metadata, so it cannot be the non-first part of a split WIM (for example).
  image | The 1-based index of the image that contains the files or directories to iterate over, or WIMLIB_ALL_IMAGES to iterate over all images.
  path | Path in the image at which to do the iteration.
  flags | Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG.
  cb | A callback function that will receive each directory entry.
  user_ctx | An extra parameter that will always be passed to the callback function `cb`.

Returns
  Normally, returns 0 if all calls to `cb` returned 0; otherwise the first nonzero value that was returned from `cb`. However, additional wimlib_error_code values may be returned, including the following:

Return values

  WIMLIB_ERR_INVALID_IMAGE | `image` does not exist in `wim`.
  WIMLIB_ERR_PATH_DOES_NOT_EXIST | `path` does not exist in the image.
  WIMLIB_ERR_RESOURCE_NOT_FOUND | WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED was specified, but the data for some files could not be found in the blob lookup table of `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 over which iteration needed to be done.

## wimlib_iterate_lookup_table()

WIMLIBAPI int wimlib_iterate_lookup_table | ( | WIMStruct * | wim,
|  | int | flags,
|  | wimlib_iterate_lookup_table_callback_t | cb,
|  | void * | user_ctx )

Iterate through the blob lookup table of a WIMStruct.

This can be used to directly get a listing of the unique "blobs" contained in a WIM file, which are deduplicated over all images.

Specifically, each listed blob may be from any of the following sources:

- Metadata blobs, if the WIMStruct contains image metadata
- File blobs from the on-disk WIM file (if any) backing the WIMStruct
- File blobs from files that have been added to the in-memory WIMStruct, e.g. by using wimlib_add_image()
- File blobs from external WIMs referenced by wimlib_reference_resource_files() or wimlib_reference_resources()

Parameters

  wim | Pointer to the WIMStruct for which to get the blob listing.
  flags | Reserved; set to 0.
  cb | A callback function that will receive each blob.
  user_ctx | An extra parameter that will always be passed to the callback function `cb`.

Returns
  0 if all calls to `cb` returned 0; otherwise the first nonzero value that was returned from `cb`.

## wimlib_print_available_images()

WIMLIBAPI void wimlib_print_available_images | ( | const WIMStruct * | wim,
|  | int | image )

(Deprecated) Print information about one image, or all images, contained in a WIM.

Parameters

  wim | Pointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
  image | The 1-based index of the image for which to print information, or WIMLIB_ALL_IMAGES to print information about all images.

Returns
  This function has no return value. No error checking is done when printing the information. If `image` is invalid, an error message is printed.

This function is deprecated; use wimlib_get_xml_data() or wimlib_get_image_property() to query image information instead.

## wimlib_print_header()

WIMLIBAPI void wimlib_print_header | ( | const WIMStruct * | wim | ) |

Print the header of the WIM file (intended for debugging only).

## wimlib_resolve_image()

WIMLIBAPI int wimlib_resolve_image | ( | WIMStruct * | wim,
|  | const wimlib_tchar * | image_name_or_num )

Translate a string specifying the name or number of an image in the WIM into the number of the image.

The images are numbered starting at 1.

Parameters

  wim | Pointer to the WIMStruct for a WIM.

  image_name_or_num

  A string specifying the name or number of an image in the WIM. If it parses to a positive integer, this integer is taken to specify the number of the image, indexed starting at 1. Otherwise, it is taken to be the name of an image, as given in the XML data for the WIM file. It also may be the keyword "all" or the string "*", both of which will resolve to WIMLIB_ALL_IMAGES.
  There is no way to search for an image actually named "all", "*", or an integer number, or an image that has no name. However, you can use wimlib_get_image_name() to get the name of any image.

Returns
  If the string resolved to a single existing image, the number of that image, indexed starting at 1, is returned. If the keyword "all" or "*" was specified, WIMLIB_ALL_IMAGES is returned. Otherwise, WIMLIB_NO_IMAGE is returned. If `image_name_or_num` was `NULL` or the empty string, WIMLIB_NO_IMAGE is returned, even if one or more images in `wim` has no name. (Since a WIM may have multiple unnamed images, an unnamed image must be specified by index to eliminate the ambiguity.)