Struct WinHttpPacResolver 

pub struct WinHttpPacResolver { /* private fields */ }

Available on Windows and crate feature pac-windows-native and crate feature pac only.

PAC/WPAD via WinHttpGetProxyForUrlEx. Reuse one session; the cache it does not bound is described on resolve.

Pac / WpadAutoDetect: native fetch; WPAD only after with_wpad(true). PacInline: a JS engine, PacResolver routes it there and the rest here. Direct/Manual: resolve_config. resolve_config answers a hostless URL Direct, except PacInline: that one is Error::PacNotSupported whether or not the URL has a host. resolve does not short-circuit it; see its doc. PacPolicy does not apply: real DNS/local IP.

Implementations

impl WinHttpPacResolver

pub fn new() -> Result<Self, Error>

Open a session with the default DEFAULT_WINHTTP_PAC_TIMEOUT budget.

Errors

Error::Io when WinHttpOpen, WinHttpSetTimeouts or WinHttpSetStatusCallback fails.

pub fn with_timeout(timeout: Duration) -> Result<Self, Error>

Open a session; zero timeout → Error::PacTimeout (not “unlimited”).

Errors

Error::Io (WinHttpOpen / SetTimeouts / SetStatusCallback) or Error::PacTimeout when timeout is zero.

pub fn timeout(&self) -> Duration

The per-resolution budget.

pub fn with_wpad(self, wpad: bool) -> Self

Allow WPAD discovery. Off by default: discovery asks the local network where the PAC script is, and whoever answers for wpad or DHCP option 252 there chooses the proxy. Off, WpadAutoDetect with a host and the AutoDetect / AutoDetectThenUrl sources are Error::PacNotSupported; a hostless URL is still Direct.

pub fn wpad(&self) -> bool

Whether WPAD discovery is allowed.

pub fn reset_auto_proxy(&self) -> Result<AutoProxyReset, Error>

Flush what the WinHTTP autoproxy service remembers (discovered and downloaded scripts, and the WPAD misses) so that the next resolution discovers and downloads afresh. Call it after the network changes.

This is WinHttpResetAutoProxy with WINHTTP_RESET_ALL | WINHTTP_RESET_OUT_OF_PROC. The cache it clears belongs to the service, not to this resolver, so the reset is machine-wide: every process that resolves through the service fetches again. Opening a new resolver does not do this; the service outlives the session.

Microsoft documents that a reset within 30 seconds of the previous one returns success and does nothing. A call inside that window is therefore not made, and AutoProxyReset::TooSoon says how long to wait. The window counts resets made through this crate in this process; one made by another process is invisible here, and a reset requested right after it can still be dropped by the service.

Windows 8 / Server 2012 or later.

Errors

Error::Io when WinHttpResetAutoProxy fails.

pub fn resolve( &self, url: &Url, source: &WinHttpPacSource, ) -> Result<Vec<ProxyStep>, Error>

Resolve url via source. Full FindProxyForURL chain → ProxySteps (HTTP/HTTPS/SOCKS4; fProxy == FALSE → Direct; FTP skipped; repeats collapse, as in parse_find_proxy_result, so the chain can be shorter than the entry count WinHTTP reported).

WinHTTP splits the script’s result itself, and its answers differ from parse_find_proxy_result’s wherever the result is spaced or split unusually. Among them: PROXY\u{a0}a:1 is a:1 here (a no-break space ends the keyword), PROXY a:1\r\nPROXY b:2 has no b:2 (a line break does not separate candidates), and nothing past the first DIRECT arrives, so PROXY a:1; DIRECT; PROXY b:2 has no b:2 either.

ERROR_WINHTTP_AUTODETECTION_FAILED → [Direct], but only from a source that asked for auto-detect. Download / script failure (and that same code from a URL-only source, where there was nothing to discover) stays an error.

A hostless URL (mailto:, data:) is passed to FindProxyForURL with an empty host, as in pac::evaluate. resolve_config returns Direct for hostless URLs without evaluation because it resolves a whole configuration; this method evaluates the source selected by the caller.

Asking twice can be answered once. What WinHTTP caches is the autoproxy URL and the script; a repeat resolution re-runs that script rather than fetching it again, and a WPAD miss is remembered for as long as the session lives. The call that would bypass the cache is not made: it hands the user’s credentials to whatever WPAD found. Dropping the resolver does not flush it: WinHttpGetProxyForUrlEx “always executes out-of-process”, and with that service active Microsoft’s AutoProxy Cache topic puts the cached URL and script “available to the whole computer”: typically until the machine’s IP address changes. reset_auto_proxy flushes it, machine-wide. Unlike ProxyConfig the result carries no capture time to say which fetch it came from.

A PacTimeout cancels the resolution without finishing it: the abandoned operation goes on draining behind this session, and a retry issued at once can spend its own budget waiting behind that rather than on the script. Widen the timeout or wait before retrying.

Errors

Error::PacNotSupported for an auto-detect source without with_wpad(true), Error::PacTimeout, Error::PacEvaluation (ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT), Error::PacInvalidResult, Error::Io (incl. undownloadable PAC URL).

pub fn resolve_config( &self, config: &ProxyConfig, url: &Url, ) -> Result<Vec<ProxyStep>, Error>

Like resolve_with_pac but WinHTTP fetches the script. Direct/Manual → resolve; hostless → Direct except PacInline → Error::PacNotSupported.

WpadAutoDetect may re-read the live registry for PAC URL / static fallback: not a pure function of config alone.

Errors

Error::PacNotSupported for PacInline, and for WpadAutoDetect with a host unless with_wpad(true), plus resolve’s errors and, for the Direct/Manual arm this hands over, resolve’s, which is where Error::ProxyEntryUnusable comes from.

Trait Implementations

impl Debug for WinHttpPacResolver

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

Formats the value using the given formatter.