Struct LumenFile 

pub struct LumenFile<'a> { /* private fields */ }

An open LUMEN file.

Implementations

impl<'a> LumenFile<'a>

pub fn open_unvalidated(buf: &'a [u8]) -> Result<LumenFile<'a>>

Open without checking the whole of section 11 first.

LumenFile::open runs every check of section 11 before it returns, and one of them walks each slice’s stream. A caller that wants a single layer, a layer preview for instance, pays for that walk without asking. This parses the container and its chunks and checks nothing: it leaves the streams to LumenFile::layer, which reports a malformed one when it reaches it.

pub fn open(buf: &'a [u8], level: Level) -> Result<LumenFile<'a>>

Open a plaintext file, validating it against level.

pub fn open_with_key( buf: &'a [u8], level: Level, key: SessionKey, ) -> Result<LumenFile<'a>>

Open a file whose session key is already known.

pub fn open_with_password( buf: &'a [u8], level: Level, password: &str, ) -> Result<LumenFile<'a>>

Open a password-protected file.

pub fn open_with_machine_key( buf: &'a [u8], level: Level, private_key: &[u8; 32], ) -> Result<LumenFile<'a>>

Open a machine-bound file with the recipient’s X25519 private key.

pub fn recover_password(&self, password: &str) -> Result<SessionKey>

Recover the session key from a password, without reopening.

pub fn recover_machine_key(&self, private_key: &[u8; 32]) -> Result<SessionKey>

Recover the session key from a recipient private key, without reopening.

pub fn bytes(&self) -> &'a [u8]

The file’s bytes.

pub fn header(&self) -> &FileHeader

The fixed file header.

pub fn directory(&self) -> &Directory

The chunk directory.

pub fn head(&self) -> &Head

The HEAD chunk.

pub fn meta(&self) -> &Meta

The META chunk.

pub fn profile(&self) -> Option<&Profile>

The PROF chunk, if present. A file carries at most one.

pub fn meta_sectors(&self) -> &[Sector]

Every sector META defines, in the order it lists them.

Sector 0 is implicit and has no entry here.

pub fn previews(&self) -> &[Preview]

Every PREV chunk, in file order.

pub fn extensions(&self) -> &[Extension]

Every EXTD chunk whose frame could be read, in file order.

pub fn dictionary(&self) -> Option<&ZstdDictionary>

The ZDIC chunk, if present.

pub fn layer_hashes(&self) -> Option<&LayerHashes>

The LHAS chunk, if present.

pub fn layer_table(&self) -> &LayerTable

The LTBL chunk.

pub fn layr_chunks(&self) -> &[LayrChunk]

Every LAYR chunk, in directory order.

pub fn voxl(&self) -> Option<&[u8]>

The VOXL payload, if present, verbatim.

pub fn auth(&self) -> Option<&Auth>

The AUTH chunk, if present.

pub fn layer_count(&self) -> u32

The layer count.

pub fn total_pixels(&self) -> u32

Pixels in one layer mask.

pub fn multi_sector(&self) -> bool

Whether the file declares sector-based layer encoding, i.e. whether some layer carries more than one sector (head.multi_sector_flag).

This is informational: which sectors a layer carries is read from its LTBL entries, not from this flag.

pub fn level(&self) -> Level

Whether the validation level this file was opened at is strict.

pub fn is_unlocked(&self) -> bool

Whether the file has a session key available.

pub fn layr_chunk_data(&self, index: u32) -> Result<Vec<u8>>

The decompressed, decrypted output of the LAYR chunk at directory index index: the concatenation of every slice the table places in it.

pub fn layer(&self, index: u32) -> Result<DecodedLayer>

The decoded mask of layer index as a single-material reader prints it.

That reader reads the layer’s first entry - sector 0’s, which every layer with data has - and skips the rest, so this is sector 0’s mask and not the union of every sector’s. A layer whose first entry carries no data is empty here even when a later sector holds data; LumenFile::is_single_material_complete reports that case, and LumenFile::layer_sectors reaches the other sectors.

pub fn layer_sectors(&self, index: u32) -> Result<Vec<DecodedSector>>

Every sector’s decoded mask on layer index, in ascending sector_id.

A sector with no data on this layer has no mask and is not reported.

pub fn is_single_material_complete(&self) -> bool

Whether a single-material reader would print every layer faithfully.

False when any layer carries data in a sector other than 0, which is content such a reader never reads and would drop silently: it must report the file incomplete rather than complete (section 7.2).

pub fn timing_for(&self, layer: u32, sector_id: u32) -> Result<Resolved>

Resolve one (layer, sector)’s timing.

The returned values already carry the sector’s META.sectors entry, the bottom and transition blend with the counts that sector carries or inherits, and the (layer, sector)’s own LROV payload. Overrides are not opt-in ([spec/08-print-control.md] section 4.5): a reader that does not apply them must refuse a file that carries an LROV chunk, because printing the layer at META’s exposure instead of its override fails quietly. This method is therefore the only supported way to read a layer’s timing.

pub fn verify_layer(&self, index: u32) -> Result<()>

Verify layer index against the LHAS leaf table and Merkle path.

pub fn verify_all(&self) -> Result<()>

Verify every layer and the Merkle root.

Trait Implementations

impl<'a> Debug for LumenFile<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.