WinHttpGetProxyForUrl (winhttp)
Last changed: -141.249.133.142

.

Summary:

The WinHttpGetProxyForUrl function retrieves the proxy data for the specified URL.

C# Signature:

"hSession" The WinHTTP session handle returned by the WinHttpOpen function

"lpcwszUrl" A pointer to a null-terminated Unicode string that contains the URL of the HTTP request that the application is preparing to send.</param>

"pAutoProxyOptions" A pointer to a WINHTTP_AUTOPROXY_OPTIONS structure that specifies the auto-proxy options to use.

"pProxyInfo" A pointer to a WINHTTP_PROXY_INFO structure that receives the proxy setting. This structure is then applied to the request handle using the WINHTTP_OPTION_PROXY option.

If the function succeeds, the function returns true. If the function fails, it returns false. For extended error data, call "System.Runtime.InteropServices.Marshal.GetLastWin32Error".

[DllImport("winhttp.dll", SetLastError = true, CharSet = CharSet.Unicode)]
[return: MarshalAs(UnmanagedType.Bool)]
    public static extern Boolean WinHttpGetProxyForUrl(
        IntPtr hsession,
        [MarshalAs(UnmanagedType.LPWStr)] String lpcwszUrl,
        ref WINHTTP_AUTO_PROXY_OPTIONS pAutoProxyOptions,
        out WINHTTP_PROXY_INFO pProxyInfo);

VB Signature:

Declare Function WinHttpGetProxyForUrl Lib "winhttp.dll" (TODO) As TODO

User-Defined Types:

None.

Alternative Managed API:

Do you know one? Please contribute it!

Notes:

Possible error codes include the following:

Error Code - Description

ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR - Returned by WinHttpGetProxyForUrl when a proxy for the specified URL cannot be located.

ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT - An error occurred executing the script code in the Proxy Auto-Configuration (PAC) file.

ERROR_WINHTTP_INCORRECT_HANDLE_TYPE - The type of handle supplied is incorrect for this operation.

ERROR_WINHTTP_INTERNAL_ERROR - An internal error has occurred.

ERROR_WINHTTP_INVALID_URL - The URL is invalid.

ERROR_WINHTTP_LOGIN_FAILURE - The login attempt failed. When this error is encountered, close the request handle with WinHttpCloseHandle. A new request handle must be created before retrying the function that originally produced this error.

ERROR_WINHTTP_OPERATION_CANCELLED - The operation was canceled, usually because the handle on which the request was operating was closed before the operation completed.

ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT - 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.

ERROR_WINHTTP_UNRECOGNIZED_SCHEME - The URL of the PAC file specified a scheme other than "http:" or "https:".

ERROR_NOT_ENOUGH_MEMORY - 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 WinHttpGetProxyForUrl can be instructed to

automatically discover the location of the PAC file on the local network.

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 WinHttpGetProxyForUrl can be instructed to automatically discover the location of the PAC file on the local network.

WinHttpGetProxyForUrl supports only ECMAScript-based PAC files.

WinHttpGetProxyForUrl 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.

WinHttpGetProxyForUrl 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.

Requirements

Minimum supported client: Windows XP, Windows 2000 Professional with SP3 [desktop apps only]

Minimum supported server: Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only]

Tips & Tricks:

Please add some!

Sample Code:

https://msdn.microsoft.com/en-us/library/windows/desktop/aa384122(v=vs.85).aspx

Documentation