WinHttpGetProxyForUrlEx function (winhttp.h)
The WinHttpGetProxyForUrlEx function retrieves the proxy data for the specified URL.
Syntax
WINHTTPAPI DWORD WinHttpGetProxyForUrlEx(
[in] HINTERNET hResolver,
[in] PCWSTR pcwszUrl,
[in] WINHTTP_AUTOPROXY_OPTIONS *pAutoProxyOptions,
[in] DWORD_PTR pContext
);
Parameters
[in] hResolver
The WinHTTP resolver handle returned by the WinHttpCreateProxyResolver function.
[in] pcwszUrl
A pointer to a null-terminated Unicode string that contains a URL for which proxy information will be determined.
[in] pAutoProxyOptions
A pointer to a WINHTTP_AUTOPROXY_OPTIONS structure that specifies the auto-proxy options to use.
[in] pContext
Context data that will be passed to the completion callback function.
Return value
A status code indicating the result of the operation.
The following codes may be returned. | Description |
---|---|
|
The operation is continuing asynchronously. |
|
Returned by WinHttpGetProxyForUrlEx when a proxy for the specified URL cannot be located. |
|
An error occurred executing the script code in the Proxy Auto-Configuration (PAC) file. |
|
The type of handle supplied is incorrect for this operation. |
|
The URL is invalid. |
|
The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed. |
|
The PAC file could not be downloaded. For example, the server referenced by the PAC URL may not have been reachable, or the server returned a 404 NOT FOUND response. |
|
The URL of the PAC file specified a scheme other than "http:" or "https:". |
|
Not enough memory was available to complete the requested operation. (Windows error code) |
Remarks
This function implements the Web Proxy Auto-Discovery (WPAD) protocol for automatically configuring the proxy settings for an HTTP request. The WPAD protocol downloads a Proxy Auto-Configuration (PAC) file, which is a script that identifies the proxy server to use for a given target URL. PAC files are typically deployed by the IT department within a corporate network environment. The URL of the PAC file can either be specified explicitly or WinHttpGetProxyForUrlEx can be instructed to automatically discover the location of the PAC file on the local network.
WinHttpGetProxyForUrlEx supports only ECMAScript-based PAC files.
WinHttpGetProxyForUrlEx must be called on a per-URL basis, because the PAC file can return a different proxy server for different URLs. This is useful because the PAC file enables an IT department to implement proxy server load balancing by mapping (hashing) the target URL (specified by the lpcwszUrl parameter) to a certain proxy in a proxy server array.
WinHttpGetProxyForUrlEx caches the autoproxy URL and the autoproxy script when auto-discovery is specified in the dwFlags member of the pAutoProxyOptions structure. For more information, see Autoproxy Cache.
WinHttpGetProxyForUrlEx provides a fully Asynchronous and cancellable API that WinHttpGetProxyForUrl does not. WinHttpGetProxyForUrlEx also provides the application with the full proxy list that was returned by the PAC script allowing the application to better handle failover to "DIRECT" and to understand SOCKS if desired.
WinHttpGetProxyForUrlEx always executes asynchronously and returns immediately with ERROR_IO_PENDING on success. The callback is set by calling WinHttpSetStatusCallback on the hSession provided by WinHttpOpen. Alternately call WinHttpSetStatusCallback on the hResolver provided by WinHttpCreateProxyResolver to have a specific callback for each call.
You must call WinHttpSetStatusCallback before WinHttpCreateProxyResolver. When calling WinHttpSetStatusCallback, use WINHTTP_CALLBACK_FLAG_REQUEST_ERROR | WINHTTP_CALLBACK_FLAG_GETPROXYFORURL_COMPLETE. See WINHTTP_STATUS_CALLBACK for information on the use of the callback.
Once a callback of status WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE is returned, the application can call WinHttpGetProxyResult on the resolver handle used to issue WinHttpGetProxyForUrlEx to receive the results of that call.
If the call fails after returning ERROR_IO_PENDING then a callback of WINHTTP_CALLBACK_STATUS_REQUEST_ERROR will be issued.
This function always executes out-of-process.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 8 [desktop apps only] |
Minimum supported server | Windows Server 2012 [desktop apps only] |
Target Platform | Windows |
Header | winhttp.h |
Library | Winhttp.lib |
DLL | Winhttp.dll |