IBackgroundCopyJobHttpOptions：：SetClientCertificateByID method （bits2_5.h）

指定要在 HTTPS （SSL）要求中用於客戶端驗證的用戶端憑證標識碼。

語法

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

參數

[in] StoreLocation

識別要用來查閱憑證的系統存放區位置。關於可能的數值，請參見 BG_CERT_STORE_LOCATION 列舉。

[in] StoreName

包含憑證儲存名稱的空終止字串。字串限制為 256 個字元，包含空終止符。你可以指定以下系統儲存裝置或應用程式定義儲存。店面可以是本地或偏遠的店面。

價值觀	Meaning
加州	認證機構證書
我的	個人證書
根	根憑證
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 伺服器 2008
目標平臺	窗戶
Header	bits2_5.h（包含 Bits.h）
Library	Bits.lib