Trait winsafe::prelude::kernel_Hfile

pub trait kernel_Hfile: Handle {
    // Provided methods
    fn CreateFile(
        file_name: &str,
        desired_access: GENERIC,
        share_mode: Option<FILE_SHARE>,
        security_attributes: Option<&mut SECURITY_ATTRIBUTES<'_>>,
        creation_disposition: DISPOSITION,
        attributes: FILE_ATTRIBUTE,
        flags: Option<FILE_FLAG>,
        security: Option<FILE_SECURITY>,
        hfile_template: Option<&HFILE>
    ) -> SysResult<(CloseHandleGuard<HFILE>, ERROR)> { ... }
    fn CreateFileMapping(
        &self,
        mapping_attrs: Option<&mut SECURITY_ATTRIBUTES<'_>>,
        protect: PAGE,
        max_size: Option<u64>,
        mapping_name: Option<&str>
    ) -> SysResult<CloseHandleGuard<HFILEMAP>> { ... }
    fn GetFileInformationByHandle(
        &self,
        fi: &mut BY_HANDLE_FILE_INFORMATION
    ) -> SysResult<()> { ... }
    fn GetFileSizeEx(&self) -> SysResult<u64> { ... }
    fn GetFileTime(
        &self,
        creation_time: Option<&mut FILETIME>,
        last_access_time: Option<&mut FILETIME>,
        last_write_time: Option<&mut FILETIME>
    ) -> SysResult<()> { ... }
    fn GetFileType(&self) -> SysResult<FILE_TYPE> { ... }
    fn LockFile(
        &self,
        offset: u64,
        num_bytes_to_lock: u64
    ) -> SysResult<UnlockFileGuard<'_, Self>> { ... }
    fn ReadFile(&self, buffer: &mut [u8]) -> SysResult<u32> { ... }
    fn SetEndOfFile(&self) -> SysResult<()> { ... }
    fn SetFilePointerEx(
        &self,
        distance_to_move: i64,
        move_method: FILE_STARTING_POINT
    ) -> SysResult<i64> { ... }
    fn SetFileTime(
        &self,
        creation_time: Option<&FILETIME>,
        last_access_time: Option<&FILETIME>,
        last_write_time: Option<&FILETIME>
    ) -> SysResult<()> { ... }
    fn WriteFile(&self, data: &[u8]) -> SysResult<u32> { ... }
}

Available on crate feature kernel only.

This trait is enabled with the kernel feature, and provides methods for HFILE.

Prefer importing this trait through the prelude:

use winsafe::prelude::*;

Provided Methods

fn CreateFile( file_name: &str, desired_access: GENERIC, share_mode: Option<FILE_SHARE>, security_attributes: Option<&mut 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,
)?;

fn CreateFileMapping( &self, mapping_attrs: Option<&mut SECURITY_ATTRIBUTES<'_>>, protect: PAGE, 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.

fn GetFileInformationByHandle( &self, fi: &mut BY_HANDLE_FILE_INFORMATION ) -> SysResult<()>

GetFileInformationByHandle function.

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

GetFileSizeEx function.

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

GetFileTime function.

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

GetFileType function.

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

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 = hfile.LockFile(0, total_size as _)?; // keep guard alive

// file read/write operations...

// UnlockFile() called automatically

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.

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

SetEndOfFile function.

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

SetFilePointerEx function.

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

SetFileTime function.

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.

Object Safety

This trait is not object safe.

Implementors

impl kernel_Hfile for HFILE