HOWTO: Programmatically Query and Set Proxy Settings Under Internet Explorer

ID: Q226473

The information in this article applies to:

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. Or to set the settings on a per session basis, a valid session handle can be used.


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());
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

Additional query words: 


Keywords          : kbIE400 kbIE401 kbIE401sp1 kbIE500 
Version           : WINDOWS:4.0,4.01,4.01 SP1,5.0
Platform          : WINDOWS 
Issue type        : kbhowto

Last Reviewed: May 3, 1999