Struct 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 erase_and_write(&self, data: &[u8]) -> SysResult<()>

Truncates the file size to zero, then writes the bytes.

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_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 read_buffer(&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 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.

Note that sometimes the system will make the file larger than you specified, so don’t bindly trust this method.

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

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

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

Returns, in current time zone, 3 times of the file, respectively:

1. creation time;
2. last access time;
3. last write time.

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.