Expand description
The request path contract: what a caller may name, and what gets stored.
§Duplicated on purpose, for now
This is a second copy of the preparation that ships in
windows-file-enumeration-sys, not a replacement for it. That crate is
released and this one is not, so making it depend here would make it
unpublishable; the copy keeps the working crate untouched while this one is
proven. The de-duplication happens after this branch merges with main, and
is scheduled as a checklist item – it is not a duplicate that nobody
circled back to.
§A resolved path is not a session-independent path
GetFullPathNameW is lexical. It resolves relative components and
./.. and never expands a drive letter, and a drive letter resolves
against the logon session of whatever token is in effect. So a path
prepared on a submitting thread and opened on a worker under a captured
token from another session can name a different device. Preparation closes
the current-directory race; it does not close that one, and nothing here
should be read as implying otherwise.
A request resolves its path when it is built, on the submitting thread. Deferring that to a worker would let the meaning of a relative path change between submission and execution, because the process current directory is shared mutable state that nothing in this crate controls. Resolving early also separates the two concerns cleanly: string resolution happens here, and the privileged open happens later under the captured token.
§Two path families
A \\?\ path is verbatim: Win32 disables path parsing for it, so the crate
stores it code unit for code unit. It is checked for full qualification –
the one property the prefix promises and a caller can get wrong – and
otherwise left alone. Trailing separators and ./.. components are
preserved, because in verbatim form they are literal name components rather
than syntax.
Everything else, including \\.\ device paths, goes through
GetFullPathNameW. Those forms are normalised by Win32, so resolving them
here produces exactly the path a later CreateFileW would have used.
§Why ordinary paths stop at MAX_PATH
Whether CreateFileW accepts a longer ordinary path depends on the host
executable’s longPathAware manifest and on system policy – neither of
which this crate controls, and both of which belong to whoever embeds it.
Letting them decide would make the same call succeed in one host and fail in
another. The crate instead draws the line itself: ordinary paths stop at
MAX_PATH, and a caller who wants a longer one says so explicitly with a
fully qualified \\?\ path, which has never depended on the manifest.
Structs§
- Path
Error - A synchronous failure while preparing a caller’s path.
- Prepared
Path - A path that has been through
prepare: the exact path a worker will open.
Enums§
- Path
Failure - Why a caller’s path could not be prepared.
Functions§
- prepare
- Validate and, where the contract calls for it, resolve a caller’s path.