Struct QueryFileInformation

Source

pub struct QueryFileInformation { /* private fields */ }

Expand description

An owned, marshalable parameter set for GetFileInformationByHandleEx.

§Example

use std::fs;
use std::os::windows::io::AsHandle;

use windows_namespace_request_sys::query::{FileInformationClass, QueryFileInformation};
use windows_namespace_request_sys::CapturedHandle;

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

let request = QueryFileInformation::new(
    CapturedHandle::capture(file.as_handle())?,
    FileInformationClass::BASIC,
)
.with_capacity(256);

// The whole buffer comes back: the call reports no written length, so the
// consumer bounds its own reads rather than trusting a count we invented.
let bytes = request.perform()?;
assert_eq!(bytes.len(), 256);
assert_eq!(bytes.as_ptr() as usize % 8, 0);

Implementations§

Source §

impl QueryFileInformation

Source

pub const DEFAULT_CAPACITY: usize

The capacity a request starts with.

Large enough for any of the fixed-size classes and for a useful batch of directory entries. A caller enumerating a large directory will want more and should say so; this is a starting point, not a recommendation.

Source

pub fn new(handle: CapturedHandle, class: FileInformationClass) -> Self

Begins a request against handle for class.

Source

pub fn with_capacity(self, capacity: usize) -> Self

Sets the buffer size the query is given.

For a fixed-size class this must be at least the size of that class’s structure, and Windows reports ERROR_BAD_LENGTH if it is not. For a directory class it bounds how many entries one call can return, and a buffer too small for even one entry fails with ERROR_MORE_DATA – neither is pre-empted here.

Source

pub fn handle(&self) -> &CapturedHandle

The owned duplicate of the handle being queried.

Source

pub fn class(&self) -> FileInformationClass

The information class this request asks for.

Source

pub fn capacity(&self) -> usize

The buffer size the query will be given.

Source

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

Copies the request, duplicating the handle.

Not Clone, because duplicating a handle is fallible. Note that the copy shares the original’s enumeration cursor, per this module’s measurements – it is a second reference, not a second enumeration.

§Errors

Returns the handle-capture failure when the handle cannot be duplicated.

Source

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

Performs the query on the calling thread.

Returns the whole buffer, 8-byte aligned. The call reports no written length – a batch is walked by its own next-entry offsets – so nothing here invents a byte count it cannot know.

§Errors

Returns the raw Win32 code, unaltered. ERROR_NO_MORE_FILES ends a directory enumeration and ERROR_MORE_DATA means the buffer held no complete entry; both are the caller’s to interpret.