Trait winsafe::prelude::kernel_Hfile
source · 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> { ... }
}
kernel
only.Expand description
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§
sourcefn 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 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,
)?;
sourcefn CreateFileMapping(
&self,
mapping_attrs: Option<&mut SECURITY_ATTRIBUTES<'_>>,
protect: PAGE,
max_size: Option<u64>,
mapping_name: Option<&str>
) -> SysResult<CloseHandleGuard<HFILEMAP>>
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.
sourcefn GetFileInformationByHandle(
&self,
fi: &mut BY_HANDLE_FILE_INFORMATION
) -> SysResult<()>
fn GetFileInformationByHandle( &self, fi: &mut BY_HANDLE_FILE_INFORMATION ) -> SysResult<()>
GetFileInformationByHandle
function.
sourcefn GetFileSizeEx(&self) -> SysResult<u64>
fn GetFileSizeEx(&self) -> SysResult<u64>
GetFileSizeEx
function.
sourcefn GetFileTime(
&self,
creation_time: Option<&mut FILETIME>,
last_access_time: Option<&mut FILETIME>,
last_write_time: Option<&mut FILETIME>
) -> SysResult<()>
fn GetFileTime( &self, creation_time: Option<&mut FILETIME>, last_access_time: Option<&mut FILETIME>, last_write_time: Option<&mut FILETIME> ) -> SysResult<()>
GetFileTime
function.
sourcefn GetFileType(&self) -> SysResult<FILE_TYPE>
fn GetFileType(&self) -> SysResult<FILE_TYPE>
GetFileType
function.
sourcefn LockFile(
&self,
offset: u64,
num_bytes_to_lock: u64
) -> SysResult<UnlockFileGuard<'_, Self>>
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
sourcefn ReadFile(&self, buffer: &mut [u8]) -> SysResult<u32>
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.
sourcefn SetEndOfFile(&self) -> SysResult<()>
fn SetEndOfFile(&self) -> SysResult<()>
SetEndOfFile
function.
sourcefn SetFilePointerEx(
&self,
distance_to_move: i64,
move_method: FILE_STARTING_POINT
) -> SysResult<i64>
fn SetFilePointerEx( &self, distance_to_move: i64, move_method: FILE_STARTING_POINT ) -> SysResult<i64>
SetFilePointerEx
function.
sourcefn SetFileTime(
&self,
creation_time: Option<&FILETIME>,
last_access_time: Option<&FILETIME>,
last_write_time: Option<&FILETIME>
) -> SysResult<()>
fn SetFileTime( &self, creation_time: Option<&FILETIME>, last_access_time: Option<&FILETIME>, last_write_time: Option<&FILETIME> ) -> SysResult<()>
SetFileTime
function.
sourcefn WriteFile(&self, data: &[u8]) -> SysResult<u32>
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.