The following option flags are supported by WinHttpQueryOption and WinHttpSetOption.

WINHTTP_OPTION_AUTOLOGON_POLICY

Sets an unsigned long integer value that specifies the Automatic Logon Policy with one of the following values.

WINHTTP_AUTOLOGON_SECURITY_LEVEL_HIGH

Default credentials are not used. Note that this flag takes effect only if you specify the server by the actual machine name. It will not take effect, if you specify the server by "localhost" or IP address.

WINHTTP_AUTOLOGON_SECURITY_LEVEL_LOW

An authenticated log on using the default credentials is performed for all requests.

WINHTTP_AUTOLOGON_SECURITY_LEVEL_MEDIUM

An authenticated log on using the default credentials is performed only for requests on the local Intranet.

 

WINHTTP_OPTION_CALLBACK

Retrieves the pointer to the callback function set with WinHttpSetStatusCallback.

WINHTTP_OPTION_CLIENT_CERT_CONTEXT

Sets the client certificate context. If an application receives ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED, it must call WinHttpSetOption to supply a certificate before retrying the request. As a part of processing this option, WinHttp calls CertDuplicateCertificateContext on the caller-provided certificate context so that the certificate context can be independently released by the caller.

Note  The application should not attempt to close the certificate store with the CERT_CLOSE_STORE_FORCE_FLAG flag in the call to CertCloseStore on the certificate store from which the certificate context was retrieved. An access violation may occur.

When the server requests a client certificate, WinHttpSendRequest, or WinHttpReceiveResponse returns an ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED error. If the server requests the certificate but does not require it, the application can specify this option to indicate that it does not have a certificate. The server can choose another authentication scheme or allow anonymous access to the server. The application provides the WINHTTP_NO_CLIENT_CERT_CONTEXT macro in the lpBuffer parameter of WinHttpSetOption as shown in the following code example.

BOOL fRet = WinHttpSetOption ( hRequest,
                               WINHTTP_OPTION_CLIENT_CERT_CONTEXT,
                               WINHTTP_NO_CLIENT_CERT_CONTEXT,
                               0); 

Windows Server 2003 with SP1 and Windows XP with SP2:  The WINHTTP_NO_CLIENT_CERT_CONTEXT macro is not supported.

If the server requires a client certificate, it may send a 403 HTTP status code in response. For more information, see the WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST option.

WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST

Retrieves a SecPkgContext_IssuerListInfoEx structure when the error from WinHttpSendRequest or WinHttpReceiveResponse is ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED. The issuer list in the structure contains a list of acceptable Certificate Authorities (CA) from the server. The client application can filter the CA list to retrieve the client certificate for SSL authentication.

Alternately, if the server requests the client certificate, but does not require it, the application can call WinHttpSetOption with the WINHTTP_OPTION_CLIENT_CERT_CONTEXT option. For more information, see the WINHTTP_OPTION_CLIENT_CERT_CONTEXT option.

Windows Server 2003 with SP1 and Windows XP with SP2:  This flag is not supported.

WINHTTP_OPTION_CODEPAGE

Sets the code page that is used to process the URL (that is, query string). The default is UTF8.

WINHTTP_OPTION_CONFIGURE_PASSPORT_AUTH

Sets an unsigned long integer value that specifies whether Passport Authentication in WinHTTP authentication is enabled. The value can be one of the following:

WINHTTP_DISABLE_PASSPORT_AUTH

Microsoft Passport authentication is disabled. This is the default.

WINHTTP_DISABLE_PASSPORT_KEYRING

The Passport keyring is disabled. This is the default.

WINHTTP_ENABLE_PASSPORT_AUTH

Passport authentication is enabled.

WINHTTP_ENABLE_PASSPORT_KEYRING

The Passport keyring is enabled.

 

WINHTTP_OPTION_CONNECTION_INFO

Retrieves the source and destination IP address, and port of the request that generated the response when WinHttpReceiveResponse returns. The application calls WinHttpSetOption with the WINHTTP_OPTION_CONNECTION_INFO option, and provides the WINHTTP_CONNECTION_INFO structure in the lpBuffer parameter. For more information, see WINHTTP_CONNECTION_INFO.

Windows Server 2003 with SP1 and Windows XP with SP2:  This flag is not supported.

WINHTTP_OPTION_CONNECT_RETRIES

Sets or retrieves an unsigned long integer value that contains the number of times WinHTTP attempts to connect to a host. Microsoft Windows HTTP Services (WinHTTP) only attempts once per Internet Protocol (IP) address. For example, if you attempt to connect to a multihomed host that has 10 IP addresses and WINHTTP_OPTION_CONNECT_RETRIES is set to 7, then WinHTTP only attempts to connect to the first seven IP address. Given the same set of 10 IP addresses, if WINHTTP_OPTION_CONNECT_RETRIES is set to 20, WinHTTP attempts each of the 10 only once. If a connection attempt still fails after the specified number of attempts, or if the connect timeout expired before then, the request is canceled. The default value for WINHTTP_OPTION_CONNECT_RETRIES is five attempts.

WINHTTP_OPTION_CONNECT_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds. Setting this option to infinite (0xFFFFFFFF) will disable this timer.

If a TCP connection request takes longer than this time-out value, the request is canceled. The default timeout is 60 seconds. When you are attempting to connect to multiple IP addresses for a single host (a multihomed host), the timeout limit is for each individual connection.

WINHTTP_OPTION_CONTEXT_VALUE

Sets or retrieves a DWORD_PRT that contains a pointer to the context value associated with this HINTERNET handle. The value stored in the buffer is used and the WINHTTP_OPTION_CONTEXT_VALUE option flag is assigned a new value.

WINHTTP_OPTION_DISABLE_FEATURE

Sets an unsigned long integer value that specifies which features are disabled with one or more of the following flags. Be aware that this feature should only be passed to WinHttpSetOption on request handles after the request handle is created with WinHttpOpenRequest, and before the request is sent with WinHttpSendRequest.

WINHTTP_DISABLE_AUTHENTICATION

Automatic authentication is disabled.

WINHTTP_DISABLE_COOKIES

Automatic addition of cookie headers to requests is disabled. Also, returned cookies are not automatically added to the cookie database. Disabling cookies can result in poor performance for Passport authentication.

WINHTTP_DISABLE_KEEP_ALIVE

Disables keep-alive semantics for the connection. Keep-alive semantics are required for MSN, NTLM, and other types of authentication.

WINHTTP_DISABLE_REDIRECTS

Automatic redirection is disabled when sending requests with WinHttpSendRequest. If automatic redirection is disabled, an application must register a callback function in order for Passport authentication to succeed.

 

WINHTTP_OPTION_ENABLE_FEATURE

Sets an unsigned long integer value that specifies the features currently enabled. Can be one of the following values.

Term	Description
WINHTTP_ENABLE_SSL_REVERT_IMPERSONATION	If enabled, WinHTTP temporarily reverts client impersonation for the duration of SSL certificate authentication operations. This value can be set only on the session handle.
WINHTTP_ENABLE_SSL_REVOCATION	If enabled, WinHTTP allows SSL revocation. This value can be set only on the request handle.

 

 

WINHTTP_OPTION_ENABLETRACING

Sets a BOOL value that specifies whether tracing is currently enabled. For more information about the trace facility in WinHTTP, see WinHTTP Trace Facility. This option can only be set on a NULL HINTERNET handle.

WINHTTP_OPTION_EXTENDED_ERROR

Retrieves an unsigned long integer value that contains a Microsoft Windows Sockets error code that was mapped to the ERROR_WINHTTP_* error messages last returned in this thread context. You can pass NULL as the handle value.

WINHTTP_OPTION_GLOBAL_SERVER_CREDS

Takes a pointer to a WINHTTP_CREDS_EX structure with the hInternet function parameter set to NULL. This option requires registry key HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings!ShareCredsWithWinHttp. If this registry key is not set WinHTTP will return error ERROR_WINHTTP_INVALID_OPTION. This registry key is not present by default. When it is set, WinINet will send credentials down to WinHTTP. Whenever WinHttp gets an authentication challenge and if there are no credentials set on the current handle, it will use the credentials provided by WinINet. In order to share server credentials in addition to proxy credentials, users needs to set WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS .

WINHTTP_OPTION_GLOBAL_PROXY_CREDS

Takes a pointer to a WINHTTP_CREDS_EX structure with the hInternet function parameter set to NULL. This option requires registry key HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings!ShareCredsWithWinHttp. If this registry key is not set WinHTTP will return error ERROR_WINHTTP_INVALID_OPTION. This registry key is not present by default. When it is set, WinINet will send credentials down to WinHTTP. Whenever WinHttp gets an authentication challenge and if there are no credentials set on the current handle, it will use the credentials provided by WinINet. In order to share server credentials in addition to proxy credentials, users needs to set WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS .

WINHTTP_OPTION_HANDLE_TYPE

Retrieves an unsigned long integer value that contains the type of the HINTERNET handle passed in. The return value can be one of the following:

WINHTTP_HANDLE_TYPE_CONNECT

The handle is a connection handle.

WINHTTP_HANDLE_TYPE_REQUEST

The handle is a request handle.

WINHTTP_HANDLE_TYPE_SESSION

The handle is a session handle.

 

WINHTTP_OPTION_HTTP_VERSION

Sets or retrieves an HTTP_VERSION_INFO structure that contains the HTTP version being supported. This is a process-wide option; use NULL for the handle.

WINHTTP_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. The default value is INFINITE.

Windows Server 2008:  This option is obsolete.

WINHTTP_OPTION_MAX_CONNS_PER_SERVER

Sets or retrieves an unsigned long integer value that contains the maximum number of connections allowed per server. The default value is INFINITE.

When this option is set to zero, WinHTTP sets the limit on the number of connections to 2.

WINHTTP_OPTION_MAX_HTTP_AUTOMATIC_REDIRECTS

Sets the maximum number of redirects that WinHTTP follows; the default is 10. This limit prevents unauthorized sites from making the WinHTTP client pause following a large number of redirects.

Windows XP with SP1 and Windows 2000 with SP3:  This flag is not supported.

WINHTTP_OPTION_MAX_HTTP_STATUS_CONTINUE

The maximum number of Informational 100-199 status code responses ignored before returning the final status code to the WinHTTP client. Informational 100-199 status codes can be sent by the server before the final status code, and are described in the specification for HTTP/1.1 (for more information, see RFC 2616). The default is 10.

Windows XP with SP1 and Windows 2000 with SP3:  This flag is not supported.

WINHTTP_OPTION_MAX_RESPONSE_DRAIN_SIZE

A bound on the amount of data drained from responses in order to reuse a connection, specified in bytes. The default is 1MB.

Windows XP with SP1 and Windows 2000 with SP3:  This flag is not supported.

WINHTTP_OPTION_MAX_RESPONSE_HEADER_SIZE

A bound set on the maximum size of the header portion of the server response, specified in bytes. This bound protects the client from an unauthorized server attempting to stall the client by sending a response with an infinite amount of header data. The default value is 64KB.

Windows XP with SP1 and Windows 2000 with SP3:  This flag is not supported.

WINHTTP_OPTION_PARENT_HANDLE

Retrieves the parent handle to this handle.

WINHTTP_OPTION_PASSPORT_COBRANDING_TEXT

Retrieves a string that contains the cobranding text provided by the Passport logon server. This option should be retrieved immediately after the logon server responds with a 401 status code. An application should pass in a buffer size, in bytes, that is big enough to hold the returned string.

WINHTTP_OPTION_PASSPORT_COBRANDING_URL

Retrieves a string that contains a URL for a cobranding graphic provided by the Passport logon server. This option should be retrieved immediately after the logon server responds with a 401 status code. An application should pass in a buffer size, in bytes, that is big enough to hold the returned string.

WINHTTP_OPTION_PASSPORT_RETURN_URL

Sets a read-only option on a request handle that retrieves the Passport return URL.

WINHTTP_OPTION_PASSPORT_SIGN_OUT

Sets the option on a session handle to sign out of any Passport logins. An application should pass in the Passport return URL that was retrieved with WINHTTP_OPTION_PASSPORT_RETURN_URL. All cookies related to the return URL are cleared.

WINHTTP_OPTION_PASSWORD

Sets or retrieves a string value that contains the password associated with a request handle.

WINHTTP_OPTION_PROXY

Sets or retrieves an WINHTTP_PROXY_INFO structure that contains the proxy data on an existing session handle or request handle. When retrieving proxy data, an application must free the lpszProxy and lpszProxyBypass strings contained in this structure (if they are non-NULL) using the GlobalFree function. An application can query for the global proxy data (the default proxy) by passing a NULL handle.

WINHTTP_OPTION_PROXY_PASSWORD

Sets or retrieves a string value that contains the password used to access the proxy.

WINHTTP_OPTION_PROXY_USERNAME

Sets or retrieves a string value that contains the user name used to access the proxy.

WINHTTP_OPTION_READ_BUFFER_SIZE

This option has been deprecated; it has no effect.

WINHTTP_OPTION_RECEIVE_RESPONSE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the timeout value, in milliseconds, to wait to receive all response headers to a request. If WinHTTP fails to receive all the headers within this timeout period, the request is canceled. The default timeout value is 90 seconds.

This timeout is checked only when data is received from the socket. As a result, when the timeout expires the client application is not notified until more data arrives from the server. If no data arrives from the server, the delay between the timeout expiration and notification of the client application could be as large as the timeout value set using the dwReceiveTimeout parameter of the WinHttpSetTimeouts function.

WINHTTP_OPTION_RECEIVE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to receive a partial response to a request or read some data. If the response takes longer than this time-out value, the request is canceled. The default timeout value is 30 seconds.

WINHTTP_OPTION_REDIRECT_POLICY

Sets the behavior of WinHTTP regarding the handling of a 30x HTTP redirect status code. This option can be set on a session or request handle to one of the following values:

Term	Description
WINHTTP_OPTION_REDIRECT_POLICY_ALWAYS	All redirects are followed automatically.
WINHTTP_OPTION_REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP	All redirects are followed, except those that originate from a secure (https) URL to an unsecure (http) URL. This is the default setting.
WINHTTP_OPTION_REDIRECT_POLICY_NEVER	Redirects are never followed. The 30x status is returned to the application.

 

 

WINHTTP_OPTION_REJECT_USERPWD_IN_URL

Rejects URLs that contain a username and password. This option also rejects URLs that contain username:password semantics, even if no username or password is specified. For example, "u:p@hostname", ":@hostname", "u:@hostname", and ":p@hostname" would all be flagged as invalid. If an invalid URL is passed to the function, it returns ERROR_WINHTTP_INVALID_URL. This option is turned off by default.

WINHTTP_OPTION_REQUEST_PRIORITY

This option has been deprecated; it has no effect.

WINHTTP_OPTION_RESOLVE_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to resolve a host name. The default timeout value is INFINITE. If a non-default value is specified, there is an overhead of one thread-creation per name resolution.

WINHTTP_OPTION_SECURE_PROTOCOLS

Sets an unsigned long integer value that specifies which secure protocols are acceptable. By default only SSL3 and TLS1 are enabled. Can by a combination of one or more of the following values.

WINHTTP_FLAG_SECURE_PROTOCOL_ALL

The Secure Sockets Layer (SSL) 2.0, SSL 3.0, and Transport Layer Security (TLS) 1.0 protocols can be used.

WINHTTP_FLAG_SECURE_PROTOCOL_SSL2

The SSL 2.0 protocol can be used.

WINHTTP_FLAG_SECURE_PROTOCOL_SSL3

The SSL 3.0 protocol can be used.

WINHTTP_FLAG_SECURE_PROTOCOL_TLS1

The TLS 1.0 protocol can be used.

 

WINHTTP_OPTION_SECURITY_CERTIFICATE_STRUCT

Retrieves the certificate for a SSL/TLS server into the WINHTTP_CERTIFICATE_INFO structure. The application must free the lpszSubjectInfo and lpszIssuerInfo members with LocalFree.

WINHTTP_OPTION_SECURITY_FLAGS

Sets or retrieves an unsigned long integer value that contains the security flags for a handle. It can be a combination of these values:

SECURITY_FLAG_IGNORE_CERT_CN_INVALID

Allows an invalid common name in a certificate; that is, the server name specified by the application does not match the common name in the certificate. If this flag is set, the application does not receive a WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID callback.

SECURITY_FLAG_IGNORE_CERT_DATE_INVALID

Allows an invalid certificate date, that is, an expired or not-yet-effective certificate. If this flag is set, the application does not receive a WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID callback.

SECURITY_FLAG_IGNORE_UNKNOWN_CA

Allows an invalid certificate authority. If this flag is set, the application does not receive a WINHTTP_CALLBACK_STATUS_FLAG_CERT_INVALID_CA callback.

SECURITY_FLAG_IGNORE_CERT_WRONG_USAGE

Allows the identity of a server to be established with a non-server certificate (for example, a client certificate).

SECURITY_FLAG_SECURE

Uses secure transfers. This is only returned in a call to WinHttpQueryOption.

SECURITY_FLAG_STRENGTH_MEDIUM

Uses medium (56-bit) encryption. This is only returned in a call to WinHttpQueryOption.

SECURITY_FLAG_STRENGTH_STRONG

Uses strong (128-bit) encryption. This is only returned in a call to WinHttpQueryOption.

SECURITY_FLAG_STRENGTH_WEAK

Uses weak (40-bit) encryption. This is only returned in a call to WinHttpQueryOption.

 

WINHTTP_OPTION_SECURITY_KEY_BITNESS

Retrieves an unsigned long integer value that contains the cipher strength of the encryption key. A larger number indicates stronger cipher strength encryption.

WINHTTP_OPTION_SEND_TIMEOUT

Sets or retrieves an unsigned long integer value that contains the time-out value, in milliseconds, to send a request or write some data. If sending the request takes longer than the timeout, the send operation is canceled. The default timeout is 30 seconds.

WINHTTP_OPTION_SERVER_CERT_CONTEXT

Retrieves the server certification context. WINHTTP_OPTION_SERVER_CERT_CONTEXT can be passed to obtain a duplicated pointer to the CERT CONTEXT for a server certificate received during a negotiated SSL connection. The client must CertFreeCertificateContext on the returned PCCERT_CONTEXT pointer that is filled into the buffer.

WINHTTP_OPTION_SPN

Includes or removes the server port number when the SPN (service principal name) is built for Kerberos or Negotiate Kerberos authentication. This flag is one of the following values:

WINHTTP_DISABLE_SPN_SERVER_PORT

Removes the server port number.

WINHTTP_ENABLE_SPN_SERVER_PORT

Includes the server port number.

 

WINHTTP_OPTION_UNLOAD_NOTIFY_EVEN

Takes an event that will be set when the last callback has completed for a particular session. This flag must be must be used on a session handle. The event cannot be closed until after it has been set by WinHTTP.

WINHTTP_FLAG_SECURE_PROTOCOL_ALL

The buffer length is incorrect for a handle, the handle is invalid, or the option has already been set.

ERROR_WINHTTP_INCORRECT_HANDLE_TYPE

The target is not a session handle.

 

WINHTTP_OPTION_URL

Retrieves a string value that contains the full URL of a downloaded resource. If the original URL contained any extra data, such as search strings or anchors, or if the call was redirected, the URL returned differs from the original. The application should pass in a buffer, sized in bytes, that is big enough to hold the returned URL in wide char.

WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS

Takes a BOOL and can be set only a session handle. It will only propagate down to handles created from the session handle after the option has been set. If TRUE, this option causes as a last resort the use of global server credentials that were pushed down from WinInet. The default for this option is FALSE. This option requires registry key HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings!ShareCredsWithWinHttp. This registry key is not present by default. When it is set, WinINet will send credentials down to WinHTTP. Whenever WinHttp gets an authentication challenge and if there are no credentials set on the current handle, it will use the credentials provided by WinINet.

WINHTTP_OPTION_USER_AGENT

Sets or retrieves the user agent string on handles supplied by WinHttpOpen and used in subsequent WinHttpSendRequest functions, as long as it is not overridden by a header added by WinHttpAddRequestHeaders or WinHttpSendRequest. When retrieving a user agent, the application should pass in a buffer, sized in bytes, that is big enough to hold the returned URL in wide char. When setting the user agent, the buffer size is the length of the string, in characters, plus the NULL terminator.

WINHTTP_OPTION_USERNAME

Sets or retrieves a string that contains the user name.

WINHTTP_OPTION_WORKER_THREAD_COUNT

Sets an unsigned long integer value that specifies the number of worker threads the thread pool should use for asynchronous completions. The default value of this option is zero, which specifies that the number of worker threads is equal to the number of CPUs on the system. This option can only be set on a NULL HINTERNET handle before an asynchronous operation has occurred. This option can only be set once.

Windows Server 2008 R2 and Windows 7:  This option is obsolete.

WINHTTP_OPTION_WRITE_BUFFER_SIZE

This option has been deprecated; it has no effect.

Remarks

The following table lists the option flags by specifying which handles they can act upon, whether they can be queried and set, and the data type used. An "X" indicates that the option flag is valid for use with the function or handle, while a "-" specifies that the option flag is invalid.

* See the documentation for this flag earlier in this topic.

Note  For Windows XP and Windows 2000, see Run-Time Requirements.

Requirements

See Also

WinHTTP Versions

Send comments about this topic to Microsoft

Build date: 10/8/2009