Share via

Option Flags

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

The following table shows the options supported by InternetQueryOption and InternetSetOption. All valid option flags have a value greater than or equal to INTERNET_FIRST_OPTION and less than or equal to INTERNET_LAST_OPTION.

Constant Description

INTERNET_OPTION_BYPASS_EDITED_ENTRY

Sets or retrieves the Boolean value that determines if the system should check the network for newer content and overwrite edited cache entries if a newer version is found. If set to TRUE, the system will check the network for newer content and overwrite the edited cache entry with the newer version. The default is FALSE, which indicates that the edited cache entry should be used without checking the network. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CACHE_ENTRY_ABORT

Indicates that WinInet should cancel a download in progress, causing it to stop writing to the temporary cache file and leaving download control to the browser without consuming unnecessary space. This option is sent to WinInet by URLMON via the PreventCacheEntryWrite() method.

External download agents need to set this option in order to ensure that the entry is not growing in parallel, if they chose to handle their own download.

It is important to note that, after a download is complete, the cache entry is not deleted automatically. It is necessary to call delete it, even if the entry is small. External download handlers should call DeleteUrlCacheEntry to delete the cache entry if the download is aborted.

INTERNET_OPTION_CACHE_TIMESTAMPS

Retrieves an INTERNET_CACHE_TIMESTAMPS structure that contains the LastModified time and Expires time from the resource stored in the Internet cache. This value is used by InternetQueryOption. Surprised.

INTERNET_OPTION_CALLBACK

Sets or retrieves the address of the callback function defined for this handle. This option can be used on all HINTERNET handles and is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CLIENT_CERT_CONTEXT

This flag is not supported by InternetQueryOption. The LPVOID(lpBuffer) parameter must be a pointer to a CERT CONTEXT structure and not a pointer to a CERT CONTEXT pointer. If an application receives ERROR_INTERNET_CLIENT_AUTH_CERT_NEEDED, it must call InternetErrorDlg or use InternetSetOption to supply a certificate before retrying the request. CertDuplicateCertificateContext is then called so that the certificate context passed can be independently released by the application.

INTERNET_OPTION_CONNECT_RETRIES

Sets or retrieves an unsigned long integer value that contains the number of times the WinInet API will attempt to resolve and connect to a host. WinInet will only attempt once per IP address. For example, if you attempt to connect to a multihome host that has ten IP addresses and INTERNET_OPTION_CONNECT_RETRIES is set to seven, WinInet will only attempt to resolve and connect to the first seven IP address. Conversely, given the same set of ten IP addresses, if INTERNET_OPTION_CONNECT_RETRIES is set to 20, WinInet will attempt each of the ten only once. If a host has only one IP address and the first connection attempt fails, there will be no further attempts. If a connection attempt still fails after the specified number of attempts, the request is canceled. The default value for INTERNET_OPTION_CONNECT_RETRIES is five attempts. This option can be used on any HINTERNET handle, including a NULL handle. It is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONNECT_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value to use for Internet connection requests. Units are in milliseconds. If a connection request takes longer than this time-out value, the request is canceled. When attempting to connect to multiple IP addresses for a single host (a multihome host), the timeout limit is cumulative for all of the IP addresses. This option can be used on any HINTERNET handle, including a NULL handle. It is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONNECTED_STATE

Sets or retrieves an unsigned long integer value that contains the connected state. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_CONTEXT_VALUE

Sets or retrieves a DWORD_PTR that contains the address of the context value associated with this HINTERNET handle. This option can be used on any HINTERNET handle. This is used by InternetQueryOption and InternetSetOption. Previously, this set the context value to the address stored in the DWORD(lpBuffer) pointer. This has been corrected so that the value stored in the buffer will be used and the INTERNET_OPTION_CONTEXT_VALUE flag will be assigned a new value. The old value, 10, has been preserved so that applications written for the old behavior are still supported.

INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to receive a response to a request. If the response takes longer than this time-out value, the request is canceled.

This option is supported only during connection establishment and will be ignored if the device is in a connected state. If, for example, the server does not respond to the POST done via HttpSendRequest, InternetReadFile will hang forever waiting for a response from the server and will ignore the OEM specified timeout value.

This option can be used on any HINTERNET handle, including a NULL handle. It is used by InternetQueryOption and InternetSetOption.

For using WinInet synchronously, only the default value for this flag can be changed by calling InternetSetOption and passing NULL in the hInternet parameter.

INTERNET_OPTION_CONTROL_SEND_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to send a request. If the send takes longer than this time-out value, the send is canceled.

This option is supported only during connection establishment and will be ignored if the device is in a connected state. If, for example, the server does not respond to the POST done via HttpSendRequest, InternetReadFile will hang forever waiting for a response from the server and will ignore the OEM specified timeout value.

This option can be used on any HINTERNET handle, including a NULL handle. It is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_DATA_SEND_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to send a request. If the send takes longer than this time-out value, the send is canceled.

This option is supported only if the connection is established, and will be ignored if the device is in an unconnected state.

INTERNET_OPTION_DATA_RECEIVE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to receive a response to a request. If the response takes longer than this time-out value, the request is canceled.

This option is supported only if the connection is established, and will be ignored if the device is in an unconnected state.

INTERNET_OPTION_DATAFILE_NAME

Retrieves a string value that contains the name of the file backing a downloaded entity. This flag is valid after InternetOpenUrl, FtpOpenFile, or HttpOpenRequest has completed. It is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_DIGEST_AUTH_UNLOAD

Causes the system to log off the digest authentication SSPI package, purging all of the credentials created for the process. No buffer is required for this option. It is used by InternetSetOption.

INTERNET_OPTION_END_BROWSER_SESSION

Flushes entries not in use from the password cache on the hard drive. It also resets the cache time used when the synchronization mode is once-per-session. No buffer is required for this option. This is used by InternetSetOption.

INTERNET_OPTION_ERROR_MASK

Sets an unsigned long integer value that contains the error masks that can be handled by the client application. This can be a combination of the INTERNET_ERROR_MASK values described in this table.

INTERNET_ERROR_MASK_COMBINED_SEC_CERT

Indicates that the client application can handle security certificate error codes.

INTERNET_ERROR_MASK_INSERT_CDROM

Indicates that the client application can handle the ERROR_INTERNET_INSERT_CDROM error code.

INTERNET_ERROR_MASK_LOGIN_FAILURE _DISPLAY_ENTITY_BODY

Indicates that the client application can handle the ERROR_INTERNET_LOGIN_FAILURE_DISPLAY_ENTITY_BODY error code.

INTERNET_OPTION_EXTENDED_ERROR

Retrieves an unsigned long integer value that contains a Windows Sockets error code that was mapped to the ERROR_INTERNET_ error messages last returned in this thread context. This option is used on a NULLHINTERNET handle by InternetQueryOption.

INTERNET_OPTION_FROM_CACHE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the amount of time the system should wait for a response to a network request before checking the cache for a copy of the resource. If a network request takes longer than the time specified and the requested resource is available in the cache, the resource will be retrieved from the cache. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_HANDLE_TYPE

Retrieves an unsigned long integer value that contains the type of the HINTERNET handles passed in. This is used by InternetQueryOption on any HINTERNET handle. Possible return values include:

  • INTERNET_HANDLE_TYPE_CONNECT_FTP
  • INTERNET_HANDLE_TYPE_CONNECT_HTTP
  • INTERNET_HANDLE_TYPE_FILE_REQUEST
  • INTERNET_HANDLE_TYPE_FTP_FILE
  • INTERNET_HANDLE_TYPE_FTP_FILE_HTML
  • INTERNET_HANDLE_TYPE_FTP_FIND
  • INTERNET_HANDLE_TYPE_FTP_FIND_HTML
  • INTERNET_HANDLE_TYPE_HTTP_REQUEST
  • INTERNET_HANDLE_TYPE_INTERNET

INTERNET_OPTION_HTTP_VERSION

Sets or retrieves an HTTP_VERSION_INFO structure that contains the HTTP version being supported. This must be used on a NULL handle. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_IGNORE_OFFLINE

Sets or retrieves whether the global offline flag should be ignored. No buffer is required for this option. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_MAX_CONNS_PER_1_0_SERVER

Sets or retrieves an unsigned long integer value that contains the maximum number of connections allowed per HTTP/1.0 server. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_MAX_CONNS_PER_SERVER

Sets or retrieves an unsigned long integer value that contains the maximum number of connections allowed per server. This is used by InternetQueryOption and InternetSetOption. This value was introduced in Internet Explorer 5.

INTERNET_OPTION_PARENT_HANDLE

Retrieves the parent handle to this handle. This option can be used on any HINTERNET handle by InternetQueryOption.

INTERNET_OPTION_PASSWORD

Sets or retrieves a string value that contains the password associated with a handle returned by InternetConnect. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_PER_CONNECTION_OPTION

Sets or retrieves an INTERNET_PER_CONN_OPTION_LIST structure that specifies a list of options for a particular connection. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_PROXY

Sets or retrieves an INTERNET_PROXY_INFO structure that contains the proxy information on an existing InternetOpen handle when the HINTERNET handle is not NULL. If the HINTERNET handle is NULL, the function sets or queries the global proxy information. This option can be used on the HINTERNET handle returned by InternetOpen. It is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_PROXY_PASSWORD

Sets or retrieves a string value that contains the password currently being used to access the proxy. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_PROXY_USERNAME

Sets or retrieves a string value that contains the user name currently being used to access the proxy. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_READ_BUFFER_SIZE

Sets or retrieves an unsigned long integer value that contains the size of the read buffer. This option can be used on HINTERNET handles returned by FtpOpenFile, FtpFindFirstFile, and InternetConnect (FTP session only). This option is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_RECEIVE_THROUGHPUT

Not currently implemented.

INTERNET_OPTION_RECEIVE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to receive a response to a request. If the response takes longer than this time-out value, the request is canceled.

This option is supported only during connection establishment and will be ignored if the device is in a connected state. For example, if the server does not respond to the POST done via HttpSendRequest, InternetReadFile will hang forever waiting for a response from the server and ignoring the OEM specified timeout value.

This option can be used on any HINTERNET handle, including a NULL handle. It is used by InternetQueryOption and InternetSetOption.

For using WinInet synchronously, only the default value for this flag can be changed by calling InternetSetOption and passing NULL in the hInternet parameter.

INTERNET_OPTION_REFRESH

Causes the proxy information to be reread from the registry for a handle. No buffer is required. This option can be used on the HINTERNET handle returned by InternetOpen. It is used by InternetSetOption.

INTERNET_OPTION_REQUEST_FLAGS

Retrieves an unsigned long integer value that contains the special status flags that indicate the status of the download currently in progress. This is used by InternetQueryOption. The INTERNET_OPTION_REQUEST_FLAGS option can be one of the following values:

  • INTERNET_REQFLAG_CACHE_WRITE_DISABLED
    Internet request cannot be cached (an HTTPS request, for example).
  • INTERNET_REQFLAG_FROM_CACHE
    Response came from the cache.
  • INTERNET_REQFLAG_NET_TIMEOUT
    Internet request timed out.
  • INTERNET_REQFLAG_NO_HEADERS
    Original response contained no headers.
  • INTERNET_REQFLAG_VIA_PROXY
    Request was made through a proxy.

INTERNET_OPTION_REQUEST_PRIORITY

Sets or retrieves an unsigned long integer value that contains the priority of requests competing for a connection on an HTTP handle. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_RESET_URLCACHE_SESSION

Starts a new cache session for the process. No buffer is required. This is used by InternetSetOption.

INTERNET_OPTION_SECONDARY_CACHE_KEY

Sets or retrieves a string value that contains the secondary cache key. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_SECURITY_CERTIFICATE

Retrieves the certificate for an SSL/TLS (Secure Sockets Layer/Transport Layer Security) server into a formatted string. This is used by InternetQueryOption.

INTERNET_OPTION_SECURITY_CERTIFICATE_STRUCT

Retrieves the certificate for an SSL/TLS server into the INTERNET_CERTIFICATE_INFO structure. This is used by InternetQueryOption.

INTERNET_OPTION_SECURITY_FLAGS

Retrieves an unsigned long integer value that contains the security flags for a handle. This option is used by InternetQueryOption. It can be a combination of these values:

  • SECURITY_FLAG_128BIT
    Identical to the preferred value SECURITY_FLAG_STRENGTH_STRONG. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_40BIT
    Identical to the preferred value SECURITY_FLAG_STRENGTH_WEAK. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_56BIT
    Identical to the preferred value SECURITY_FLAG_STRENGTH_MEDIUM. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_FORTEZZA
    Helps to provide secrecy, authentication, and/or integrity for the specified connection.
  • SECURITY_FLAG_IGNORE_CERT_CN_INVALID
    Ignores the ERROR_INTERNET_SEC_CERT_CN_INVALID error message.
  • SECURITY_FLAG_IGNORE_CERT_DATE_INVALID
    Ignores the ERROR_INTERNET_SEC_CERT_DATE_INVALID error message.
  • SECURITY_FLAG_IGNORE_REDIRECT_TO_HTTP
    Ignores the ERROR_INTERNET_HTTPS_TO_HTTP_ON_REDIR error message.
  • SECURITY_FLAG_IGNORE_REDIRECT_TO_HTTPS
    Ignores the ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR error message.
  • SECURITY_FLAG_IGNORE_REVOCATION
    Ignores certificate revocation problems.
  • SECURITY_FLAG_IGNORE_UNKNOWN_CA
    Ignores unknown certificate authority problems.
  • SECURITY_FLAG_IGNORE_WRONG_USAGE
    Ignores incorrect usage problems.
  • SECURITY_FLAG_NORMALBITNESS
    Identical to the value SECURITY_FLAG_STRENGTH_WEAK. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_SECURE
    Uses transfers that use security functionality. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_STRENGTH_MEDIUM
    Uses medium (56-bit) encryption. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_STRENGTH_STRONG
    Uses strong (128-bit) encryption. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_STRENGTH_WEAK
    Uses weak (40-bit) encryption. This is only returned in a call to InternetQueryOption.
  • SECURITY_FLAG_UNKNOWNBIT
    The bit size used in the encryption is unknown. This is only returned in a call to InternetQueryOption.

INTERNET_OPTION_SECURITY_KEY_BITNESS

Retrieves an unsigned long integer value that contains the bit size of the encryption key. The larger the number, the greater the encryption strength being used. This is used by InternetQueryOption.

INTERNET_OPTION_SEND_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to send a request. If the send takes longer than this time-out value, the send is canceled.

This option can be used on any HINTERNET handle, including a NULL handle. It is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_SERVER_CERT_CONTEXT

Retrieves a PCCERT_CONTEXT structure that contains the server certificate information. The CertFreeCertificateContext method must be called to free the context.

INTERNET_OPTION_SETTINGS_CHANGED

Informs the system that the registry settings have been changed so that it will check the settings on the next call to InternetConnect. This is used by InternetSetOption.

INTERNET_OPTION_URL

Retrieves a string value that contains the full URL of a downloaded resource. If the original URL contained any extra information, such as search strings or anchors, or if the call was redirected, the URL returned will differ from the original. This option is valid on HINTERNET handles returned by InternetOpenUrl, FtpOpenFile, or HttpOpenRequest. It is used by InternetQueryOption.

INTERNET_OPTION_USER_AGENT

Sets or retrieves the user agent string on handles supplied by InternetOpen and used in subsequent HttpSendRequest functions, as long as it is not overridden by a header added by HttpAddRequestHeaders or HttpSendRequest. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_USERNAME

Sets or retrieves a string that contains the user name associated with a handle returned by InternetConnect. This is used by InternetQueryOption and InternetSetOption.

INTERNET_OPTION_VERSION

Retrieves an INTERNET_VERSION_INFO structure that contains the version number of Wininet.dll. This option can be used on a NULLHINTERNET handle by InternetQueryOption.

INTERNET_OPTION_WRITE_BUFFER_SIZE

Sets or retrieves an unsigned long integer value that contains the size of the write buffer. This option can be used on HINTERNET handles returned by FtpOpenFile and InternetConnect (FTP session only). It is used by InternetQueryOption and InternetSetOption.

Requirements

Header wininet.h
Windows Embedded CE Windows CE 2.12 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

WinInet Constants