wimlib
Data Structures | Macros | Typedefs | Functions
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. More...
 
#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) More...
 
#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. More...
 

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

Functions

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. More...
 
const wimlib_tcharwimlib_get_image_description (const WIMStruct *wim, int image)
 Get the description of the specified image. More...
 
const wimlib_tcharwimlib_get_image_name (const WIMStruct *wim, int image)
 Get the name of the specified image. More...
 
const wimlib_tcharwimlib_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. More...
 
int wimlib_get_wim_info (WIMStruct *wim, struct wimlib_wim_info *info)
 Get basic information about a WIM file. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void wimlib_print_available_images (const WIMStruct *wim, int image)
 (Deprecated) Print information about one image, or all images, contained in a WIM. More...
 
void wimlib_print_header (const WIMStruct *wim)
 Print the header of the WIM file (intended for debugging only). More...
 
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. More...
 

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

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_WRITEFailed to write the data to the requested file.

◆ wimlib_get_image_description()

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

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

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
wimPointer to the WIMStruct for the WIM.
imageThe 1-based index of the image for which to get the property.
property_nameThe 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()

int wimlib_get_wim_info ( WIMStruct wim,
struct wimlib_wim_info info 
)

Get basic information about a WIM file.

Parameters
wimPointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
infoA wimlib_wim_info structure that will be filled in with information about the WIM file.
Returns
0

◆ wimlib_get_xml_data()

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
wimPointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
buf_retOn success, a pointer to an allocated buffer containing the raw UTF16-LE XML document is written to this location.
bufsize_retThe 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_FILENAMEwim is not backed by a file and therefore does not have an XML document.
WIMLIB_ERR_READFailed to read the XML document from the WIM file.
WIMLIB_ERR_UNEXPECTED_END_OF_FILEFailed to read the XML document from the WIM file.

◆ wimlib_image_name_in_use()

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
wimPointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
nameThe 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()

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
wimThe 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).
imageThe 1-based index of the image that contains the files or directories to iterate over, or WIMLIB_ALL_IMAGES to iterate over all images.
pathPath in the image at which to do the iteration.
flagsBitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG.
cbA callback function that will receive each directory entry.
user_ctxAn 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_IMAGEimage does not exist in wim.
WIMLIB_ERR_PATH_DOES_NOT_EXISTpath does not exist in the image.
WIMLIB_ERR_RESOURCE_NOT_FOUNDWIMLIB_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()

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:

Parameters
wimPointer to the WIMStruct for which to get the blob listing.
flagsReserved; set to 0.
cbA callback function that will receive each blob.
user_ctxAn 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()

void wimlib_print_available_images ( const WIMStruct wim,
int  image 
)

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

Parameters
wimPointer to the WIMStruct to query. This need not represent a standalone WIM (e.g. it could represent part of a split WIM).
imageThe 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()

void wimlib_print_header ( const WIMStruct wim)

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

◆ wimlib_resolve_image()

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
wimPointer to the WIMStruct for a WIM.
image_name_or_numA 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.)