How to programmatically query and set proxy settings under Internet Explorer (226473)


The information in this article applies to:

  • Microsoft Internet Explorer (Programming) 4.0
  • Microsoft Internet Explorer (Programming) 4.01
  • Microsoft Internet Explorer (Programming) 4.01 SP1
  • Microsoft Internet Explorer (Programming) 5
  • Microsoft Windows Internet Services (WinInet)
This article was previously published under Q226473

SUMMARY

The article explains the steps neccessary to programmatically query and set the proxy setting information for Internet Explorer.

Under Internet Explorer 4.x and earlier, the InternetSetOption and InternetQueryOption APIs are used with the INTERNET_OPTION_PROXY flag. While this option will still work under Internet Explorer 5, multiple connection options have been introduced in the new version. Given this, the INTERNET_OPTION_PROXY flag will return only the "static" proxy server setting. The static option is the proxy server information stored under the HKEY_CURRENT_USER hive much the same way it was under Internet Explorer 4.0

Note INTERNET_OPTION_PROXY does not permanently change the settings. It does this for the current process only when a NULL handle is used. However, it can also change the settings on a per session basis if a valid session handle is sent in (session handles are obtained using the InternetOpen() API).

If under Internet Explorer 5, you specified a different connection option (such as a dial up connection) as the default, it possible that the proxy information you obtain using the INTERNET_OPTION_PROXY flag may be incorrect for the current Internet Explorer session. For this reason, under Internet Explorer 5, it is recommended that the INTERNET_OPTION_PER_CONNECTION_OPTION be used instead.

Note INTERNET_OPTION_PER_CONNECTION_OPTION causes the settings to be changed on a system-wide basis when a NULL handle is used. To correctly reflect global proxy settings, you must call the InternetSetOption function with the INTERNET_OPTION_REFRESH option flag. Or, to set the settings on a per session basis, a valid session handle can be used.

Note It is still possible to change proxy information for the whgke process without affecting global machine settings in Internet Explorer 5 and later versions. To do this, you must call the InternetSetOption function on the handle that is returned by the InternetOpen function by using the INTERNET_OPTION_PER_CONNECTION_OPTION option. The following code example changes the proxy for the whole process even though the hInternet handle is closed and is not used for the actual request. 
HINTERNET hInternet = InternetOpen(szAppName, INTERNET_OPEN_TYPE_DIRECT, NULL, NULL, 0);
InternetSetOption(hInternet, INTERNET_OPTION_PER_CONNECTION_OPTION, ...); 
InternetCloseHandle (hInternet);

MORE INFORMATION

Under Internet Explorer 4.x, a typical mechanism to query the proxy information would look something like this:
unsigned long        nSize = 4096;
char                 szBuf[4096] = { 0 };
INTERNET_PROXY_INFO* pInfo = (INTERNET_PROXY_INFO*)szBuf;

if(!InternetQueryOption(NULL, INTERNET_OPTION_PROXY, pInfo, &nSize))
   printf("InternetQueryOption failed! (%d)\n", GetLastError());
Under Internet Explorer 5, the recommended way is to use code similar to below: 
INTERNET_PER_CONN_OPTION_LIST    List;
INTERNET_PER_CONN_OPTION         Option[5];
unsigned long                    nSize = sizeof(INTERNET_PER_CONN_OPTION_LIST);

Option[0].dwOption = INTERNET_PER_CONN_AUTOCONFIG_URL;
Option[1].dwOption = INTERNET_PER_CONN_AUTODISCOVERY_FLAGS;
Option[2].dwOption = INTERNET_PER_CONN_FLAGS;
Option[3].dwOption = INTERNET_PER_CONN_PROXY_BYPASS;
Option[4].dwOption = INTERNET_PER_CONN_PROXY_SERVER;

List.dwSize = sizeof(INTERNET_PER_CONN_OPTION_LIST);
List.pszConnection = NULL;
List.dwOptionCount = 5;
List.dwOptionError = 0;
List.pOptions = Option;

if(!InternetQueryOption(NULL, INTERNET_OPTION_PER_CONNECTION_OPTION, &List, &nSize))
   printf("InternetQueryOption failed! (%d)\n", GetLastError());
   if(Option[0].Value.pszValue != NULL)
   printf("%s\n", Option[0].Value.pszValue);

if((Option[2].Value.dwValue & PROXY_TYPE_AUTO_PROXY_URL) == PROXY_TYPE_AUTO_PROXY_URL)
  printf("PROXY_TYPE_AUTO_PROXY_URL\n");

if((Option[2].Value.dwValue & PROXY_TYPE_AUTO_DETECT) == PROXY_TYPE_AUTO_DETECT)
   printf("PROXY_TYPE_AUTO_DETECT\n");

INTERNET_VERSION_INFO      Version;
nSize = sizeof(INTERNET_VERSION_INFO);

InternetQueryOption(NULL, INTERNET_OPTION_VERSION, &Version, &nSize);

if(Option[0].Value.pszValue != NULL)
   GlobalFree(Option[0].Value.pszValue);

if(Option[3].Value.pszValue != NULL)
   GlobalFree(Option[3].Value.pszValue);

if(Option[4].Value.pszValue != NULL)
   GlobalFree(Option[4].Value.pszValue);
The code above specifies the connection by setting the pszConnection string in the INTERNET_PER_CONN_OPTION_LIST structure. By setting this string to NULL, the configuration information will be retrieved for the default (or LAN) settings.

The first option (Option[0] INTERNET_PER_CONN_AUTOCONFIG_URL) will return the URL specified for auto configuration of the proxy server. The second option (Option[1] INTERNET_PER_CONN_AUTODISCOVERY_FLAG) will detect whether the auto detect option is enabled or not for the connection specified. The third option will determine what combination of flags have been set for this particular connection. The last two options correspond to the same information as retrieved whe INTERNET_OPTION_PROXY was used in Internet Explorer 4.x.

As you also see, the options that can potentially return string values are freed using GlobalFree(). This is because the string buffers are allocated for you by the WININET library, and it's up to the programmer to free up the buffer after using it.

To obtain information for a different connection, simply change the List.pszConnection string to point to the Dial-Up setting entry you're interested it.

Similarly, to set proxy information, you would use the same technique but with InternetSetOption() instead, for example:
INTERNET_PER_CONN_OPTION_LIST    List;
INTERNET_PER_CONN_OPTION         Option[1];
unsigned long                    nSize = sizeof(INTERNET_PER_CONN_OPTION_LIST);

Option[0].dwOption = INTERNET_PER_CONN_PROXY_SERVER;
Option[0].Value.pszValue = "http://myproxy:8080";

List.dwSize = sizeof(INTERNET_PER_CONN_OPTION_LIST);
List.pszConnection = NULL;
List.dwOptionCount = 1;
List.dwOptionError = 0;
List.pOptions = Option;

if(!InternetSetOption(NULL, INTERNET_OPTION_PER_CONNECTION_OPTION, &List, nSize))
   printf("InternetQueryOption failed! (%d)\n", GetLastError());
Once again, the above sample will change the default (or LAN) settings (List.pszConnection == NULL). In the sample, the "static" proxy server information is changed to "http://myproxy" at port 8080. Similarly you can also change the auto configuration URL:

INTERNET_PER_CONN_OPTION_LIST    List;
INTERNET_PER_CONN_OPTION         Option[2];
unsigned long                    nSize = sizeof(INTERNET_PER_CONN_OPTION_LIST);

Option[0].dwOption = INTERNET_PER_CONN_AUTOCONFIG_URL;
Option[0].Value.pszValue = "http://myserver/get_proxy_info.dll";
Option[1].dwOption = INTERNET_PER_CONN_FLAGS;
Option[1].Value.dwValue = PROXY_TYPE_AUTO_PROXY_URL;

List.dwSize = sizeof(INTERNET_PER_CONN_OPTION_LIST);
List.pszConnection = NULL;
List.dwOptionCount = 2;
List.dwOptionError = 0;
List.pOptions = Option;

if(!InternetSetOption(NULL, INTERNET_OPTION_PER_CONNECTION_OPTION, &List, nSize))
   printf("InternetQueryOption failed! (%d)\n", GetLastError());
When you configure Internet Explorer to use a proxy server for HTTP and go direct for other protocols, use the code to follow.

Note The buffer that is passed to INTERNET_PER_CONN_PROXY_SERVER has the settings for each protocol (this code sets only HTTP, and all other protocols use direct connection).

Note The INTERNET_PER_CONN_FLAGS sets the value for both Proxy types (direct and through proxy) in one element of the Option List Array, as shown below in the code.

Note You have to OR these flags in one place. If you place these flags in another List element, they will display correctly (Internet Explorer OPTIONS), but only one of the flags (the first that is set) will work. 
int main(int argc, char * argv[]) 
{ 
char buff[256] = "http=http://itgproxy:80"; 
// To include server for FTP, HTTPS, and so on, use the string
// (ftp=http://itgproxy:80; https=https://itgproxy:80) 
INTERNET_PER_CONN_OPTION_LIST    List; 
INTERNET_PER_CONN_OPTION         Option[3]; 
unsigned long                    nSize = sizeof(INTERNET_PER_CONN_OPTION_LIST); 

Option[0].dwOption = INTERNET_PER_CONN_PROXY_SERVER; 
Option[0].Value.pszValue = buff; 

Option[1].dwOption = INTERNET_PER_CONN_FLAGS; 
Option[1].Value.dwValue = PROXY_TYPE_PROXY; 
Option[1].Value.dwValue |= PROXY_TYPE_DIRECT; 
// This option sets all the possible connection types for the client. 
// This case specifies that the proxy can be used or direct connection is possible.

Option[2].dwOption = INTERNET_PER_CONN_PROXY_BYPASS; 
Option[2].Value.pszValue = "<local>"; 

 

List.dwSize = sizeof(INTERNET_PER_CONN_OPTION_LIST); 
List.pszConnection = NULL; 
List.dwOptionCount = 3; 
List.dwOptionError = 0; 
List.pOptions = Option; 

if(!InternetSetOption(NULL, INTERNET_OPTION_PER_CONNECTION_OPTION, &List, nSize)) 
printf("InternetSetOption failed! (%d)\n", GetLastError()); 

InternetSetOption(NULL, INTERNET_OPTION_REFRESH, NULL,NULL); 
//The connection settings for other instances of Internet Explorer. 

return 0; 

}
In the sample above (again the default or LAN setting), you have to specify the auto proxy configuration URL and set the option flag to enable the auto proxy configuration.

REFERENCES

MSDN WinInet API Documentation, April 1999
Modification Type:MajorLast Reviewed:1/28/2005
Keywords:kbhowto KB226473
©2004 Microsoft Corporation. All rights reserved.