pub struct WinHttpPacResolver { /* private fields */ }pac-windows-native and crate feature pac only.Expand description
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§
Source§impl WinHttpPacResolver
impl WinHttpPacResolver
Sourcepub fn new() -> Result<Self, Error>
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.
Sourcepub fn with_timeout(timeout: Duration) -> Result<Self, Error>
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.
Sourcepub fn with_wpad(self, wpad: bool) -> Self
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.
Sourcepub fn reset_auto_proxy(&self) -> Result<AutoProxyReset, Error>
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.
Sourcepub fn resolve(
&self,
url: &Url,
source: &WinHttpPacSource,
) -> Result<Vec<ProxyStep>, Error>
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).
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).
Sourcepub fn resolve_config(
&self,
config: &ProxyConfig,
url: &Url,
) -> Result<Vec<ProxyStep>, Error>
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.