Crate wimlib

Source
Expand description

§wimlib

These are wimlib Rust bindings. wimlib is a C library for creating, modifying, extracting and mounting files in the Windows Imaging Format (WIM files). It provides a free and corss-platform alternative to Microsoft’s WIMGAPI, ImageX and DISM.

C library link: https://wimlib.net

§Basic WIM handling concepts

Wimlib bindings wrap up a WIM file in a opaque Wim type. There are two ways to create its instance

  1. WimLib::open_wim opens an on-disk WIM file and creates a Wim for it
  2. WimLib::create_new_wim creates a new Wim that initially contains no images and does not yet have a backing on-disk file

Wim contains zero or more independent directory trees called images. Images may be extracted, added, deleted, exported, and updated using various API functions. You can select these images using Wim::select_image and Wim::select_all_images as most of methods using them are under structure Image.

Changes made to a WIM represented by a Wim have no persistent effect until the WIM is actually written to an on-disk file. This can be done using Image::write, but if the WIM was originally opened using WimLib::open_wim, then Wim::overwrite can be used instead.

wimlib’s API is designed to let you combine functions to accomplish tasks in a flexible way. Here are some example sequences of function calls:

Apply an image from a WIM file, similar to the command-line program wimapply

  1. WimLib::open_wim
  2. Image::extract

Capture an image into a new WIM file, similar to wimcapture:

  1. WimLib::create_new_wim
  2. Wim::add_image
  3. Image::write

Append an image to an existing WIM file, similar to wimappend:

  1. WimLib::open_wim
  2. Wim::add_image
  3. Wim::overwrite

Delete an image from an existing WIM file, similar to wimdelete:

  1. WimLib::open_wim
  2. Image::delete_self
  3. Wim::overwrite

Export an image from one WIM file to another, similar to wimexport:

  1. WimLib::open_wim (on source)
  2. WimLib::open_wim (on destination)
  3. Image::export
  4. Wim::overwrite (on destination)

The API also lets you do things the command-line tools don’t directly allow. For example, you could make multiple changes to a WIM before efficiently committing the changes with just one call to Wim::overwrite. Perhaps you want to both delete an image and add a new one; or perhaps you want to customize an image with Wim::overwrite after adding it. All these use cases are supported by the API.

You can also visit documentation of modules in wim module for detailed documentation of certain scopes.

§Additional information and features

§Mounting WIM images

See Mounting WIM images.

§Progress Messages

See progress::ProgressMsg.

§Non-standalone WIMs

See Creating and handling non-standalone WIMSs.

§Pipable WIMs

wimlib supports a special »pipable« WIM format which unfortunately is not compatible with Microsoft’s software. To create a pipable WIM, call Image::write, Image::write_to_file, or Wim::overwrite with WriteFlags::PIPABLE specified. Pipable WIMs are pipable in both directions, so Image::write_to_file can be used to write a pipable WIM to a pipe, and WimLib::extract_image_from_pipe can be used to apply an image from a pipable WIM. wimlib can also transparently open and operate on pipable WIM s using a seekable file descriptor using the regular function calls (e.g. WimLib::open_wim, Image::extract).

See the documentation for the –pipable flag of wimcapture for more information about pipable WIMs.

§Custom allocation functions

WimLib allows settings custom allocator functions. I would really like to make wimlib bindings support this feature, especially by automatically hooking that to users global allocator, but…

  1. It uses C-style allocation APIs, which are very basic compared to Rusts and inherently incompatible. Rust’s allocation APIs require knowing Layout. which includes alignment. malloc requires only size. For dallocation memory, C’s API is even more basic. Just provide a pointer. No size, no alignment. This can be bypassed by having some fixed alignment and allocating a bit more to store the size information and return shifted pointer. Tried this and it lead me to…

  2. wimlib calls libc’s realpath. That one allocates using libc’s allocation facilities (malloc) but wimlib then deallocates the memory by user provided deallocation function. And as my deallocation trick shifted pointer back to the header and tried to read it, it made Address-san sad (of course it did). I could possibly try to do evil things like catch SIGSEGV and then try again with libc::free. Or somehow hook the library and override libc’s allocation facilities. But I am (at least for now) not willing to risk such fragile solution.

Re-exports§

pub use wimlib_sys as sys;

Modules§

progress
Track the progress of long WIM operations
string
WimLib is made to support both UTF-8 and UTF-16, depending on platform
wim
Most of the interfaces live in here. Manipulating WIMs

Macros§

tstr
Create a new crate::string::TStr from literal

Structs§

AddFlags
Flags related to operations of adding items to the WIM
DeleteFlags
Flags related to operations of deleting items from the WIM
DirEntry
Structure passed to the Image::iterate_dir_tree’s callback function
ExportFlags
Flags related to exporting image to another WIM
ExtractFlags
Flags to configure extraction methods for Image
FileAttributes
File attributes are metadata values stored by the file system on disk and are used by the system and are available to developers via various file I/O APIs. For a list of related APIs and topics, see the See also section.
Image
Selected WIM image
InitFlags
Flags for initialising the library using WimLib::try_init
IterateDirTreeFlags
Flags for Image::iterate_dir_tree
IterateLookupTableFlags
Flags for [Wim::interate_lookup_table]; empty, reserved for future use
LazyStreamEntry
Unresolved stream entry
ObjectId
An object ID, which is an extra piece of metadata that may be associated with a file on NTFS filesystems
OpenFlags
Flags related to WimLib::open_wim
ReferenceFlags
Resource reference flags
ReferenceTemplateImageFlags
Reference template file flags – currently unused
RenameFlags
Item rename flags – currently unused
ResourceEntry
Information about a “blob”, which is a fixed length sequence of binary data
ResourceWimRef
Wim resource reference
SetInfo
Builder for Wim::set_info
SourceTargetPair
Pair of source and target for Wim::add_image_multisource
StreamEntry
Information about a stream of a particular file in the WIM
UpdateCommand
Specification of an update to perform on a WIM image
UpdateFlags
Flags related to updating items in file
Wim
Structure that contains opaque structure reference representing WIM and an optional progress callback pointer.
WimInfo
General information about a WIM file
WimLib
A zero-sized type which guards the resources by counting global refernece counter
WriteFlags
Flags for writing image

Enums§

CompressionType
Specifies a compression type
Error
Possible values of the error code returned by many functions in wimlib
ReparseTag
A unique identifier for a file system filter driver stored within a file’s optional reparse point data that indicates the file system filter driver that performs additional filter-defined processing on a file during I/O operations.
TryInitError
Error returned when tried to initialise WimLib

Constants§

ALL_IMAGES
All images index

Functions§

version
Return the version of wimlib

Type Aliases§

ImageIndex
Index for an image in a WIM