Trait async_fs::windows::OpenOptionsExt

source · 
pub trait OpenOptionsExt: Sealed {
    // Required methods
    fn access_mode(&mut self, access: u32) -> &mut Self;
    fn share_mode(&mut self, val: u32) -> &mut Self;
    fn custom_flags(&mut self, flags: u32) -> &mut Self;
    fn attributes(&mut self, val: u32) -> &mut Self;
    fn security_qos_flags(&mut self, flags: u32) -> &mut Self;
}
Expand description

Windows-specific extensions to OpenOptions.

Required Methods§

source

fn access_mode(&mut self, access: u32) -> &mut Self

Overrides the dwDesiredAccess argument to the call to CreateFile with the specified value.

This will override the read, write, and append flags on the OpenOptions structure. This method provides fine-grained control over the permissions to read, write and append data, attributes (like hidden and system), and extended attributes.

§Examples
use async_fs::{OpenOptions, windows::OpenOptionsExt};

// Open without read and write permission, for example if you only need
// to call `stat` on the file
let file = OpenOptions::new().access_mode(0).open("foo.txt").await?;
source

fn share_mode(&mut self, val: u32) -> &mut Self

Overrides the dwShareMode argument to the call to CreateFile with the specified value.

By default share_mode is set to FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE. This allows other processes to read, write, and delete/rename the same file while it is open. Removing any of the flags will prevent other processes from performing the corresponding operation until the file handle is closed.

§Examples
use async_fs::{OpenOptions, windows::OpenOptionsExt};

// Do not allow others to read or modify this file while we have it open
// for writing.
let file = OpenOptions::new()
    .write(true)
    .share_mode(0)
    .open("foo.txt")
    .await?;
source

fn custom_flags(&mut self, flags: u32) -> &mut Self

Sets extra flags for the dwFileFlags argument to the call to CreateFile2 to the specified value (or combines it with attributes and security_qos_flags to set the dwFlagsAndAttributes for CreateFile).

Custom flags can only set flags, not remove flags set by Rust’s options. This option overwrites any previously set custom flags.

§Examples
use async_fs::{OpenOptions, windows::OpenOptionsExt};

let file = OpenOptions::new()
    .create(true)
    .write(true)
    .custom_flags(windows_sys::Win32::Storage::FileSystem::FILE_FLAG_DELETE_ON_CLOSE)
    .open("foo.txt")
    .await?;
source

fn attributes(&mut self, val: u32) -> &mut Self

Sets the dwFileAttributes argument to the call to CreateFile2 to the specified value (or combines it with custom_flags and security_qos_flags to set the dwFlagsAndAttributes for CreateFile).

If a new file is created because it does not yet exist and .create(true) or .create_new(true) are specified, the new file is given the attributes declared with .attributes().

If an existing file is opened with .create(true).truncate(true), its existing attributes are preserved and combined with the ones declared with .attributes().

In all other cases the attributes get ignored.

§Examples
use async_fs::{OpenOptions, windows::OpenOptionsExt};

let file = OpenOptions::new()
    .write(true)
    .create(true)
    .attributes(windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_HIDDEN)
    .open("foo.txt")
    .await?;
source

fn security_qos_flags(&mut self, flags: u32) -> &mut Self

Sets the dwSecurityQosFlags argument to the call to CreateFile2 to the specified value (or combines it with custom_flags and attributes to set the dwFlagsAndAttributes for CreateFile).

By default security_qos_flags is not set. It should be specified when opening a named pipe, to control to which degree a server process can act on behalf of a client process (security impersonation level).

When security_qos_flags is not set, a malicious program can gain the elevated privileges of a privileged Rust process when it allows opening user-specified paths, by tricking it into opening a named pipe. So arguably security_qos_flags should also be set when opening arbitrary paths. However the bits can then conflict with other flags, specifically FILE_FLAG_OPEN_NO_RECALL.

For information about possible values, see Impersonation Levels on the Windows Dev Center site. The SECURITY_SQOS_PRESENT flag is set automatically when using this method.

§Examples
use async_fs::{OpenOptions, windows::OpenOptionsExt};

let file = OpenOptions::new()
    .write(true)
    .create(true)
    .security_qos_flags(windows_sys::Win32::Storage::FileSystem::SECURITY_IDENTIFICATION)
    .open(r"\\.\pipe\MyPipe")
    .await?;

Object Safety§

This trait is not object safe.

Implementors§