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_sys::Win32::Storage::FileSystem::{
    FILE_GENERIC_READ, FILE_SHARE_READ, OPEN_EXISTING,
};
use wtf_string::Wtf16String;

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: a relative path would be fixed to it here.
let text = path.to_str().expect("a temporary path is valid UTF-8");
let request = OpenFile::new(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: Wtf16String) -> Result<Self, PathCaptureError>

Begins a request against path.

The path reaches CreateFileW as it was given, with no length limit and no check of this crate’s own, with one exception: a path that Win32 would resolve against the current directory is fixed to the current directory as it is now, by concatenation, so that it still names the same place when the request is performed on another thread after the directory has changed. A path that is not clearly a plain relative one is left exactly as given, and Win32 resolves it when the call is made; the rules, and what they leave out, are those of D-19 in the crate’s DESIGN-NOTES.md. path is the path as given and win32_path is the one handed to the call.

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.

Errors

PathCaptureError::InteriorNul if the path contains a NUL, which Win32 would read as its end, and the failure of GetCurrentDirectoryW if it had to be read and could not be.

pub fn from_anchored(path: AnchoredPath) -> Self

Begins a request against a path the caller has already anchored.

The path is not anchored again: the request hands Win32 the anchored path’s win32 form, which was fixed when the caller built it, whatever the current directory is now. This is for a caller that anchored its path when it built a request of its own, so that the meaning is fixed once (D-30 in the crate’s DESIGN-NOTES.md). Every other parameter starts as new starts it.

Example

use windows_namespace_request_sys::{AnchoredPath, OpenFile};
use wtf_string::Wtf16String;

// Anchored once, when the caller's own request was built...
let anchored = AnchoredPath::new(Wtf16String::from("a-child"))?;

// ...and handed on as it is, with nothing read again.
let request = OpenFile::from_anchored(anchored.clone());
assert_eq!(request.path(), anchored.given());
assert_eq!(request.win32_path(), anchored.win32());

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<SharedHandle>) -> Self

Sets hTemplateFile.

The request holds the template as one more holder of it, so it cannot be left naming a template the caller has since closed.

pub fn path(&self) -> &Wtf16Str

The path as it was given.

pub fn win32_path(&self) -> &Wtf16Str

The path that is handed to CreateFileW: the one given, or that one fixed to the current directory of the moment the request was built.

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<&SharedHandle>

The template handle, if one was supplied, shared with its other holders.

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

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

This is not Clone because copying the security attributes it may own allocates, and the allocation can fail. The type inherits that from SecurityAttributes::try_clone rather than hiding it behind an infallible signature that would have to panic. The template is shared, not duplicated (D-32 in the crate’s DESIGN-NOTES.md), so it cannot fail.

Errors

Returns SecurityAttributes::try_clone’s error when the memory for the security attributes cannot be allocated. A request without them 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.