Struct OpenFile 

pub struct OpenFile { /* private fields */ }

An owned, marshalable parameter set for CreateFileW.

Every parameter of the underlying call is expressible, including the two no audited consumer uses. An entry that could not express two of its own call’s parameters would be a narrowed CreateFileW, and narrowing a platform entry to fit the consumers currently in view is precisely the anti-pattern this workspace’s platform-integrity rule names.

Example

use std::fs;

use windows_namespace_request_sys::open::OpenFile;
use windows_namespace_request_sys::prepare;
use wtf_string::Wtf16String;
use windows_sys::Win32::Storage::FileSystem::{
    FILE_GENERIC_READ, FILE_SHARE_READ, OPEN_EXISTING,
};

let path = std::env::temp_dir().join(format!("wnrs-open-{}.tmp", std::process::id()));
fs::write(&path, b"example")?;

// Built on this thread, where the current directory still means what the
// caller thinks it means.
let text = path.to_str().expect("a temporary path is valid UTF-8");
let request = OpenFile::new(prepare(&Wtf16String::from(text))?)
    .with_desired_access(FILE_GENERIC_READ)
    .with_share_mode(FILE_SHARE_READ)
    .with_creation_disposition(OPEN_EXISTING);

// Performed here, but it would behave identically on any other thread.
let opened = fs::File::from(request.perform()?);
assert_eq!(opened.metadata()?.len(), b"example".len() as u64);

Implementations

impl OpenFile

pub fn new(path: PreparedPath) -> Self

Begins a request against path.

Every other parameter starts at the value that means “the caller said nothing”: no access, no sharing, no security attributes, a zero creation disposition, no flags, and no template. They are set explicitly rather than defaulted to a plausible-looking open, because a plausible default is exactly what a caller cannot see they got.

pub fn with_desired_access(self, desired_access: u32) -> Self

Sets dwDesiredAccess.

pub fn with_share_mode(self, share_mode: FILE_SHARE_MODE) -> Self

Sets dwShareMode.

pub fn with_security(self, security: Option<SecurityAttributes>) -> Self

Sets lpSecurityAttributes from an already-captured value.

Passing None means a null argument: default security and a non-inheritable handle. That is a different outcome from attributes carrying a null descriptor, which is why the distinction survives into this type rather than being flattened here.

pub fn with_creation_disposition( self, creation_disposition: FILE_CREATION_DISPOSITION, ) -> Self

Sets dwCreationDisposition.

pub fn with_flags_and_attributes( self, flags_and_attributes: FILE_FLAGS_AND_ATTRIBUTES, ) -> Self

Sets dwFlagsAndAttributes.

Carried verbatim, including FILE_FLAG_OVERLAPPED. Whether the opened handle is destined for a completion port is the caller’s to state and this crate’s to leave alone.

pub fn with_template(self, template: Option<CapturedHandle>) -> Self

Sets hTemplateFile from an already-captured handle.

The request owns a duplicate, so it cannot be left naming a template the caller has since closed.

pub fn path(&self) -> &PreparedPath

The prepared path this request will open.

pub fn desired_access(&self) -> u32

The requested access mask.

pub fn share_mode(&self) -> FILE_SHARE_MODE

The requested share mode.

pub fn security(&self) -> Option<&SecurityAttributes>

The captured security attributes, if any were supplied.

pub fn creation_disposition(&self) -> FILE_CREATION_DISPOSITION

The requested creation disposition.

pub fn flags_and_attributes(&self) -> FILE_FLAGS_AND_ATTRIBUTES

The requested flags and attributes.

pub fn template(&self) -> Option<&CapturedHandle>

The captured template handle, if one was supplied.

pub fn try_clone(&self) -> Result<Self, HandleCaptureError>

Copies the request, duplicating the template handle if it has one.

This is not Clone because a request may own a handle, and duplicating a handle is fallible. The type inherits that from CapturedHandle::try_clone rather than hiding it behind an infallible signature that would have to panic.

Errors

Returns the handle-capture failure when the template cannot be duplicated. A request with no template cannot fail.

pub fn perform(&self) -> Outcome<OwnedHandle>

Performs the open on the calling thread.

The handle comes back plain and unassociated: nothing here binds it to a completion port, because doing so irreversibly forecloses IoRing use of it and that choice belongs to a layer that knows the handle’s destination.

Errors

Returns the raw Win32 code, unaltered and snapshotted before any cleanup can overwrite it. ERROR_FILE_NOT_FOUND here means a missing path and nothing else is inferred from it.

Trait Implementations

impl Debug for OpenFile

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

Formats the value using the given formatter.

impl Request for OpenFile

type Error = Win32Error

How performing it can fail.

type Output = OwnedHandle

What performing the request produces.

fn perform(&self) -> Outcome<OwnedHandle>

Performs the request on the calling thread.