Edit

Setting WinINet Proxy Configurations in WinHTTP

  • Article

Setting Automatic Proxy on WinHTTP 5.1

Applications that port from WinINet to WinHTTP may need to use the same autoproxy settings that they can retrieve under WinINet or Internet Explorer (IE). The WinHTTP version 5.1 API can retrieve and use these proxy settings. In general, WinHTTP specifies the proxy and proxy bypass servers on a per-session basis when the session is created. These settings can be overridden on a per-request basis.

To use the same proxy configuration as WinINet or IE, the WinHTTP client should set proxy settings for the session. In addition, if IE or WinINet are configured to use Web Proxy Auto-Discovery (WPAD), the WinHTTP client that uses those settings must set proxy settings on a per-request basis. The following sections describe how to specify the proxy settings for a session and a request:

Setting the Proxy Configuration on a Session

The Application is Running on a User Account

Before a session is created, the application calls WinHttpGetIEProxyConfigForCurrentUser to get the IE proxy settings. The application must be running as a user account to obtain these settings. The pProxyConfig parameter is a pointer to a WINHTTP_CURRENT_USER_IE_PROXY_CONFIG structure that contains the proxy name (lpszProxy) and proxy bypass (lpszProxyBypass) servers. The proxy name and proxy bypass values of the WINHTTP_CURRENT_USER_IE_PROXY_CONFIG structure are then used to initialize the WinHTTP session. The session is initialized by calling WinHttpOpen with the pwszProxyName and pwszProxyBypass parameters obtained from the lpszProxy and lpszProxyBypass members of the WINHTTP_CURRENT_USER_IE_PROXY_CONFIG structure.

The Application is Running as a Service

The application must ensure that the registry settings for an individual user are loaded into the registry before calling WinHttpGetIEProxyConfigForCurrentUser. If these settings are not loaded into the registry, WinHttpGetIEProxyConfigForCurrentUser cannot obtain the proxy settings. Registry settings for an individual user can be loaded into the registry by calling the LoadUserProfile function. If loading the user's registry settings is not an option, the application can call WinHttpOpen with the WINHTTP_ACCESS_TYPE_DEFAULT_PROXY specified in the dwAcessType parameter. Specifying the default proxy in the call to WinHttpOpen tells the WinHTTP API to retrieve the proxy configuration set by using the WinHTTP proxycfg.exe utility. After the registry settings for an individual user have been loaded, the application follows the steps outlined under The application is running on a user account to set the proxy name and proxy bypass servers.

Setting the Proxy Configuration on a Single Request

Before the session is created, the application calls WinHttpGetIEProxyConfigForCurrentUser to determine if WinINet and IE are configured to use WPAD. WinHttpGetIEProxyConfigForCurrentUser returns the WINHTTP_CURRENT_USER_IE_PROXY_CONFIG structure that contains the fAutoDetect member. A value of TRUE for this member indicates that WPAD is used, and the lpszAutoConfigUrl member contains the WPAD URL.

Automatic Proxy Configuration Is Used

If WPAD is used, the application calls WinHttpGetProxyForUrl to retrieve the proxy for the request. The lpwszUrl parameter contains the URL that the request is being sent to, and the pAutoProxyOptions parameter contains a pointer to the structure (WINHTTP_AUTOPROXY_OPTIONS) that contains the autoproxy options. The application initializes the WINHTTP_AUTOPROXY_OPTIONS structure with the settings returned from the WINHTTP_CURRENT_USER_IE_PROXY_CONFIG structure in the call to WinHttpGetIEProxyConfigForCurrentUser. The WINHTTP_AUTOPROXY_CONFIG_URL flag is specified in the dwFlags member of the WINHTTP_AUTOPROXY_OPTIONS structure, and the lpszAutoconfigUrl member contains the proxy auto-configuration URL from the WINHTTP_CURRENT_USER_IE_PROXY_CONFIG structure. The WinHttpGetProxyForUrl function returns the proxy name and the proxy bypass list in the lpszProxy and lpszProxyBypass members of the WINHTTP_PROXY_INFO structure.

After the proxy for the request is obtained from WinHttpGetProxyForUrl, the application creates the request with WinHttpOpenRequest. Then WinHttpSetOption is called to set the proxy for the request by specifying the request handle in the hInternet parameter. The dwOption parameter in the call to WinHttpSetOption should be set to WINHTTP_OPTION_PROXY and the lpBuffer parameter is a pointer to a WINHTTP_PROXY_INFO structure that contains the proxy and proxy bypass to be used for the request.

Automatic Proxy Configuration Is Not Used

If the call to WinHttpGetIEProxyConfigForCurrentUser indicates that autoproxy is not used, the application can simply create the request with WinHttpOpenRequest. The proxy configuration is the same for the entire session, and per-request changes are not needed.