Setting and Retrieving Internet Options

This tutorial describes how to set and retrieve Internet options using the Win32 Internet functions InternetSetOption and InternetQueryOption.

Internet options can be set on or retrieved from a specified HINTERNET handle or Microsoft® Internet Explorer's current settings.

Requirements and Dependencies

Application developers who want to set and retrieve Internet options programatically must have an understanding of C/C++ programming, a familiarity with Win32 programming, a familiarity with the Win32 Internet functions, and an understanding of the HINTERNET handles.

To compile programs using any of the Win32 Internet functions, make sure the Wininet.h header file is in the include directory and the Wininet.lib library file is in the library directory of the C/C++ compiler you are using.

General Steps

To set or retrieve Internet options using the Win32 Internet functions, you will need to take care of:

Choosing Internet Options

Since there are so many Internet options, choosing the right options can be a little tricky. Many Internet options affect the behavior of the Win32 Internet functions and Microsoft® Internet Explorer. For example, you can:

Handle basic server and proxy authentication by setting usernames and passwords.
Set or retrive the user agent string used by servers to identify the capabilities of the client application or browser.
Retrieve the handle type of the specified HINTERNET handle.

For a list of the Internet options that can be accessed by using the Win32 Internet functions, see the Option Flags page in the Win32 Internet Functions Reference.

Beginning with Internet Explorer 5, some options can be set or retrieved from a specific Internet connection using the INTERNET_PER_CONN_OPTION_LIST and INTERNET_PER_CONN_OPTION structures. For a list of options that can be set or retrieved from a specific Internet connection, see the dwOptions member of the INTERNET_PER_CONN_OPTION structure.

Choosing the HINTERNET handle

The HINTERNET handle used to set or retrieve Internet options determines the scope of the operation.

For example, client applications that need to use a proxy that requires authentication, probably don't want to set the proxy username and password everytime the application tries to access an Internet resource. If all requests to all servers are handled by the same proxy, setting the proxy username and password on a INTERNET_HANDLE_TYPE_INTERNET type HINTERNET handle (in other words, an HINTERNET handle created by a call to InternetOpen) would allow any calls derived from this HINTERNET handle to use the same proxy username and password. Setting the proxy username and password everytime an HINTERNET handle is created by InternetConnect or InternetOpenUrl would require a lot of extra overhead that isn't really necessary.

Setting or Retrieving the Options

Now that you've determined what Internet options and HINTERNET handle you want to use, its time to set or retrieve those Internet options. To set or retrieve options using the Win32 Internet functions, client applications need to call either InternetQueryOption or InternetSetOption. For details on how use them, see:

Scope of HINTERNET Handle

The HINTERNET handle used to set or retrieve Internet options is the determining factor for for what actions the options will be valid for.

In general, HINTERNET handles have three levels:

The root HINTERNET handle (created by a call to InternetOpen) would contain all the Internet options that affect this instance of the Win32 Internet functions.
HINTERNET handles that connect to a server (created by a call to InternetConnect)
HINTERNET handles that are associated with a resource or enumeration of resources on a particluar server.

In addition to the various HINTERNET handles, application can also use NULL to set or retrieve the default values of the Internet options used by Internet Explorer and the Win32 Internet functions. Setting Internet options when using NULL as the handle will change the default values of the options, which is currently stored in the registry. Client applications should not use Microsoft Win32 registry functions to change the default values of the Internet options, since the implementation of how the options are stored may be altered in upcoming versions of the Win32 Internet functions.

The following table lists the type of HINTERNET handles and the scope that of the Internet options associated with them.

Handle Type	Scope
NULL	The default option settings for Internet Explorer.
INTERNET_HANDLE_TYPE_CONNECT_FTP	The option settings for this connection to an FTP server. These options will affect any operations initiated from this HINTERNET handle, like file downloads.
INTERNET_HANDLE_TYPE_CONNECT_GOPHER	The option settings for this connection to a Gopher server. These options will affect any operations initiated from this HINTERNET handle, like file downloads.
INTERNET_HANDLE_TYPE_CONNECT_HTTP	The option settings for this connection to an HTTP server. These options will affect any operations initiated from this HINTERNET handle, like file downloads.
INTERNET_HANDLE_TYPE_FILE_REQUEST	The option settings assocated with this file request.
INTERNET_HANDLE_TYPE_FTP_FILE	The option settings associated with this FTP resource download.
INTERNET_HANDLE_TYPE_FTP_FILE_HTML	The option settings associated with this FTP resource download that is being formatted in HTML.
INTERNET_HANDLE_TYPE_FTP_FIND	The option settings associated with this search of files on an FTP server.
INTERNET_HANDLE_TYPE_FTP_FIND_HTML	The option settings associated with this search of files on an FTP server that is being formatted in HTML.
INTERNET_HANDLE_TYPE_GOPHER_FILE	The option settings associated with this Gopher resource download.
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML	The option settings associated with this Gopher resource download that is being formatted in HTML.
INTERNET_HANDLE_TYPE_GOPHER_FIND	The option settings associated with this search of files on an Gopher server.
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML	The option settings associated with this search of files on an Gopher server that is being formatted in HTML.
INTERNET_HANDLE_TYPE_HTTP_REQUEST	The option settings assocated with this HTTP request.
INTERNET_HANDLE_TYPE_INTERNET	The option settings associated with this instance of the Win32 Internet functions.

Setting Individual Options

After determining the Internet options you want to set and the scope of that you want affected by these options, setting Internet options is pretty easy. All you would need to do is call the InternetSetOption function with desired HINTERNET handle, Internet option flag, and a buffer containing the information you want set.

The following example demonstrates how to set the proxy username and password on a specified HINTERNET handle.

//hOpen is the HINTERNET handle created by Internet Open
//strUsername is a string buffer that contains the proxy username
InternetSetOption(hOpen, INTERNET_OPTION_PROXY_USERNAME, 
    strUsername, strlen(strUsername)+1);

//strPassword is the buffer that contains the proxy password
InternetSetOption(hOpen, INTERNET_OPTION_PROXY_PASSWORD, 
    strPassword, strlen(strPassword)+1);

Retrieving Individual Options

Internet options can be retrieved using the InternetQueryOption function. To retrieve Internet options, do the following steps:

Determine the buffer size necessary to retrieve the Internet option information.
The buffer size can be determined by using NULL for the address of the buffer and passing it a buffer size of 0.
```
DWORD dwSize=0;

InternetQueryOption(NULL,INTERNET_OPTION_USERAGENT,NULL,&dwSize);
```
The value returned by InternetQueryOption will be the amount of memory needed, in TCHAR, to retrieve the information.
Allocate a memory for the buffer.
```
lpszData = new char[dwSize];
```

Retrieve the information.

InternetQueryOption(NULL, INTERNET_OPTION_USERAGENT,lpszData,&dwSize);

Free the memory.
```
delete [] lpszData;
```

Complete Sample

The following is the complete sample used in the previous section. This sample demonstrates how to retrieve the default user agent string.

DWORD dwSize;

//This call determines the buffer size needed
InternetQueryOption(NULL,INTERNET_OPTION_USERAGENT,NULL,&dwSize);

//allocate the necessary memory
lpszData = new char[dwSize];

//Call InternetQueryOption again with the buffer provided
InternetQueryOption(NULL, INTERNET_OPTION_USERAGENT,lpszData,&dwSize);

//Insert code to user the user agent string information

//Free the allocated memory
delete [] lpszData;

Setting Connection Options

Begining with Internet Explorer 5, Internet options can be set for on a specific connection. Previously, all connections shared the same Internet option settings. To set options for a particular connection, you will need to do the following steps:

Create a INTERNET_PER_CONN_OPTION_LIST structure.
Allocate the memory for the individual Internet options that you want to set for the connection.
Set the options in INTERNET_PER_CONN_OPTION structures.
Set the options using InternetSetOption.

The following sample demonstrates how to set proxy information for a LAN connection.

BOOL SetConnectionOptions()
{
    INTERNET_PER_CONN_OPTION_LIST list;
    BOOL    bReturn;
    DWORD   dwBufSize = sizeof(list);

    // fill out list struct
    list.dwSize = sizeof(list);
    
    // NULL == LAN, otherwise connectoid name
    list.pszConnection = NULL;
    
    // set three options      
    list.dwOptionCount = 3;         
    list.pOptions = new INTERNET_PER_CONN_OPTION[3];

    // make sure the memory was allocated
    if(NULL == list.pOptions)
    {
        //return FALSE if the memory wasn't allocated
        return FALSE;
    }

    // set flags
    list.pOptions[0].dwOption = INTERNET_PER_CONN_FLAGS;
    list.pOptions[0].Value.dwValue = PROXY_TYPE_DIRECT | 
        PROXY_TYPE_PROXY;

    // set proxy name
    list.pOptions[1].dwOption = INTERNET_PER_CONN_PROXY_SERVER;
    list.pOptions[1].Value.pszValue = "http://proxy:80";

    // set proxy override
    list.pOptions[2].dwOption = INTERNET_PER_CONN_PROXY_BYPASS;
    list.pOptions[2].Value.pszValue = "local";

    // set the options on the connection
    bReturn = InternetSetOption(NULL, 
        INTERNET_OPTION_PER_CONNECTION_OPTION, &list, dwBufSize);

    //free the allocated memory
    delete [] list.pOptions;

    return bReturn;
}

Retrieving Connection Options

Begining with Internet Explorer 5, Internet options can be retrieved from a specific connection. To retrieve options from a particular connection, you will need to do the following steps:

Create a INTERNET_PER_CONN_OPTION_LIST structure.
Allocate the memory for the individual Internet options that you want to retrieve from the connection.
Specify the options using INTERNET_PER_CONN_OPTION structures.
Retrieve the options using InternetQueryOption.
Utilize the option information.
Free the memory that was allocated to hold the option information using the GlobalFree function.