Struct HFILE

pub struct HFILE(/* private fields */);

Available on crate feature kernel only.

Handle to a file. Originally just a HANDLE.

Unless you need something specific, consider using the File high-level abstraction.

Implementations

impl HFILE

pub const unsafe fn from_ptr(p: *mut c_void) -> Self

Constructs a new handle object by wrapping a pointer.

This method can be used as an escape hatch to interoperate with other libraries.

Safety

Be sure the pointer has the correct type and isn’t owned by anyone else, otherwise you may cause memory access violations.

pub const unsafe fn raw_copy(&self) -> Self

Returns a raw copy of the underlying handle pointer.

Safety

As the name implies, raw_copy returns a raw copy of the handle, so closing one of the copies won’t close the others. This means a handle can be used after it has been closed, what can lead to errors and undefined behavior. Even worse: sometimes Windows reuses handle values, so you can call a method on a completely different handle type, what can be catastrophic.

However, in some cases the Windows API demands a copy of the handle – raw_copy is an escape hatch to fill this gap.

pub const unsafe fn as_mut(&mut self) -> &mut *mut c_void

Returns a mutable reference to the underlying raw pointer.

This method can be used as an escape hatch to interoperate with other libraries.

Safety

This method exposes the raw pointer used by raw Windows calls. It’s an opaque pointer to an internal Windows structure, and no dereferencings should be attempted.

pub const fn ptr(&self) -> *mut c_void

Returns the underlying raw pointer.

This method exposes the raw pointer used by raw Windows calls. It’s an opaque pointer to an internal Windows structure, and no dereferencings should be attempted.

This method can be used as an escape hatch to interoperate with other libraries.

impl HFILE

pub fn CreateFile( file_name: &str, desired_access: GENERIC, share_mode: Option<FILE_SHARE>, security_attributes: Option<&SECURITY_ATTRIBUTES<'_>>, creation_disposition: DISPOSITION, attributes: FILE_ATTRIBUTE, flags: Option<FILE_FLAG>, security: Option<FILE_SECURITY>, hfile_template: Option<&HFILE>, ) -> SysResult<(CloseHandleGuard<HFILE>, ERROR)>

CreateFile function.

The error code is also returned because it can carry information even if the file is successfully open.

Unless you need something specific, consider using the File high-level abstraction.

Examples

Opening an existing file as read-only:

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

let (hfile, status) = w::HFILE::CreateFile(
    "C:\\Temp\\test.txt",
    co::GENERIC::READ,
    Some(co::FILE_SHARE::READ),
    None,
    co::DISPOSITION::OPEN_EXISTING,
    co::FILE_ATTRIBUTE::NORMAL,
    None,
    None,
    None,
)?;

Opening a file for read and write. If the file doesn’t exist, create it:

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

let (hfile, status) = w::HFILE::CreateFile(
    "C:\\Temp\\test.txt",
    co::GENERIC::READ | co::GENERIC::WRITE,
    None,
    None,
    co::DISPOSITION::OPEN_ALWAYS,
    co::FILE_ATTRIBUTE::NORMAL,
    None,
    None,
    None,
)?;

pub fn CreateFileMapping( &self, mapping_attrs: Option<&SECURITY_ATTRIBUTES<'_>>, protect: PAGE, sec: Option<SEC>, max_size: Option<u64>, mapping_name: Option<&str>, ) -> SysResult<CloseHandleGuard<HFILEMAP>>

CreateFileMapping function.

Unless you need something specific, consider using the FileMapped high-level abstraction.

pub fn GetFileInformationByHandle( &self, ) -> SysResult<BY_HANDLE_FILE_INFORMATION>

GetFileInformationByHandle function.

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

GetFileSizeEx function.

pub fn GetFileTime(&self) -> SysResult<(FILETIME, FILETIME, FILETIME)>

GetFileTime function.

Returns, respectively:

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

Examples

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

let hfile: w::HFILE; // initialized somewhere

let (creation, last_access, last_write) = hfile.GetFileTime()?;

pub fn GetFileType(&self) -> SysResult<FILE_TYPE>

GetFileType function.

pub fn LockFile( &self, offset: u64, num_bytes_to_lock: u64, ) -> SysResult<UnlockFileGuard<'_>>

LockFile function.

In the original C implementation, you must call UnlockFile as a cleanup operation.

Here, the cleanup is performed automatically, because LockFile returns an UnlockFileGuard, which automatically calls UnlockFile when the guard goes out of scope. You must, however, keep the guard alive, otherwise the cleanup will be performed right away.

Examples

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

let hfile: w::HFILE; // initialized somewhere

let total_size = hfile.GetFileSizeEx()?;

let _lock_guard = hfile.LockFile(0, total_size as _)?; // keep guard alive

// file read/write operations...

// UnlockFile() called automatically

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

ReadFile function.

Reads 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 asynchronous reading – which use the OVERLAPPED struct – is not currently supported by this method, because the buffer must remain untouched until the async operation is complete, thus making the method unsound.

pub fn SetEndOfFile(&self) -> SysResult<()>

SetEndOfFile function.

pub fn SetFilePointerEx( &self, distance_to_move: i64, move_method: FILE_STARTING_POINT, ) -> SysResult<i64>

SetFilePointerEx function.

pub fn SetFileTime( &self, creation_time: Option<&FILETIME>, last_access_time: Option<&FILETIME>, last_write_time: Option<&FILETIME>, ) -> SysResult<()>

SetFileTime function.

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

WriteFile function.

Returns the number of bytes written.

Note that asynchronous writing – which use the OVERLAPPED struct – is not currently supported by this method, because the buffer must remain untouched until the async operation is complete, thus making the method unsound.

Trait Implementations

impl Debug for HFILE

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

Formats the value using the given formatter.

impl Display for HFILE

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

Formats the value using the given formatter.

impl Handle for HFILE

const NULL: Self

The null, uninitialized handle; equals to 0.

const INVALID: Self

The invalid handle; equals to -1.

unsafe fn from_ptr(p: *mut c_void) -> Self

Constructs a new handle object by wrapping a pointer.

unsafe fn raw_copy(&self) -> Self

Returns a raw copy of the underlying handle pointer.

unsafe fn as_mut(&mut self) -> &mut *mut c_void

Returns a mutable reference to the underlying raw pointer.

fn ptr(&self) -> *mut c_void

Returns the underlying raw pointer.

fn as_opt(&self) -> Option<&Self>

Returns None if the handle is null or invalid, otherwise returns Some(&self).

impl Hash for HFILE

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LowerHex for HFILE

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

Formats the value using the given formatter.

impl PartialEq for HFILE

fn eq(&self, other: &HFILE) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl UpperHex for HFILE

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

Formats the value using the given formatter.

impl Eq for HFILE

impl Send for HFILE

impl StructuralPartialEq for HFILE