Training
Module
Explore common configuration options - Training
This module discusses configuring and customizing some of the common default settings in Windows clients.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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.
To set or retrieve Internet options complete the following:
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:
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.
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.
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.
The HINTERNET handle used to set or retrieve Internet options determines the actions for which the options are valid.
These handles have three levels:
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. |
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);
Internet options can be retrieved using the InternetQueryOption function. To retrieve Internet options:
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.
Allocate a memory for the buffer.
char *lpszData;
lpszData = new char[dwSize];
Retrieve the data.
InternetQueryOption( NULL,
INTERNET_OPTION_USER_AGENT,
lpszData, &dwSize );
Free the memory.
delete [] lpszData;
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;
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:
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;
}
In Internet Explorer 5 and later, Internet options can be retrieved from a specific connection. To retrieve options from a particular connection:
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).
Training
Module
Explore common configuration options - Training
This module discusses configuring and customizing some of the common default settings in Windows clients.