Trait FileHandle 

pub trait FileHandle:
    Read
    + Write
    + Seek {
    type ReadRequest<'a>
       where Self: 'a;
    type ReadIntoRequest<'a>
       where Self: 'a;

    // Required methods
    fn path(&self) -> &Path;
    fn metadata(&self) -> Result<Metadata, VfError>;
    fn read_request_at(
        &self,
        offset: u64,
        length: usize,
    ) -> Self::ReadRequest<'_>;
    fn read_request_at_into<'a>(
        &'a self,
        offset: u64,
        buffer: &'a mut [u8],
    ) -> Self::ReadIntoRequest<'a>;
    fn read_at(&self, buffer: &mut [u8], offset: u64) -> Result<usize, VfError>;
    fn write_at(&self, buffer: &[u8], offset: u64) -> Result<usize, VfError>;
    fn read_native(&mut self, buffer: &mut [u8]) -> Result<usize, VfError>;
    fn read_to_end_with_limit(
        &mut self,
        max_bytes: usize,
    ) -> Result<Vec<u8>, VfError>;
    fn write_native(&mut self, buffer: &[u8]) -> Result<usize, VfError>;
    fn seek_native(&mut self, position: SeekFrom) -> Result<u64, VfError>;
    fn sync_data(&self) -> Result<(), VfError>;
    fn sync_all(&self) -> Result<(), VfError>;
    fn try_close(&mut self) -> Result<(), VfError>;
    fn is_closed(&self) -> bool;
    fn close(self) -> Result<(), VfError>
       where Self: Sized;

    // Provided method
    fn set_permissions(&self, _permissions: Permissions) -> Result<(), VfError> { ... }
}

Owned application file. Borrowed requests preserve the file’s lifetime; clients validate connection ownership before dispatching a vector.

External implementations must keep request storage valid for its borrowed lifetime, validate client ownership before I/O, and report positional progress without changing the cursor. Request constructors do no I/O. Associated request types are implementer contracts, not application-facing builders. A backend must retain ownership of live descriptors through cleanup failures.

Required Associated Types

type ReadRequest<'a> where Self: 'a

Borrowed positional read request; constructing it performs no I/O.

type ReadIntoRequest<'a> where Self: 'a

Borrowed positional request into a caller-owned destination buffer.

Required Methods

fn path(&self) -> &Path

Diagnostic name captured at open; not current path or object identity.

fn metadata(&self) -> Result<Metadata, VfError>

Query the opened object, even if its original pathname was renamed.

fn read_request_at(&self, offset: u64, length: usize) -> Self::ReadRequest<'_>

Prepare a non-cursor-changing read for this handle’s owning client.

fn read_request_at_into<'a>( &'a self, offset: u64, buffer: &'a mut [u8], ) -> Self::ReadIntoRequest<'a>

Borrow both the handle and destination until the vector call completes.

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

Read up to the buffer’s length without changing the cursor; may be short.

fn write_at(&self, buffer: &[u8], offset: u64) -> Result<usize, VfError>

Write up to the input’s length without changing the cursor; may be short.

fn read_native(&mut self, buffer: &mut [u8]) -> Result<usize, VfError>

Cursor-based read retaining structured errors, unlike the Read adapter.

fn read_to_end_with_limit( &mut self, max_bytes: usize, ) -> Result<Vec<u8>, VfError>

Collect from the current cursor with a caller-selected payload budget. A failed read may advance the cursor; exceeding the limit is an error, not successful truncation. Standard Read::read_to_end is not bounded.

fn write_native(&mut self, buffer: &[u8]) -> Result<usize, VfError>

Cursor-based possibly short write retaining structured errors.

fn seek_native(&mut self, position: SeekFrom) -> Result<u64, VfError>

Change the cursor, retaining structured errors unlike Seek.

fn sync_data(&self) -> Result<(), VfError>

Request durability of file data; errors are not discarded.

fn sync_all(&self) -> Result<(), VfError>

Request durability of file data and metadata supported by the backend.

fn try_close(&mut self) -> Result<(), VfError>

Close without surrendering cleanup ownership on failure. After an ambiguous failure, reconcile/close rather than resume ordinary I/O.

fn is_closed(&self) -> bool

Local close ownership only, not proof of remote liveness after failure.

fn close(self) -> Result<(), VfError>

where Self: Sized,

Consuming close: on failure the handle is lost and Drop retries cleanup best-effort on a later operation or cleanup drain. Prefer try_close when cleanup failures need reconciliation.

Provided Methods

fn set_permissions(&self, _permissions: Permissions) -> Result<(), VfError>

Change permission bits on the opened object, not by re-resolving its path. The default reports Unsupported; callers must not silently claim preservation.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<F: FileSystem> FileHandle for FsFile<F>

type ReadRequest<'a> = FsRead<'a, F> where Self: 'a

type ReadIntoRequest<'a> = FsReadInto<'a, F> where Self: 'a