WinHttpRequestOption enumeration

Article
11/02/2022

The WinHttpRequestOption enumeration includes options that can be set or retrieved for the current Microsoft Windows HTTP Services (WinHTTP) session.

Syntax

typedef enum WinHttpRequestOption { 
  WinHttpRequestOption_UserAgentString,
  WinHttpRequestOption_URL,
  WinHttpRequestOption_URLCodePage,
  WinHttpRequestOption_EscapePercentInURL,
  WinHttpRequestOption_SslErrorIgnoreFlags,
  WinHttpRequestOption_SelectCertificate,
  WinHttpRequestOption_EnableRedirects,
  WinHttpRequestOption_UrlEscapeDisable,
  WinHttpRequestOption_UrlEscapeDisableQuery,
  WinHttpRequestOption_SecureProtocols,
  WinHttpRequestOption_EnableTracing,
  WinHttpRequestOption_RevertImpersonationOverSsl,
  WinHttpRequestOption_EnableHttpsToHttpRedirects,
  WinHttpRequestOption_EnablePassportAuthentication,
  WinHttpRequestOption_MaxAutomaticRedirects,
  WinHttpRequestOption_MaxResponseHeaderSize,
  WinHttpRequestOption_MaxResponseDrainSize,
  WinHttpRequestOption_EnableHttp1_1,
  WinHttpRequestOption_EnableCertificateRevocationCheck
} WinHttpRequestOption;

Constants

WinHttpRequestOption_UserAgentString

Sets or retrieves a VARIANT that contains the user agent string.

WinHttpRequestOption_URL

Retrieves a VARIANT that contains the URL of the resource. This value is read-only; you cannot set the URL using this property. The URL cannot be read until the Open method is called. This option is useful for checking the URL after the Send method is finished to verify that any redirection occurred.

WinHttpRequestOption_URLCodePage

Sets or retrieves a VARIANT that identifies the code page for the URL string. The default value is the UTF-8 code page. The code page is used to convert the Unicode URL string, passed in the Open method, to a single-byte string representation.

WinHttpRequestOption_EscapePercentInURL

Sets or retrieves a VARIANT that indicates whether percent characters in the URL string are converted to an escape sequence. The default value of this option is VARIANT_TRUE which specifies all unsafe American National Standards Institute (ANSI) characters except the percent symbol are converted to an escape sequence.

WinHttpRequestOption_SslErrorIgnoreFlags

Sets or retrieves a VARIANT that indicates which server certificate errors should be ignored. This can be a combination of one or more of the following flags.

Error	Value
Unknown certification authority (CA) or untrusted root	0x0100
Wrong usage	0x0200
Invalid common name (CN)	0x1000
Invalid date or certificate expired	0x2000

The default value of this option in Version 5.1 of WinHTTP is zero, which results in no errors being ignored. In earlier versions of WinHTTP, the default setting was 0x3300, which resulted in all server certificate errors being ignored by default.

WinHttpRequestOption_SelectCertificate

Sets a VARIANT that specifies the client certificate that is sent to a server for authentication. This option indicates the location, certificate store, and subject of a client certificate delimited with backslashes. For more information about selecting a client certificate, see SSL in WinHTTP.

WinHttpRequestOption_EnableRedirects

Sets or retrieves a VARIANT that indicates whether requests are automatically redirected when the server specifies a new location for the resource. The default value of this option is VARIANT_TRUE to indicate that requests are automatically redirected.

WinHttpRequestOption_UrlEscapeDisable

Sets or retrieves a VARIANT that indicates whether unsafe characters in the path and query components of a URL are converted to escape sequences. The default value of this option is VARIANT_TRUE, which specifies that characters in the path and query are converted.

WinHttpRequestOption_UrlEscapeDisableQuery

Sets or retrieves a VARIANT that indicates whether unsafe characters in the query component of the URL are converted to escape sequences. The default value of this option is VARIANT_TRUE, which specifies that characters in the query are converted.

WinHttpRequestOption_SecureProtocols

Sets or retrieves a VARIANT that indicates which secure protocols can be used. This option selects the protocols acceptable to the client. The protocol is negotiated during the Secure Sockets Layer (SSL) handshake. This can be a combination of one or more of the following flags.

Protocol	Value
SSL 2.0	0x0008
SSL 3.0	0x0020
Transport Layer Security (TLS) 1.0	0x0080

The default value of this option is 0x0028, which indicates that SSL 2.0 or SSL 3.0 can be used. If this option is set to zero, the client and server are not able to determine an acceptable security protocol and the next Send results in an error.

WinHttpRequestOption_EnableTracing

Sets or retrieves a VARIANT that indicates whether tracing is currently enabled. Also see Collect WinHTTP traces.

WinHttpRequestOption_RevertImpersonationOverSsl

Controls whether the WinHttpRequest object temporarily reverts client impersonation for the duration of the SSL certificate authentication operations. The default setting for the WinHttpRequest object is TRUE. Set this option to FALSE to keep impersonation while performing certificate authentication operations.

WinHttpRequestOption_EnableHttpsToHttpRedirects

Controls whether or not WinHTTP allows redirects. By default, all redirects are automatically followed, except those that transfer from a secure (https) URL to an non-secure (http) URL. Set this option to TRUE to enable HTTPS to HTTP redirects.

WinHttpRequestOption_EnablePassportAuthentication

Enables or disables support for Passport authentication. By default, automatic support for Passport authentication is disabled; set this option to TRUE to enable Passport authentication support.

WinHttpRequestOption_MaxAutomaticRedirects

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