IBackgroundCopyJobHttpOptions：：SetClientCertificateByID 方法（bits2_5.h）

指定要在 HTTPS （SSL）请求中用于客户端身份验证的客户端证书的标识符。

Syntax

HRESULT SetClientCertificateByID(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] byte                   *pCertHashBlob
);

参数

[in] StoreLocation

标识用于查找证书的系统存储的位置。有关可能的值，请参阅 BG_CERT_STORE_LOCATION 枚举。

[in] StoreName

包含证书存储名称的以 Null 结尾的字符串。字符串限制为 256 个字符，包括 null 终止符。可以指定以下系统存储之一或应用程序定义的存储区之一。该存储可以是本地或远程存储。

价值	Meaning
CA	证书颁发机构证书
我	个人证书
根	根证书
SPC	软件发布者证书

[in] pCertHashBlob

标识证书的 SHA1 哈希。对哈希使用 20 字节缓冲区。有关详细信息，请参阅“备注”。

返回值

下表列出了一些可能的返回值。

返回代码	Description
S_OK	成功。
E_ACCESSDENIED	用户无权访问存储位置。
E_NOTIMPL	StoreLocation 参数的值未在BG_CERT_STORE_LOCATION枚举中定义。
HRESULT_FROM_WIN32（ERROR_FILE_NOT_FOUND）	找不到与 StoreName 参数匹配的存储区。
CRYPT_E_NOT_FOUND	找不到与哈希匹配的证书。
RPC_X_NULL_REF_POINTER	StoreName 或 pCertHashBlob 参数不能为 NULL。
RPC_X_BAD_STUB_DATA	pCertHashBlob 缓冲区大小不是 20 字节。
BG_E_STRING_TOO_LONG	StoreName 参数超过 256 个字符。
BG_E_INVALID_STATE	作业的状态不能BG_JOB_STATE_CANCELLED或BG_JOB_STATE_ACKNOWLEDGED。

注解

只有作业所有者可以指定客户端证书。如果作业更改所有权，BITS 将从作业中删除证书。

客户端证书仅适用于使用 HTTP 或 HTTPS 协议的远程文件。可以为所有作业类型指定证书。

当网站接受但不要求 SSL 客户端证书，BITS 作业未指定客户端证书时，作业将失败并ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED（0x80072f0c）。

如果为作业或应用程序创建证书，则可以将证书标识符（指纹）存储在注册表或数据库中，并在作业需要证书时使用它。还可以枚举存储中的证书，并让用户选择证书。另一种替代方法是调用 CertFindCertificateInStore 函数，以基于某些条件检索证书上下文。使用上下文调用 CertGetCertificateContextProperty 函数以检索哈希（为 dwPropId 指定CERT_HASH_PROP_ID）。

不支持智能卡指纹。

例子

以下示例演示如何使用证书的指纹为作业指定客户端证书。示例硬编码证书的指纹，并假定 pJob 指向有效的作业。


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;  
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;
  BYTE Thumbprint[] = {0xa1, 0x06, 0x6e, 0x13, 0xf2, 0x34, 0x49, 0x0a, 0x22, 0xd7, 0x6f, 0xb2, 0x80, 0xab, 0x68, 0x7d, 0x16, 0x55, 0xb3, 0x14};


  // Retrieve a pointer to the IBackgroundCopyJob4 interface.
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"QueryInterface for HttpOptions failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByID(BG_CERT_STORE_LOCATION_CURRENT_USER, 
      L"MY", Thumbprint);
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByID failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions)
  {
    hr = pHttpOptions->Release();
  }

要求

Requirement	价值
最低支持的客户端	Windows Vista
支持的最低服务器	Windows Server 2008
目标平台	Windows操作系统
Header	bits2_5.h （包括 Bits.h）
Library	Bits.lib