Crate windows_file_enumeration_sys

Expand description

Windows-only platform layer for asynchronous flat directory enumeration.

One request enumerates one directory. The crate owns bounded submission and completion rings, lossless backpressure, cancellation, submitter security context transport, and a caller-buffered GetFileInformationByHandleEx engine. Recursive traversal belongs in a separate layer that composes these flat requests.

§Native values stay native

Names and paths are native-width WTF-16 (wtf_string), so an ill-formed surrogate a filesystem contains survives the round trip. Times are signed Windows tick counts (WindowsFileTimestamp), attributes are the raw FILE_ATTRIBUTE_* bitmask, and a file ID keeps the record’s exact 16 bytes. Nothing is converted eagerly into a portable shape whose losses a caller could not undo.

§Safety

The public surface is entirely safe: every FFI call the native engine makes is confined to a single caller-owned, size-checked buffer (EnumerationRequest::with_buffer_capacity), and no directory entry is ever opened individually – the engine reads only from the batched GetFileInformationByHandleEx listing of the one directory handle the request named. A submitted enumeration’s security context is captured synchronously on the submitter’s own thread, before the request becomes visible to any worker, so the later directory open always runs as whoever asked for it rather than as the pool. The unsafe internals that make this true – buffer aliasing, handle ownership, and thread-pool callback lifetime – are recorded in DESIGN-NOTES.md and DESIGN-RATIONALE.md.

§Building a predicate

Build a request for one directory, delivering only files larger than 4 KiB whose names end in .log:

use windows_file_enumeration_sys::{
    ComparisonOperator, EntryType, EnumerationRequest, NamePattern, PatternToken,
    PredicateClause, QueryByExample,
};
use wtf_string::Wtf16String;

let suffix = NamePattern::empty()
    .with(PatternToken::AnyRun)
    .with(PatternToken::Literal(Wtf16String::from(".log")));

let query = QueryByExample::new()
    .with(PredicateClause::Name {
        pattern: suffix,
        case: Default::default(),
        negated: false,
    })?
    .with(PredicateClause::IsType {
        entry_type: EntryType::File,
        negated: false,
    })?
    .with(PredicateClause::LogicalSize {
        operator: ComparisonOperator::Greater,
        value: 4096,
    })?;

let request = EnumerationRequest::for_path("C:/logs".as_ref())?.with_predicate(query);

§Running an enumeration

Session::new returns a producing Session and its single Receiver. Session::try_begin captures the caller’s own security context and starts the enumeration; entries and exactly one Completion::Terminal arrive on the receiver, every entry of one enumeration before its terminal:

use windows_file_enumeration_sys::{Completion, EnumerationRequest, Session};

let (session, receiver) = Session::new(8, 8)?;
let request = EnumerationRequest::for_path("C:/logs".as_ref())?;
session.try_begin(request)?.detach();

while let Some(completion) = receiver.recv() {
    match completion {
        Completion::Entry { entry, .. } => println!("{}", entry.name()),
        Completion::Terminal { outcome, .. } => {
            println!("finished: {outcome:?}");
            break;
        }
    }
}

§Traversal-style submission

A recursive traversal layer captures one security context and reuses it for every directory in the tree with Session::try_begin_with_token, instead of paying a fresh capture per directory on whatever thread happens to be submitting:

use windows_file_enumeration_sys::{EnumerationRequest, Session};
use windows_impersonation_token_sys::ImpersonationToken;

let (session, receiver) = Session::new(8, 8)?;
let token = ImpersonationToken::capture()?;

for directory in ["C:/logs", "C:/logs/archive"] {
    let request = EnumerationRequest::for_path(directory.as_ref())?;
    session
        .try_begin_with_token(request, token.clone())?
        .detach();
}

Structs§

BeginError: A synchronous refusal to start an enumeration.
DirectoryEntry: One enumerated directory entry with its full inline metadata.
EnumerationHandle: A live enumeration’s affine handle.
EnumerationId: Identifies one accepted enumeration within a session.
EnumerationRequest: One directory to enumerate, with the predicate and bounds that apply to it.
FileIdentity: A filesystem object’s identity: the record’s 128-bit file ID, optionally qualified by the volume it lives on.
NamePattern: A compiled pattern for one leaf name.
PredicateError: A synchronous failure while building a query.
QueryByExample: A validated conjunction of clauses.
Receiver: The consuming half of a session: the only way to observe completions.
RequestError: A synchronous failure while building an EnumerationRequest.
Session: The producing half of a session.
SessionError: A synchronous failure while building a session.
Win32Error: A raw Win32 error code, kept in the currency it arrived in.
WindowsFileTimestamp: A Windows file time: signed 100-nanosecond ticks since 1601-01-01 UTC.

Enums§

BeginFailure: Why an enumeration was not admitted.
CaseSensitivity: How a name comparison treats case.
ComparisonOperator: How a numeric or timestamp clause compares.
Completion: One record taken from a session’s completion ring.
EntryPredicate: What a request asks of each entry.
EntryType: Whether an entry is a directory or an ordinary file.
EnumerationError: Why an accepted enumeration failed.
FileIdentityMode: How much work a request is willing to do for file identity.
MalformedRecord: Which part of a native directory record failed validation.
PatternToken: One element of a NamePattern.
PredicateClause: One condition an entry must satisfy.
PredicateFailure: Why a query-by-example clause was rejected.
RequestFailure: Why a request could not be built.
SessionFailure: Why a session could not be built.
TerminalOutcome: How one enumeration ended.
TimestampField: Which of an entry’s four times a timestamp clause compares.

Constants§

DEFAULT_BUFFER_CAPACITY: The default native buffer capacity, in bytes.
MINIMUM_BUFFER_CAPACITY: The smallest native buffer capacity, in bytes.
MINIMUM_COMPLETION_RING_CAPACITY: The smallest completion-ring capacity that can carry one enumeration.
MINIMUM_SUBMISSION_CAPACITY: The smallest submission-ring capacity that can carry one enumeration.

Type Aliases§

TokenCaptureError: The capture error behind a BeginFailure::TokenCapture, re-exported so a caller can inspect it without depending on the sibling crate by name.