Setting and Retrieving Internet Options

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

Internet options can be set on, or retrieved from, a specified HINTERNET handle or the current settings in Microsoft Internet Explorer.

• Implementation Steps
  • Choosing Internet Options
  • Choosing the HINTERNET Handle
  • Setting or Retrieving the Options
• Scope of HINTERNET Handle
• Setting Individual Options
• Retrieving Individual Options
  • Complete Sample
• Setting Connection Options
• Retrieving Connection Options
• Related topics

Implementation Steps

To set or retrieve Internet options complete the following:

• Choosing Internet Options
• Choosing the HINTERNET Handle
• Setting or Retrieving the Options

Choosing Internet Options

Because there are so many Internet options, choosing the right options is important. Many Internet options affect the behavior of the WinINet functions and Internet Explorer:

For example, you can:

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

For more information and a list of the Internet options, see Option flags.

In Internet Explorer 5 and later, 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 more information and 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. All the handles created through this handle will inherit the options set on this handle.

For example, client applications that require a proxy with authentication, probably do not require setting the proxy user name and password every time the application attempts to access an Internet resource. If all requests on a given connection are handled by the same proxy, setting the proxy user name and password on a connection type HINTERNET handle, that is, a handle created by a call to InternetConnect, would allow any calls derived from this HINTERNET handle to use the same proxy user name and password. Setting the proxy user name and password every time an HINTERNET handle is created by HttpOpenRequest would require extra and unnecessary overhead. Be aware that if the application uses a proxy that requires authentication, it should set the proxy credentials on every new connection.

Setting or Retrieving the Options

When you have determined what Internet options and HINTERNET handle to use, retrieve those Internet options. To set or retrieve options, call either InternetQueryOption or InternetSetOption.

Scope of HINTERNET Handle

The HINTERNET handle used to set or retrieve Internet options determines the actions for which the options are valid.

These 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 WinINet.
• HINTERNET handles that connect to a server (created by a call to InternetConnect)
• HINTERNET handles associated with a resource or enumeration of resources on a particular server.

In addition to the various HINTERNET handles, an application can also use NULL to set or retrieve the default values of the Internet options used by Internet Explorer and the WinINet functions. Setting Internet options when using NULL as the handle changes the default values of the options, which are currently stored in the registry. Client applications should not use registry functions to change the default values of the Internet options, because the implementation of how the options are stored can be altered in the future.

The following table lists the type of HINTERNET handles and the scope 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 affect any operations initiated from this HINTERNET handle, such as file downloads.
INTERNET_HANDLE_TYPE_CONNECT_GOPHER	The option settings for this connection to a Gopher server. These options affect any operations initiated from this HINTERNET handle, such as file downloads. Note: Windows XP and Windows Server 2003 R2 and earlier only.
INTERNET_HANDLE_TYPE_CONNECT_HTTP	The option settings for this connection to an HTTP server. These options affect any operations initiated from this HINTERNET handle, such as file downloads.
INTERNET_HANDLE_TYPE_FILE_REQUEST	The option settings associated 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 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 formatted in HTML.
INTERNET_HANDLE_TYPE_GOPHER_FILE	The option settings associated with this Gopher resource download. Note: Windows XP and Windows Server 2003 R2 and earlier only.
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML	The option settings associated with this Gopher resource download formatted in HTML. Note: Windows XP and Windows Server 2003 R2 and earlier only.
INTERNET_HANDLE_TYPE_GOPHER_FIND	The option settings associated with this search of files on an Gopher server. Note: Windows XP and Windows Server 2003 R2 and earlier only.
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML	The option settings associated with this search of files on an Gopher server formatted in HTML. Note: Windows XP and Windows Server 2003 R2 and earlier only.
INTERNET_HANDLE_TYPE_HTTP_REQUEST	The option settings associated with this HTTP request.
INTERNET_HANDLE_TYPE_INTERNET	The option settings associated with this instance of the WinINet functions.

Setting Individual Options

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

The following example shows how to set the proxy user name and password on a specified HINTERNET handle.

// strUsername is a string buffer of cchMax characters or less.
// It contains the proxy user name.
size_t cchMax = 80;
size_t cchUserLength, cchPasswordLength;
HRESULT hr = StringCchLength(strUsername, cchMax, &cchUserLength);

if (SUCCEEDED(hr))
{
   // hOpen is the HINTERNET handle created by InternetConnect.
   InternetSetOption(hConnect, INTERNET_OPTION_PROXY_USERNAME,
      strUsername, DWORD(cchUserLength)+1);
}
else
{
   // Insert error handling code here.
}

// strPassword is the string buffer that contains the proxy password.
hr = StringCchLength(strPassword, cchMax, &cchPasswordLength);

InternetSetOption(hOpen, INTERNET_OPTION_PROXY_PASSWORD,
    strPassword, DWORD(cchPasswordLength)+1);

Retrieving Individual Options

Internet options can be retrieved using the InternetQueryOption function. To retrieve Internet options:

1. 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 zero.

   DWORD dwSize;
   InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);
   

   The value returned by InternetQueryOption is the amount of memory required to retrieve the information, in bytes.

2. Allocate a memory for the buffer.

   char *lpszData;
   lpszData = new char[dwSize];
   

3. Retrieve the data.

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

4. Free the memory.

   delete [] lpszData;
   

Complete Sample

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

// This call determines the required buffer size.
DWORD dwSize;
InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);

// Allocate the necessary memory.
char *lpszData;
lpszData = new char[dwSize];

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

// Insert code here to use the user agent string data.

// Free the allocated memory.
delete [] lpszData;

Setting Connection Options

In Internet Explorer 5 and later, 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:

1. Create an INTERNET_PER_CONN_OPTION_LIST structure.
2. Allocate the memory for the individual Internet options that you want to set for the connection.
3. Set the options in INTERNET_PER_CONN_OPTION structures.
4. Set the options using InternetSetOption.

The following code example shows how to set proxy data for a LAN connection.

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

    // Fill the list structure.
    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];

    // Ensure that 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 = TEXT("https://proxy:80");

    // Set proxy override.
    list.pOptions[2].dwOption = INTERNET_PER_CONN_PROXY_BYPASS;
    list.pOptions[2].Value.pszValue = TEXT("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

In Internet Explorer 5 and later, Internet options can be retrieved from a specific connection. To retrieve options from a particular connection:

1. Create a INTERNET_PER_CONN_OPTION_LIST structure.
2. Allocate the memory for the individual Internet options to retrieve from the connection.
3. Specify the options using INTERNET_PER_CONN_OPTION structures.
4. Retrieve the options using InternetQueryOption.
5. Utilize the option data.
6. Free the memory, allocated to hold the option data, using the GlobalFree function.

Note

WinINet does not support server implementations. In addition, it should not be used from a service. For server implementations or services use Microsoft Windows HTTP Services (WinHTTP).

Related topics

Handling Authentication

HINTERNET Handles