WinHttpSetDefaultProxyConfiguration function (winhttp.h)

Article
10/13/2021

Important

Use of WinHttpSetDefaultProxyConfiguration is deprecated on Windows 8.1 and newer. Most proxy configurations are not supported by WinHttpSetDefaultProxyConfiguration, nor does it support proxy authentication. Instead, use WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY with WinHttpOpen.

The WinHttpSetDefaultProxyConfiguration function sets the default WinHTTP proxy configuration in the registry.

Syntax

WINHTTPAPI BOOL WinHttpSetDefaultProxyConfiguration(
  [in] WINHTTP_PROXY_INFO *pProxyInfo
);

Parameters

[in] pProxyInfo

A pointer to a variable of type WINHTTP_PROXY_INFO that specifies the default proxy configuration.

Return value

Returns TRUE if successful, or FALSE otherwise. For extended error information, call GetLastError. Among the error codes returned are the following.

Error Code	Description
ERROR_WINHTTP_INTERNAL_ERROR	An internal error has occurred.
ERROR_NOT_ENOUGH_MEMORY	Not enough memory was available to complete the requested operation. (Windows error code)

Remarks

The default proxy configuration set by WinHttpSetDefaultProxyConfiguration can be overridden for an existing WinHTTP session by calling WinHttpSetOption and specifying the WINHTTP_OPTION_PROXY flag. The default proxy configuration can be overridden for a new session by specifying the configuration with the WinHttpOpen function.

The dwAccessType member of the WINHTTP_PROXY_INFO structure pointed to by pProxyInfo should be set to WINHTTP_ACCESS_TYPE_NAMED_PROXY if a proxy is specified. Otherwise, it should be set to WINHTTP_ACCESS_TYPE_DEFAULT_PROXY.

Any new sessions created after calling this function use the new default proxy configuration.

Even when WinHTTP is used in asynchronous mode (that is, when WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates synchronously. The return value indicates success or failure. To get extended error information, call GetLastError.

Note For Windows XP and Windows 2000, see the Run-Time Requirements section of the WinHTTP start page.

Examples

The following code example shows how to set the default proxy configuration in the registry.

WINHTTP_PROXY_INFO proxyInfo;

// Allocate memory for string members.
proxyInfo.lpszProxy = new WCHAR[25];
proxyInfo.lpszProxyBypass = new WCHAR[25];

// Set the members of the proxy info structure.
proxyInfo.dwAccessType = WINHTTP_ACCESS_TYPE_NAMED_PROXY;
swprintf_s(proxyInfo.lpszProxy, 25, L"proxy_server");
swprintf_s(proxyInfo.lpszProxyBypass, 25, L"<local>");

// Set the default proxy configuration.
if (WinHttpSetDefaultProxyConfiguration( &proxyInfo ))
    printf("Proxy Configuration Set.\n");

// Free memory allocated to the strings.
delete [] proxyInfo.lpszProxy;
delete [] proxyInfo.lpszProxyBypass;

Requirements

Requirement	Value
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]
Target Platform	Windows
Header	winhttp.h
Library	Winhttp.lib
DLL	Winhttp.dll
Redistributable	WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000.

Share via