Option Flags
The following option flags are supported by WinHttpQueryOption and WinHttpSetOption.
- SECURITY_FLAG_IGNORE_WEAK_SIGNATURE
-
-
Allows a weak signature check to be ignored.
-
- WINHTTP_OPTION_ASSURED_NON_BLOCKING_CALLBACKS
-
-
The default is FALSE. If set to TRUE, WinHTTP does not guarantee progress if status callbacks are blocked by the client application.
The client application must take special care to perform minimal operations within the callback without blocking, returning as quickly as possible, and in particular must not wait for any subsequent WinHTTP calls. If it does not follow these guidelines, there is likely to be a negative performance impact or a potential application hang. If used in the prescribed manner, this option may improve performance.
-
- 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.
Note This flag is available for Windows Vista and later.BOOL fRet = WinHttpSetOption ( hRequest, WINHTTP_OPTION_CLIENT_CERT_CONTEXT, WINHTTP_NO_CLIENT_CERT_CONTEXT, 0);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.
Note This flag is available for Windows Vista and later.
-
- 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_CONNECT_RETRIES
-
-
Sets or retrieves an unsigned long integer value that contains the number of timesWinHTTP 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_CONNECTION_INFO
-
-
Retrieves the source and destination IP address, and port of the request that generated the response when WinHttpReceiveResponse returns. The application calls WinHttpQueryOption 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 obsolete.
-
- WINHTTP_OPTION_CONTEXT_VALUE
-
-
Sets or retrieves a DWORD_PTR 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_DECOMPRESSION
-
-
Sets a DWORD of flags which determine whether WinHTTP will automatically decompress response bodies with compressed Content-Encodings. WinHTTP will also set an appropriate Accept-Encoding header, overriding any supplied by the caller. Supported values are:
Value Meaning WINHTTP_DECOMPRESSION_FLAG_GZIP Decompress Content-Encoding: gzip responses. WINHTTP_DECOMPRESSION_FLAG_DEFLATE Decompress Content-Encoding: deflate responses. WINHTTP_DECOMPRESSION_FLAG_ALL Decompress responses with any supported Content-Encoding. By default, WinHTTP will deliver compressed responses to the caller unmodified. Supported in Windows 8.1 and newer.
-
- 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 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.
If enabled, WinHTTP allows SSL revocation. This value can be set only on the request handle.
-
- WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL
-
-
Sets a DWORD bitmask of acceptable advanced HTTP versions. Supported on Windows 10, version 1607 and newer. Possible values are:
- WINHTTP_PROTOCOL_FLAG_HTTP2 (0x1). Supported on Windows 10, version 1607 and newer
Legacy versions of HTTP (1.1 and prior) cannot be disabled using this option. The default is 0x0.
-
- 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_OPTION_HTTP_PROTOCOL_USED
-
-
Gets a DWORD indicating which advanced HTTP version was used on a given request. Possible values are:
- • WINHTTP_PROTOCOL_FLAG_HTTP2 (0x1). Supported on Windows 10, version 1607 and newer.
0x0 indicates HTTP/1.1 or earlier. Supported on Windows 10, version 1607 and newer.
-
- 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_IS_PROXY_CONNECT_RESPONSE
-
-
Gets whether or not a Proxy Return Connect Response can be retrieved.
-
- 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 Vista with SP1 and Windows Server 2008: This flag 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 obsolete.
-
- 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 obsolete.
-
- 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 obsolete.
-
- 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 obsolete.
-
- 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_SPN_USED
-
-
Gets the proxy Server Principal Name that WinHTTP supplied to SSPI during authentication. This string value is usefor passing to SspiPromptForCredentials after an authentication failure.
-
- 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_PROXY_CONNECT_RESPONSE
-
-
Sets whether or not the proxy response entity can be retrieved. This option is disabled by default.
-
- 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 All redirects are followed automatically.
All redirects are followed, except those that originate from a secure (https) URL to an unsecure (http) URL. This is the default setting.
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 in Windows 7 and Windows 8. By default only SSL3, TLS1.0, TLS1.1, and TLS1.2 are enabled in Windows 8.1 and Windows 10. The value can be 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_FLAG_SECURE_PROTOCOL_TLS1_1
-
The TLS 1.1 protocol can be used.
- WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_2
-
The TLS 1.2 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_IGNORE_WEAK_SIGNATURE
-
Allows a weak signature to be ignored.
This flag is available in the rollup update for each OS starting with Windows 7 and Windows Server 2008 R2.
- 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_CBT
-
-
Gets a pointer to SecPkgContext_Bindings structure that specifies a Channel Binding Token (CBT).
A Channel Binding Token is a property of a secure transport channel and is used to bind an authentication channel to the secure transport channel. This token can only be obtained by this option after an SSL connection has been established.
Note Passing this option and a null value for lpBuffer to WinHttpQueryOption will return ERROR_INSUFFICIENT_BUFFER and the required byte size for the buffer in the lpdwBufferLength parameter. This returned buffer size value can be passed in a subsequent call to query for the Channel Binding Token. These steps are necessary when handling WINHTTP_CALLBACK_STATUS_REQUEST if you want to modify request headers based on the Channel Binding Token. Note that Windows XP and Vista do not support modifying request headers during this callback.
-
- 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 call CertFreeCertificateContext on the returned PCCERT_CONTEXT pointer that is filled into the buffer.
-
- WINHTTP_OPTION_SERVER_SPN_USED
-
-
Gets the server Server Principal Name that WinHTTP supplied to SSPI during authentication. This string value can be passed to SspiPromptForCredentials after an authentication failure.
-
- 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_OPTION_UNLOAD_NOTIFY_EVENT
-
-
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_OPTION_UNSAFE_HEADER_BLOCKING
-
-
This option is reserved for internal use and should not be called.
-
- WINHTTP_OPTION_UPGRADE_TO_WEB_SOCKET
-
-
Instructs the stack to start a WebSocket handshake process with WinHttpSendRequest. This option takes no parameters.
-
- 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_WEB_SOCKET_CLOSE_TIMEOUT
-
-
Sets the time, in milliseconds, that WinHttpWebSocketClose should wait to complete the close handshake. The default is 10 seconds.
-
- WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL
-
-
Sets the interval, in milliseconds, to send a keep-alive packet over the connection. The default interval is 30000 (30 seconds). The minimum interval is 15000 (15 seconds). Using WinHttpSetOption to set a value lower than 15000 will return with ERROR_INVALID_PARAMETER.
Note The default value for WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL is read from HKLM:\SOFTWARE\Microsoft\WebSocket\KeepaliveInterval. If a value is not set, the default value of 30000 will be used. It is not possible to have a lower keepalive interval than 15000 milliseconds.
-
- WINHTTP_OPTION_WEB_SOCKET_RECEIVE_BUFFER_SIZE
-
-
Sets or retrieves a DWORD which specifies the receive buffer size to be used on WebSocket connections. Supported in Windows 8.1 and newer.
-
- WINHTTP_OPTION_WEB_SOCKET_SEND_BUFFER_SIZE
-
-
Sets or retrieves a DWORD which specifies the send buffer size to be used on WebSocket connections. Supported in Windows 8.1 and newer.
-
- 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 flag 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.
| Option flag | Session handle | Request handle | Query option | Set option | Data type |
|---|---|---|---|---|---|
| WINHTTP_OPTION_ASSURED_NON_BLOCKING_CALLBACKS | X | - | - | X | BOOL |
| WINHTTP_OPTION_AUTOLOGON_POLICY | - | X | - | X | DWORD |
| WINHTTP_OPTION_CALLBACK | X | X | X | X | LPVOID |
| WINHTTP_OPTION_CLIENT_CERT_CONTEXT | - | X | - | X | CERT_CONTEXT |
| WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST | - | X | X | - | SecPkgContext_IssuerListInfoEx* |
| WINHTTP_OPTION_CODEPAGE | X | - | - | X | DWORD |
| WINHTTP_OPTION_CONFIGURE_PASSPORT_AUTH | X | - | - | X | DWORD |
| WINHTTP_OPTION_CONNECT_INFO | - | X | X | - | WINHTTP_CONNECTION_INFO |
| WINHTTP_OPTION_CONNECT_RETRIES | X | X | X | X | DWORD |
| WINHTTP_OPTION_CONNECT_TIMEOUT | X | X | X | X | DWORD |
| WINHTTP_OPTION_CONTEXT_VALUE | X | X | X | X | DWORD_PTR |
| WINHTTP_OPTION_DISABLE_FEATURE | - | X | - | X | DWORD |
| WINHTTP_OPTION_ENABLE_FEATURE | * | * | - | X | DWORD |
| WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL | X | X | - | X | DWORD |
| WINHTTP_OPTION_ENABLETRACING | - | - | X | X | DWORD |
| WINHTTP_OPTION_EXTENDED_ERROR | X | X | X | - | DWORD |
| WINHTTP_OPTION_GLOBAL_PROXY_CREDS | X | X | - | X | WINHTTP_CREDS |
| WINHTTP_OPTION_GLOBAL_SERVER_CREDS | X | X | - | X | WINHTTP_CREDS_EX |
| WINHTTP_OPTION_HANDLE_TYPE | X | X | X | - | DWORD |
| WINHTTP_OPTION_HTTP_VERSION | X | X | X | X | HTTP_VERSION_INFO |
| WINHTTP_OPTION_HTTP_PROTOCOL_USED | - | X | X | - | DWORD |
| WINHTTP_OPTION_IS_PROXY_CONNECT_RESPONSE | X | X | X | - | BOOL |
| WINHTTP_OPTION_MAX_CONNS_PER_1_0_SERVER | X | - | X | X | DWORD |
| WINHTTP_OPTION_MAX_CONNS_PER_SERVER | X | - | X | X | DWORD |
| WINHTTP_OPTION_MAX_HTTP_AUTOMATIC_REDIRECTS | X | X | X | X | DWORD |
| WINHTTP_OPTION_MAX_HTTP_STATUS_CONTINUE | X | X | X | X | DWORD |
| WINHTTP_OPTION_MAX_RESPONSE_DRAIN_SIZE | X | X | X | X | DWORD |
| WINHTTP_OPTION_MAX_RESPONSE_HEADER_SIZE | X | X | X | X | DWORD |
| WINHTTP_OPTION_UPGRADE_TO_WEB_SOCKET | - | X | - | X | N/A |
| WINHTTP_OPTION_PARENT_HANDLE | X | X | X | - | HINTERNET |
| WINHTTP_OPTION_PASSPORT_COBRANDING_TEXT | - | X | X | - | LPWSTR |
| WINHTTP_OPTION_PASSPORT_COBRANDING_URL | - | X | X | - | LPWSTR |
| WINHTTP_OPTION_PASSPORT_RETURN_URL | - | X | X | - | LPVOID |
| WINHTTP_OPTION_PASSPORT_SIGN_OUT | X | - | - | X | LPVOID |
| WINHTTP_OPTION_PASSWORD | - | X | X | X | LPWSTR |
| WINHTTP_OPTION_PROXY | X | X | X | X | WINHTTP_PROXY_INFO |
| WINHTTP_OPTION_PROXY_PASSWORD | - | X | X | X | LPWSTR |
| WINHTTP_OPTION_PROXY_SPN_USED | - | X | X | - | LPWSTR |
| WINHTTP_OPTION_PROXY_USERNAME | - | X | X | X | LPWSTR |
| WINHTTP_OPTION_READ_BUFFER_SIZE | - | X | X | X | DWORD |
| WINHTTP_OPTION_RECEIVE_PROXY_CONNECT_RESPONSE | X | X | - | X | BOOL |
| WINHTTP_OPTION_RECEIVE_TIMEOUT | X | X | X | X | DWORD |
| WINHTTP_OPTION_RECEIVE_RESPONSE_TIMEOUT | X | X | X | X | DWORD |
| WINHTTP_OPTION_REDIRECT_POLICY | X | X | X | X | DWORD |
| WINHTTP_OPTION_REJECT_USERPWD_IN_URL | - | X | - | X | BOOL |
| WINHTTP_OPTION_REQUEST_PRIORITY | - | X | X | X | DWORD |
| WINHTTP_OPTION_RESOLVE_TIMEOUT | X | X | X | X | DWORD |
| WINHTTP_OPTION_SECURE_PROTOCOLS | X | - | - | X | DWORD |
| WINHTTP_OPTION_SECURITY_CERTIFICATE_STRUCT | - | X | X | - | WINHTTP_CERTIFICATE_INFO |
| WINHTTP_OPTION_SECURITY_FLAGS | - | X | X | X | DWORD |
| WINHTTP_OPTION_SECURITY_KEY_BITNESS | - | X | X | - | DWORD |
| WINHTTP_OPTION_SEND_TIMEOUT | X | X | X | X | DWORD |
| WINHTTP_OPTION_SERVER_CBT | - | X | X | - | SecPkgContext_Bindings* |
| WINHTTP_OPTION_SERVER_CERT_CONTEXT | - | X | X | - | CERT CONTEXT |
| WINHTTP_OPTION_SERVER_SPN_USED | - | X | X | - | LPWSTR |
| WINHTTP_OPTION_SPN | - | X | - | X | DWORD |
| WINHTTP_OPTION_UNLOAD_NOTIFY_EVEN | X | - | - | X | HINTERNET |
| WINHTTP_OPTION_URL | - | X | X | - | LPWSTR |
| WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS | X | X | - | X | BOOL |
| WINHTTP_OPTION_USER_AGENT | X | - | X | X | LPWSTR |
| WINHTTP_OPTION_USERNAME | - | X | X | X | LPWSTR |
| WINHTTP_OPTION_WEB_SOCKET_CLOSE_TIMEOUT | - | - | X | X | DWORD |
| WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL | - | - | X | X | DWORD |
| WINHTTP_OPTION_WORKER_THREAD_COUNT | - | - | - | X | DWORD |
| WINHTTP_OPTION_WRITE_BUFFER_SIZE | - | X | X | X | DWORD |
* See the documentation for this flag earlier in this topic.
Requirements
|
Minimum supported client |
Windows XP, Windows 2000 Professional with SP3 [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only] |
|
Redistributable |
WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000. |
|
Header |
|
See also