Edit

Share via

IBackgroundCopyJobHttpOptions::SetSecurityFlags method (bits2_5.h)

  • Article

Sets flags for HTTP that determine whether the certificate revocation list is checked and certain certificate errors are ignored, and the policy to use when a server redirects the HTTP request.

Syntax

HRESULT SetSecurityFlags(
  [in] ULONG Flags
);

Parameters

[in] Flags

HTTP security flags that indicate which errors to ignore when connecting to the server. You can set one or more of the following flags:

Value Meaning
BG_SSL_ENABLE_CRL_CHECK
0x0001
 Check the certificate revocation list (CRL) to verify that the server certificate has not been revoked.
BG_SSL_IGNORE_CERT_CN_INVALID
0x0002
 Ignores errors caused when the certificate host name of the server does not match the host name in the request.
BG_SSL_IGNORE_CERT_DATE_INVALID
0x0004
 Ignores errors caused by an expired certificate.
BG_SSL_IGNORE_UNKNOWN_CA
0x0008
 Ignore errors associated with an unknown certification authority (CA).
BG_SSL_IGNORE_CERT_WRONG_USAGE
0x0010
 Ignore errors associated with the use of a certificate.
BG_HTTP_REDIRECT_POLICY_ALLOW_SILENT
0x0000
 Allows the server to redirect your request to another server. This is the default.
BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT
0x0100
 Allows the server to redirect your request to another server. BITS updates the remote name with the final URL.
BG_HTTP_REDIRECT_POLICY_DISALLOW
0x0200
 Places the job in the fatal error state when the server redirects your request to another server. BITS updates the remote name with the redirected URL.
BG_HTTP_REDIRECT_POLICY_MASK
0x0700
 Bitmask that you can use with the security flag value to determine which redirect policy is in effect. It does not include the flag ALLOW_HTTPS_TO_HTTP.
BG_HTTP_REDIRECT_POLICY_ALLOW_HTTPS_TO_HTTP
0x0800
 Allows the server to redirect an HTTPS request to an HTTP URL.

You can combine this flag with BG_HTTP_REDIRECT_POLICY_ALLOW_SILENT and BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT.

Return value

The following table lists some of the possible return values.

Return code Description
S_OK
 Successfully retrieved the headers.
E_NOTIMPL
 The flag value is not supported.

Remarks

If CRL checking is requested, BITS performs the check for all files in the job that specify the HTTPS protocol. The check is made for each file before the file begins transferring. If you set this value to TRUE after BITS has partially downloaded a file, BITS will reschedule the job and begin downloading the file again. Files that are already downloaded are not affected.

BITS uses the CRL on the local computer if the CRL is up-to-date; otherwise, BITS downloads the CRL from the certification authority (CA) that signed the certificate.

The job goes into the fatal error state if the following errors occur.

Error code Description
ERROR_WINHTTP_SECURE_CERT_REV_FAILED Unable to request CRL checking because the certificate server is offline or the CRL cannot be downloaded.
ERROR_WINHTTP_SECURE_CERT_REVOKED The certificate is revoked.
 

The redirect policy applies to all files in a download job (the policy does not apply to upload jobs).

Prior to BITS 3.0:  The redirect policies are not supported.

If the policy is BG_HTTP_REDIRECT_POLICY_DISALLOW and the server redirects your request, the job is placed in the fatal error state with one of the following error codes. For descriptions of the error codes, see HTTP Status Codes.

  • HRESULT_FROM_WIN32(HTTP_STATUS_AMBIGUOUS)
  • HRESULT_FROM_WIN32(HTTP_STATUS_MOVED)
  • HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT)
  • HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT_METHOD)
  • HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT_KEEP_VERB)
BITS does not support redirection from HTTP or HTTPs to SMB.

If peer caching is enabled and you specify BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT, the file is stored in the cache with the final redirected URL. If a peer then tries to download the file with the original URL, the peer will not find the file in the peer's cache and will end up downloading the file from the origin server.

If you specify and the file is downloaded from the

Note that setting BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT may affect the result when calling the IBackgroundCopyJob3::ReplaceRemotePrefix method. If a server redirected your request, BITS will have already changed the original URL to the final redirected URL, so calling the ReplaceRemotePrefix method will not find files with the original URL.

Requirements

Requirement Value
Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header bits2_5.h (include Bits.h)
Library Bits.lib

See also

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions::GetSecurityFlags