Struct OpenRequest 

pub struct OpenRequest<B: Buffering = Cached, A: DataAccess = ReadWrite> { /* private fields */ }

The request to open one file, built by OpenedFile::request and made by perform: the path, fixed to the current directory if it was relative, and the options, typed by the buffering mode and the data access of the OpenedFile it opens.

It is Send, so it can be built on the thread that has the path and the current directory and performed on one that can afford to block, and it can be performed more than once, each time opening the file again.

Implementations

impl<B: Buffering, A: DataAccess> OpenRequest<B, A>

pub fn with_security_descriptor(self, descriptor: SecurityDescriptor) -> Self

Give the file this open creates the security descriptor, built from SDDL with SecurityDescriptor::from_sddl. The request owns it and frees it, and a caller never holds a pointer to it. Calling this again replaces the descriptor.

It is the request’s and not a FileOptions field because a descriptor owns memory and cannot be copied, and the options are a plain Copy description that is passed to several opens. Handles are never inheritable: the attributes this passes to CreateFileW say so (bInheritHandle is false), and a request given no descriptor passes none, which the CreateFileW page documents as a handle that cannot be inherited.

The CreateFileW page says the descriptor is for a file that is created and is ignored when the file exists (measured: an open of an existing file with a descriptor that denies reading leaves the file as it was). This crate does not apply the descriptor itself; a created file’s descriptor reads back as the one given, through win-authorization-sys’s get_security_info, for a file opened with FileRights::READ_CONTROL.

pub fn perform(&self) -> Result<OpenedFile<B, A>>

Open the file, on the calling thread. This blocks for as long as CreateFileW does, and where the name leads is the caller’s to know, as OpenedFile::open says.

Errors

RemoteDevice (as an io::ErrorKind::Unsupported error) when B can claim its warranty only on a local device and the opened handle is on a remote one. That is decided from the handle’s final path, which GetFinalPathNameByHandleW resolves through links and mapped drives, so there is no window between the check and the open in which a link can be swapped. It is made after the open, so a file created before the refusal stays created and the open has already reached the network. UnknownLocation (also io::ErrorKind::Unsupported) when the handle’s final path cannot be read, since it is then not known to be a file on a local volume; the call’s own error is its source. That is this crate’s narrowing and not a condition of CreateFileW, and only an unbuffered open is subject to it: a cached open of a device is not refused, and what a name leads to is the caller’s responsibility (DI-D-67). Otherwise whatever the open reports, among them SharingViolation (as an io::ErrorKind::ResourceBusy error) when the file is open in a way that conflicts with this open’s access or sharing.

Trait Implementations

impl<B: Debug + Buffering, A: Debug + DataAccess> Debug for OpenRequest<B, A>

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

Formats the value using the given formatter.