Trait FormatDriverBuilder

Source

pub trait FormatDriverBuilder<S: Storage>: Sized {
    type Format: FormatDriverInstance<Storage = S>;

    const FORMAT: Format;

    // Required methods
    fn new(image: S) -> Self;
    fn new_path<P: AsRef<Path>>(path: P) -> Self;
    fn write(self, writable: bool) -> Self;
    fn storage_open_options(self, options: StorageOpenOptions) -> Self;
    async fn open<G: ImplicitOpenGate<S>>(self, gate: G) -> Result<Self::Format>;
    fn get_image_path(&self) -> Option<PathBuf>;
    fn get_writable(&self) -> bool;
    fn get_storage_open_options(&self) -> Option<&StorageOpenOptions>;

    // Provided method
    fn open_sync<G: ImplicitOpenGate<S>>(self, gate: G) -> Result<Self::Format> { ... }
}

Expand description

Prepares opening an image.

There are common options for all kinds of formats, which are accessible through this trait’s methods, but there are also specialized options that depend on the format itself. Each implementation will also provide such specialized methods, but opening an image should generally not require invoking those methods (i.e. sane defaults should apply).

See Qcow2OpenBuilder for an example implementation.

Required Associated Constants§

Source

const FORMAT: Format

Which format this is.

Required Associated Types§

Source

type Format: FormatDriverInstance<Storage = S>

The format object that this builder will create.

Required Methods§

Source

fn new(image: S) -> Self

Prepare opening the given image.

Source

fn new_path<P: AsRef<Path>>(path: P) -> Self

Prepare opening an image under the given path.

Source

fn write(self, writable: bool) -> Self

Whether the image should be writable or not.

Source

fn storage_open_options(self, options: StorageOpenOptions) -> Self

Set base storage options for opened storage objects.

When opening files (e.g. a backing file, or the path given to FormatDriverBuilder::new_path()), use these options as the basis for opening their respective storage objects.

Any filename in options is ignored, as is writability. Both are overridden case by case as needed.

Source

async fn open<G: ImplicitOpenGate<S>>(self, gate: G) -> Result<Self::Format>

Open the image.

Opens the image according to the options specified in self. If files are to be opened implicitly (e.g. backing files), the corresponding functions in gate will be invoked to do so, which can decide, based on the options, to do so, or not, or modify the options before opening the respective image/file.

To prevent any implicitly referenced objects from being opened, use DenyImplicitOpenGate, to allow all implicitly referenced objects to be opened as referenced, use PermissiveImplicitOpenGate (but note the cautionary note there).

For example:

use imago::file::File;
use imago::qcow2::Qcow2;
use imago::{DenyImplicitOpenGate, FormatDriverBuilder};

// Note we only override the backing file, not a potential external data file.  If the
// image has one, qcow2 would still attempt to open it, but `DenyImplicitOpenGate` would
// prevent that.
let image = Qcow2::<File>::builder_path("/path/to/image.qcow2")
    .backing(None)
    .open(DenyImplicitOpenGate::default())
    .await?;

Source