Struct Image 

pub struct Image { /* private fields */ }

Opened EWF image and logical media reader.

Implementations

impl Image

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Opens an EWF image from the first segment path.

Adjacent segments are discovered automatically from the first path.

Errors

Returns an error if no segment set can be discovered, a segment cannot be read, or the image is unsupported or malformed.

pub fn open_with_options( path: impl AsRef<Path>, options: OpenOptions, ) -> Result<Self>

Opens an EWF image from the first segment path with explicit options.

Errors

Returns an error if no segment set can be discovered, a segment cannot be read, or the image is unsupported or malformed.

pub fn open_with_password( path: impl AsRef<Path>, password: &EwfPassword, ) -> Result<Self>

Opens an EWF image using caller-supplied password bytes.

Supplying a password for an unencrypted image is harmless.

Errors

Returns an error if no segment set can be discovered, a segment cannot be read, the password is rejected, or the image is unsupported or malformed.

pub fn open_with_options_and_password( path: impl AsRef<Path>, options: OpenOptions, password: &EwfPassword, ) -> Result<Self>

Opens an EWF image using explicit options and caller-supplied password bytes.

Supplying a password for an unencrypted image is harmless.

Errors

Returns an error if no segment set can be discovered, a segment cannot be read, the password is rejected, or the image is unsupported or malformed.

pub fn open_segments<P, I>(paths: I) -> Result<Self>

where P: AsRef<Path>, I: IntoIterator<Item = P>,

Opens an EWF image from an explicit ordered segment path list.

Errors

Returns an error if the list is empty, a segment cannot be read, or the image is unsupported or malformed.

pub fn open_segments_with_options<P, I>( paths: I, options: OpenOptions, ) -> Result<Self>

where P: AsRef<Path>, I: IntoIterator<Item = P>,

Opens an EWF image from explicit ordered segment paths with options.

Errors

Returns an error if the list is empty, a segment cannot be read, or the image is unsupported or malformed.

pub fn open_segments_with_options_and_password<P, I>( paths: I, options: OpenOptions, password: &EwfPassword, ) -> Result<Self>

where P: AsRef<Path>, I: IntoIterator<Item = P>,

Opens an explicit ordered segment path list using explicit options and caller-supplied password bytes.

Supplying a password for an unencrypted image is harmless.

Errors

Returns an error if the list is empty, a segment cannot be read, the password is rejected, or the image is unsupported or malformed.

pub fn open_readers<N, R, I>(segments: I) -> Result<Self>

where N: Into<PathBuf>, R: SegmentReader + 'static, I: IntoIterator<Item = (N, R)>,

Opens an EWF image from supplied readers and segment labels.

Supplied readers are kept by the image and are not reopened from the filesystem. Labels are used anywhere this crate reports segment paths.

Errors

Returns an error if the list is empty, a reader fails, or the image is unsupported or malformed.

pub fn open_readers_with_options<N, R, I>( segments: I, options: OpenOptions, ) -> Result<Self>

where N: Into<PathBuf>, R: SegmentReader + 'static, I: IntoIterator<Item = (N, R)>,

Opens an EWF image from supplied readers with explicit options.

Errors

Returns an error if the list is empty, a reader fails, or the image is unsupported or malformed.

pub fn open_readers_with_options_and_password<N, R, I>( segments: I, options: OpenOptions, password: &EwfPassword, ) -> Result<Self>

where N: Into<PathBuf>, R: SegmentReader + 'static, I: IntoIterator<Item = (N, R)>,

Opens supplied readers using explicit options and caller-supplied password bytes.

Supplying a password for an unencrypted image is harmless. Supplied readers are retained by the image and are never reopened by path.

Errors

Returns an error if the list is empty, a reader fails, the password is rejected, or the image is unsupported or malformed.

pub fn open_sources<N: Into<PathBuf>>( sources: impl IntoIterator<Item = (N, SegmentSource)>, ) -> Result<Self>

Opens explicitly ordered, named positioned sources with default options. Supports EWF1 and EWF2. Names are labels, never reopened as filesystem paths.

pub fn open_sources_with_options<N: Into<PathBuf>>( sources: impl IntoIterator<Item = (N, SegmentSource)>, options: OpenOptions, ) -> Result<Self>

Opens positioned sources with reader controls. All supplied backings stay owned for the image lifetime; an open-handle limit below their count is rejected.

pub fn open_sources_with_options_and_password<N: Into<PathBuf>>( sources: impl IntoIterator<Item = (N, SegmentSource)>, options: OpenOptions, password: &EwfPassword, ) -> Result<Self>

Opens encrypted positioned sources using one caller-supplied password.

pub fn info(&self) -> &ImageInfo

Returns parsed image metadata and geometry.

pub fn sections(&self) -> &[SectionInfo]

Returns descriptor summaries in segment order and parser traversal order. Summary offsets are segment-relative, not logical media offsets.

pub fn open_strictness(&self) -> OpenStrictness

Returns the structural policy used when opening this image.

pub fn encryption_info(&self) -> Option<EncryptionInfo>

Returns non-secret encryption status for the opened image.

pub fn reader_statistics(&self) -> Option<ReaderStatistics>

Returns cumulative reader counters when statistics were enabled at open time.

Snapshots are shared across clones and cursors created from this image.

pub fn reader_cache_info(&self) -> ReaderCacheInfo

Returns configured capacities and retained table-page payload bytes.

pub fn filename(&self) -> &Path

Returns the first segment filename or supplied-reader label.

pub fn number_of_segments(&self) -> usize

Returns the number of segments in the opened image.

pub fn maximum_number_of_open_handles(&self) -> Result<Option<usize>>

Returns the configured maximum number of open segment handles.

Errors

Returns an error if the internal segment pool lock is poisoned.

pub fn set_maximum_number_of_open_handles( &self, maximum_open_handles: Option<usize>, ) -> Result<()>

Updates the maximum number of open segment handles.

None allows all handles to remain open. Supplied-reader images cannot evict and reopen readers, so this value is validated against the reader set.

Errors

Returns an error if the value is invalid for supplied readers or if the internal segment pool lock is poisoned.

pub fn number_of_open_segment_handles(&self) -> Result<usize>

Returns the current number of open segment handles.

Errors

Returns an error if the internal segment pool lock is poisoned.

pub fn segment_filenames(&self) -> &[PathBuf]

Returns all segment filenames or supplied-reader labels.

pub fn segment_filename(&self, index: usize) -> Option<&Path>

Returns one segment filename or supplied-reader label by index.

pub fn segment_set_size(&self) -> Result<u64>

Returns the total byte size of all opened segment containers.

For supplied readers, this uses SegmentReader::segment_len.

Errors

Returns an error if a segment length cannot be read, the internal segment pool lock is poisoned, or the total size overflows u64.

pub fn segment_files_corrupted(&self) -> Result<bool>

Probes path-backed segment files for corruption-style structural errors.

Images opened from supplied readers return false because there are no filesystem paths to reprobe.

Errors

Returns an error if a path-backed probe fails unexpectedly.

pub fn segment_files_encrypted(&self) -> Result<bool>

Probes path-backed segment files for EWF2 encryption markers.

Images opened from supplied readers return false because there are no filesystem paths to reprobe.

Errors

Returns an error if a path-backed probe fails unexpectedly.

pub fn segment_filename_for_chunk(&self, chunk_index: u64) -> Result<&Path>

Returns the segment containing a logical chunk.

Errors

Returns an error if chunk_index is outside the parsed chunk index or if the chunk index references a missing segment.

pub fn segment_filename_for_offset(&self, offset: u64) -> Result<Option<&Path>>

Returns the segment containing a logical byte offset.

Offsets at or beyond the logical media size return Ok(None).

Errors

Returns an error if the chunk geometry is malformed.

pub fn format(&self) -> Format

Returns the top-level EWF format generation.

pub fn format_profile(&self) -> FormatProfile

Returns the inferred format profile.

pub fn chunk_size(&self) -> u64

Returns the logical chunk size in bytes.

pub fn media_size(&self) -> u64

Returns the logical media size in bytes.

pub fn header_codepage(&self) -> HeaderCodepage

Returns the header codepage used for decoded EWF1 values.

pub fn header_values_date_format(&self) -> HeaderDateFormat

Returns the date format applied to header date values.

pub fn sectors_per_chunk(&self) -> Option<u64>

Returns sectors per chunk from media metadata.

pub fn bytes_per_sector(&self) -> Option<u64>

Returns bytes per sector from media metadata.

pub fn number_of_sectors(&self) -> Option<u64>

Returns the logical sector count from media metadata.

pub fn number_of_chunks(&self) -> Option<u64>

Returns the logical chunk count from media metadata.

pub fn error_granularity(&self) -> Option<u64>

Returns error granularity in sectors from media metadata.

pub fn segment_file_set_identifier(&self) -> Option<[u8; 16]>

Returns the segment set identifier.

pub fn segment_file_version(&self) -> Option<SegmentFileVersion>

Returns the EWF2 segment file version.

pub fn compression_method(&self) -> Option<CompressionMethod>

Returns the stored compression method metadata.

pub fn compression_values(&self) -> CompressionValues

Returns stored compression level and flags metadata.

pub fn media_type(&self) -> Option<MediaType>

Returns media type metadata.

pub fn media_flags(&self) -> MediaFlags

Returns media flag metadata.

pub fn memory_extents(&self) -> &[MemoryExtent]

Returns memory acquisition extents.

pub fn number_of_memory_extents(&self) -> usize

Returns the number of memory acquisition extents.

pub fn memory_extent(&self, index: usize) -> Option<&MemoryExtent>

Returns one memory acquisition extent by index.

pub fn ewf2_increment_data(&self) -> &[Vec<u8>]

Returns raw EWF2 increment data sections.

pub fn number_of_ewf2_increment_data_sections(&self) -> usize

Returns the number of EWF2 increment data sections.

pub fn ewf2_increment_data_section(&self, index: usize) -> Option<&[u8]>

Returns one raw EWF2 increment data section by index.

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

Returns the raw EWF2 final information section.

pub fn ewf2_restart_data(&self) -> Option<&str>

Returns EWF2 restart data text.

pub fn ewf2_analytical_data(&self) -> Option<&str>

Returns EWF2 analytical data text.

pub fn header_value(&self, identifier: &str) -> Option<Cow<'_, str>>

Returns a header value by its EWF identifier.

pub fn number_of_header_values(&self) -> usize

Returns the number of available header values.

pub fn header_value_identifier(&self, index: usize) -> Option<&str>

Returns a header value identifier by enumeration index.

pub fn hash_value(&self, identifier: &str) -> Option<&str>

Returns a stored hash string by identifier.

pub fn number_of_hash_values(&self) -> usize

Returns the number of stored hash strings.

pub fn hash_value_identifier(&self, index: usize) -> Option<&str>

Returns a stored hash identifier by enumeration index.

pub fn cursor(&self) -> ImageCursor

Returns a seekable cursor over the logical media stream.

pub fn read_at(&self, buf: &mut [u8], offset: u64) -> Result<usize>

Reads logical media bytes at an absolute byte offset.

Returns Ok(0) when buf is empty or offset is at or beyond the logical media size.

Errors

Returns an error if chunk lookup, decoding, checksum validation, or segment I/O fails, or if Image::signal_abort has been called.

pub fn read_buffer_at_offset( &self, buf: &mut [u8], offset: u64, ) -> Result<usize>

Alias for Image::read_at.

Errors

Returns the same errors as Image::read_at.

pub fn read_single_file_at( &self, entry: &SingleFileEntry, buf: &mut [u8], offset: u64, ) -> Result<usize>

Reads bytes from a logical single-file catalog entry.

Sparse extents read as zeroes. EWF1 logical sparse entries repeat a stored byte or read from their duplicate offset.

Errors

Returns an error if the entry metadata is inconsistent, the requested file range is not covered by extents, underlying image reads fail, or Image::signal_abort has been called.

pub fn read_single_file_at_strict( &self, entry: &SingleFileEntry, buf: &mut [u8], offset: u64, ) -> Result<usize>

Reads a logical file with strict chunk validation, bypassing decoded caches and the zero-on-error policy. Sparse entry handling is unchanged. Does not verify stored file hashes; use verify_single_file for that.

pub fn read_file_entry_at( &self, entry: &SingleFileEntry, buf: &mut [u8], offset: u64, ) -> Result<usize>

Alias for Image::read_single_file_at.

Errors

Returns the same errors as Image::read_single_file_at.

pub fn root_file_entry(&self) -> Option<&SingleFileEntry>

Returns the root logical single-file entry, if present.

pub fn file_entry_by_path(&self, path: &str) -> Result<Option<&SingleFileEntry>>

Returns a logical single-file entry by path.

Errors

Returns an error if path contains an empty entry name.

pub fn source_for_file_entry( &self, entry: &SingleFileEntry, ) -> Option<&SingleFileSource>

Returns the source record associated with a logical single-file entry.

pub fn subject_for_file_entry( &self, entry: &SingleFileEntry, ) -> Option<&SingleFileSubject>

Returns the subject record associated with a logical single-file entry.

pub fn access_control_entries_for_file_entry( &self, entry: &SingleFileEntry, ) -> &[SingleFilePermission]

Returns access-control entries associated with a logical single-file entry.

pub fn number_of_access_control_entries_for_file_entry( &self, entry: &SingleFileEntry, ) -> usize

Returns the number of access-control entries for a logical single-file entry.

pub fn access_control_entry_for_file_entry( &self, entry: &SingleFileEntry, index: usize, ) -> Option<&SingleFilePermission>

Returns one access-control entry for a logical single-file entry by index.

pub fn md5_hash(&self) -> Option<[u8; 16]>

Returns the stored MD5 hash bytes.

pub fn sha1_hash(&self) -> Option<[u8; 20]>

Returns the stored SHA1 hash bytes.

pub fn acquisition_errors(&self) -> &[AcquisitionError]

Returns acquisition error ranges.

pub fn number_of_acquisition_errors(&self) -> usize

Returns the number of acquisition error ranges.

pub fn acquisition_error(&self, index: usize) -> Option<&AcquisitionError>

Returns one acquisition error range by index.

pub fn sessions(&self) -> &[SectorRange]

Returns session sector ranges.

pub fn number_of_sessions(&self) -> usize

Returns the number of session sector ranges.

pub fn session(&self, index: usize) -> Option<&SectorRange>

Returns one session sector range by index.

pub fn tracks(&self) -> &[SectorRange]

Returns track sector ranges.

pub fn number_of_tracks(&self) -> usize

Returns the number of track sector ranges.

pub fn track(&self, index: usize) -> Option<&SectorRange>

Returns one track sector range by index.

pub fn read_zero_chunk_on_error(&self) -> bool

Returns whether checksum-failed chunks are read as zero-filled data.

pub fn set_read_zero_chunk_on_error(&self, zero_on_error: bool)

Sets whether checksum-failed chunks are read as zero-filled data.

pub fn signal_abort(&self)

Signals future reads and verification to abort with EwfError::Aborted.

pub fn checksum_errors(&self) -> Result<Vec<SectorRange>>

Returns checksum error ranges observed while reading.

Errors

Returns an error if the internal checksum-error lock is poisoned.

pub fn number_of_checksum_errors(&self) -> Result<usize>

Returns the number of checksum error ranges observed while reading.

Errors

Returns an error if the internal checksum-error lock is poisoned.

pub fn checksum_error(&self, index: usize) -> Result<Option<SectorRange>>

Returns one checksum error range observed while reading.

Errors

Returns an error if the internal checksum-error lock is poisoned.

pub fn single_file_cursor(&self, entry: &SingleFileEntry) -> SingleFileCursor

Returns a seekable cursor over a logical single-file entry.

pub fn single_file_cursor_by_path( &self, path: &str, ) -> Result<Option<SingleFileCursor>>

Returns a seekable cursor over a logical single-file entry by path.

Errors

Returns an error if path contains an empty entry name.

pub fn read_data_chunk(&self, chunk_index: u64) -> Result<DataChunk>

Reads and decodes one logical data chunk.

Errors

Returns an error if the chunk index is invalid, segment I/O fails, decoding fails, checksum validation fails under the current policy, or Image::signal_abort has been called.

pub fn read_encoded_data_chunk( &self, chunk_index: u64, ) -> Result<EncodedDataChunk>

Reads one encoded data chunk without decoding the payload.

Errors

Returns an error if the chunk index is invalid, segment I/O fails, or Image::signal_abort has been called.

impl Image

pub fn analyze(&self, options: &VerifyOptions) -> Result<IntegrityReport>

Collects media failures, redundant-table disagreements, acquisition context, and digest mismatches. Continues after chunk failures without substituting zero bytes. Structural validation is the validation performed during open.

pub fn analyze_with_progress( &self, options: &VerifyOptions, progress: impl FnMut(VerifyProgress) -> ControlFlow<()>, ) -> Result<IntegrityReport>

Analyzes with media progress and per-operation cancellation. Progress begins after redundant-table checks. A cancelled scan returns Aborted, not a successful partial report.

impl Image

pub fn verify_single_file( &self, entry: &SingleFileEntry, ) -> Result<SingleFileVerification>

Strictly verifies one regular file against its stored MD5/SHA1 hashes. Mismatches are results; malformed digests and unreadable data are errors. The caller should supply an entry from this image’s catalog.

pub fn verify_single_file_with_progress( &self, entry: &SingleFileEntry, progress: impl FnMut(SingleFileProgress) -> ControlFlow<()>, ) -> Result<SingleFileVerification>

Verifies one file, with cooperative cancellation before and after each buffer.

pub fn copy_single_file_with_progress( &self, entry: &SingleFileEntry, output: &mut impl Write, progress: impl FnMut(SingleFileProgress) -> ControlFlow<()>, ) -> Result<SingleFileVerification>

Copies strictly decoded file bytes and compares stored file hashes. Uses bounded buffers and bypasses decoded caches and recovery policies. The caller owns output publication: errors, cancellation, or mismatches can leave partial or unverified bytes in output. No output is flushed or synchronized here. Missing references return None, not success.

impl Image

pub fn verify(&self) -> Result<VerifyResult>

Computes MD5, SHA1, and SHA256 hashes and compares embedded references. Reads backing chunks without using cached or zero-filled recovery data. Returns an error on corruption, I/O failure, or cancellation.

pub fn verify_with_options( &self, options: &VerifyOptions, ) -> Result<VerificationReport>

Computes MD5, SHA1, and SHA256 and compares stored and external references. Chunk corruption fails verification even if normal reads allow zero-fill.

pub fn verify_with_progress( &self, options: &VerifyOptions, progress: impl FnMut(VerifyProgress) -> ControlFlow<()>, ) -> Result<VerificationReport>

Verifies media with an initial event and an event after every processed chunk. Returning Break(()) cancels this operation with EwfError::Aborted, without aborting other readers. Already-running worker reads finish before the call returns. Image::signal_abort is also honored.

Trait Implementations

impl Clone for Image

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Image

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

Formats the value using the given formatter.