Struct winsafe::File

pub struct File { /* private fields */ }

Available on crate feature kernel only.

Manages an HFILE handle, which provides file read/write and other operations. It is closed automatically when the object goes out of scope.

This is an alternative to the standard std::fs::File, with a possibly faster implementation since it’s Windows-only.

If you just want to read the file, consider memory-mapping it with FileMapped, which tends to be faster.

Examples

Reading the contents as a string:

use winsafe::{self as w, prelude::*};

let f = w::File::open(
    "C:\\Temp\\foo.txt",
    w::FileAccess::ExistingRW,
)?;
let raw_bytes = f.read_all()?;
let text = w::WString::parse(&raw_bytes)?.to_string();

Erasing the file and writing a string:

use winsafe::{self as w, prelude::*};

let f = w::File::open(
    "C:\\Temp\\foo.txt",
    w::FileAccess::OpenOrCreateRW,
)?;
f.set_size(0)?; // truncate
f.write("My text".as_bytes())?;

Implementations

impl File

pub fn open(file_path: &str, access: FileAccess) -> SysResult<Self>

Opens a file with the desired access.

pub fn hfile(&self) -> &HFILE

Returns the underlying file handle.

pub fn pointer_offset(&self) -> SysResult<u64>

Returns the position of the file pointer by calling HFILE::SetFilePointerEx.

pub fn read(&self, buffer: &mut [u8]) -> SysResult<u32>

Calls HFILE::ReadFile to read at most buffer.len() bytes from the file, starting at the current file pointer offset. Returns how many bytes were actually read. The file pointer is then incremented by the number of bytes read.

Note that the API limits the reading up to 4 GB.

pub fn read_all(&self) -> SysResult<Vec<u8>>

Returns the size of the file by calling HFILE::GetFileSizeEx, allocates the Vec buffer, then reads all the file bytes by calling HFILE::ReadFile.

Note that the API limits the reading up to 4 GB.

pub fn set_pointer_offset(&self, offset: u64) -> SysResult<()>

Sets the position of the file pointer by calling HFILE::SetFilePointerEx.

pub fn set_size(&self, num_bytes: u64) -> SysResult<()>

Truncates or expands the file by calling HFILE::SetFilePointerEx and HFILE::SetEndOfFile, then sets the file pointer to the beginning of the file.

If the size is increased, the contents in the new area are undefined.

pub fn size(&self) -> SysResult<u64>

Returns the size of the file by calling HFILE::GetFileSizeEx.

pub fn times(&self) -> SysResult<(SYSTEMTIME, SYSTEMTIME)>

Returns the creation and last write times of the file, in the current time zone.

pub fn write(&self, data: &[u8]) -> SysResult<()>

Writes the bytes at the current file pointer by calling HFILE::WriteFile.

This method will fail if the file was opened with FileAccess::ExistingReadOnly.