IBackgroundCopyJobHttpOptions：：SetClientCertificateByID 方法 (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
包含證書儲存名稱的 Null 終止字串。 字串限制為 256 個字元，包括 Null 終止符。 您可以指定下列其中一個系統存放區或應用程式定義的存放區。 存放區可以是本機或遠端存放區。
| 值 | 意義 |
|---|---|
|
證書頒發機構單位憑證 |
|
個人憑證 |
|
跟證書 |
|
軟體發行者憑證 |
[in] pCertHashBlob
識別憑證的SHA1哈希。 針對哈希使用 20 位元節緩衝區。 如需詳細資訊，請參閱＜備註＞。
傳回值
下表列出一些可能的傳回值。
| 傳回碼 | Description |
|---|---|
|
成功。 |
|
用戶沒有存取存放區位置的許可權。 |
|
StoreLocation 參數的值未定義於BG_CERT_STORE_LOCATION列舉中。 |
|
找不到符合 StoreName 參數的存放區。 |
|
找不到符合哈希的憑證。 |
|
StoreName 或 pCertHashBlob 參數不可為 NULL。 |
|
pCertHashBlob 緩衝區大小不是 20 個字節。 |
|
StoreName 參數超過 256 個字元。 |
|
無法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();
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista |
| 最低支援的伺服器 | Windows Server 2008 |
| 目標平台 | Windows |
| 標頭 | bits2_5.h (包含 Bits.h) |
| 程式庫 | Bits.lib |
另請參閱
IBackgroundCopyJobHttpOptions：：GetClientCertificate