Struct Vmgs 

pub struct Vmgs { /* private fields */ }

Implementation of the VMGS file format, backed by a generic Disk device.

Implementations

impl Vmgs

pub fn open_from_saved( disk: Disk, state: SavedVmgsState, logger: Option<Arc<dyn VmgsLogger>>, ) -> Self

Construct a Vmgs instance, re-using existing saved-state from an earlier instance.

Safety

open_from_saved does NOT perform ANY validation on the provided state, and will blindly assume that it matches the underlying storage instance!

Callers MUST ensure that the provided state matches the provided storage, and that no external entities have modified storage between the call to save and open_from_saved.

Failing to do so may result in data corruption/loss, read/write failures, encryption errors, etc… (though, notably: it will not result in any memory-unsafety, hence why the function isn’t marked unsafe).

pub fn save(&self) -> SavedVmgsState

Save the in-memory Vmgs file metadata.

This saved state can be used alongside open_from_saved to obtain a new Vmgs instance without needing to invoke any IOs on the underlying storage.

impl Vmgs

pub async fn try_open( disk: Disk, logger: Option<Arc<dyn VmgsLogger>>, format_on_empty: bool, format_on_failure: bool, ) -> Result<Self, Error>

Attempt to open the VMGS file, optionally formatting if it is empty or corrupted.

pub async fn open( disk: Disk, logger: Option<Arc<dyn VmgsLogger>>, ) -> Result<Self, Error>

Open the VMGS file.

pub async fn format_new( disk: Disk, logger: Option<Arc<dyn VmgsLogger>>, ) -> Result<Self, Error>

Format and open a new VMGS file.

pub async fn request_format( disk: Disk, logger: Option<Arc<dyn VmgsLogger>>, ) -> Result<Self, Error>

Format and open a new VMGS file.

pub fn get_file_info(&self, file_id: FileId) -> Result<VmgsFileInfo, Error>

Get allocated and valid bytes from File Control Block for file_id.

When reading data from a file, the buffer must be at least valid_bytes long.

pub async fn read_file(&mut self, file_id: FileId) -> Result<Vec<u8>, Error>

Reads the specified file_id, decrypting its contents.

pub async fn read_file_raw(&mut self, file_id: FileId) -> Result<Vec<u8>, Error>

Reads the specified file_id, but does not decrypt the contents.

pub async fn write_file( &mut self, file_id: FileId, buf: &[u8], ) -> Result<(), Error>

Writes buf to a file_id without encrypting it.

If the file is already encrypted, this will return a failure. Use Self::write_file_allow_overwrite_encrypted if you want to allow this.

To write encrypted data, use write_file_encrypted instead.

pub async fn write_file_allow_overwrite_encrypted( &mut self, file_id: FileId, buf: &[u8], ) -> Result<(), Error>

Writes buf to a file_id without encrypting it, allowing overrites of an already-encrypted file.

pub async fn write_file_encrypted( &mut self, file_id: FileId, buf: &[u8], ) -> Result<(), Error>

Encrypts buf and writes the encrypted payload to a file_id if the VMGS file has encryption configured. If the VMGS doesn’t have encryption configured, will do a plaintext write instead.

pub async fn unlock_with_encryption_key( &mut self, encryption_key: &[u8], ) -> Result<(), Error>

Decrypts the extended file table by the encryption_key and updates the related metadata in memory.

pub async fn update_encryption_key( &mut self, encryption_key: &[u8], encryption_algorithm: EncryptionAlgorithm, ) -> Result<(), Error>

Associates a new root key with the data store and removes the old encryption key, if it exists. If two keys already exist, the inactive key is removed first.

pub fn get_encryption_algorithm(&self) -> EncryptionAlgorithm

Gets the encryption algorithm of the VMGS

pub fn is_encrypted(&self) -> bool

Whether the VMGS file is encrypted

pub fn was_provisioned_this_boot(&self) -> bool

Whether the VMGS file was provisioned during the most recent boot

Trait Implementations

impl Inspect for Vmgs

fn inspect(&self, req: Request<'_>)

Inspects the object.