Struct OpenFileByIdentifier 

pub struct OpenFileByIdentifier { /* private fields */ }

An owned, marshalable parameter set for OpenFileById.

Example

use std::fs;

use windows_namespace_request_sys::open_by_id::{FileIdentifier, OpenFileByIdentifier};
use windows_sys::Win32::Storage::FileSystem::{
    FILE_GENERIC_READ, FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE,
};

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

// Any open handle on the same volume will do as the hint; it is never the
// object being reopened. The request holds it, shared.
let request = OpenFileByIdentifier::new(file, FileIdentifier::FileId(0))
    .with_desired_access(FILE_GENERIC_READ)
    .with_share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE);

assert_eq!(request.identifier(), FileIdentifier::FileId(0));

Implementations

impl OpenFileByIdentifier

pub fn new( volume_hint: impl Into<SharedHandle>, identifier: FileIdentifier, ) -> Self

Begins a request to reopen identifier, using volume_hint to name the volume it lives on.

As with crate::open::OpenFile, the remaining parameters start at “the caller said nothing” and are set explicitly. There is no creation disposition to set: OpenFileById has none, which is one of the reasons this is a separate entry rather than a variant. The request holds volume_hint as one more holder of it.

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.

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

Sets dwFlagsAndAttributes, carried verbatim as in crate::open::OpenFile.

pub fn volume_hint(&self) -> &SharedHandle

The volume-hint handle, shared with its other holders.

pub fn identifier(&self) -> FileIdentifier

The identifier this request will reopen.

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 flags_and_attributes(&self) -> FILE_FLAGS_AND_ATTRIBUTES

The requested flags and attributes.

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

Copies the request, sharing the volume-hint handle.

Not Clone, for the same reason crate::open::OpenFile::try_clone is not: copying the security attributes it may own is fallible. The hint 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, as with every other handle-producing entry.

Errors

Returns the raw Win32 code, unaltered. ERROR_INVALID_PARAMETER here most often means the identified object no longer exists, but nothing in this crate infers that on the caller’s behalf.

Trait Implementations

impl Debug for OpenFileByIdentifier

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

Formats the value using the given formatter.

impl Request for OpenFileByIdentifier

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.