共用方式為

IBackgroundCopyJobHttpOptions：：SetClientCertificateByName 方法 (bits2_5.h)

  • 發行項

指定要用於 HTTPS (SSL) 要求中用戶端驗證之用戶端憑證的主體名稱。

語法

HRESULT SetClientCertificateByName(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] LPCWSTR                SubjectName
);

參數

[in] StoreLocation

識別用來查閱憑證的系統存放區位置。 如需可能的值，請參閱 BG_CERT_STORE_LOCATION 列舉。

[in] StoreName

包含證書儲存名稱的 Null 終止字串。 字串限制為 256 個字元，包括 Null 終止符。 您可以指定下列其中一個系統存放區或應用程式定義的存放區。 存放區可以是本機或遠端存放區。

值 意義
CA
 證書頒發機構單位憑證
我
 個人憑證
根
 跟證書
Spc
 軟體發行者憑證

[in] SubjectName

包含憑證簡單主體名稱的 Null 終止字串。 如果主體名稱包含多個相對辨別名稱 (RDN) ，您可以指定一或多個相鄰的 RDN。 如果您指定多個 RDN，清單會以逗號分隔。 字串限制為 256 個字元，包括 Null 終止符。 您無法指定空的主體名稱。

請勿在名稱中包含物件識別碼。 您必須以與憑證顯示的反向順序指定 RDN。 例如，如果憑證中的主體名稱是 “CN=name1， OU=name2， O=name3”，請將主體名稱指定為 “name3， name2， name1”。

傳回值

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

傳回碼 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 或 SubjectName 參數不可為 NULL。
BG_E_STRING_TOO_LONG
 StoreName 或 SubjectName 參數超過 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) 。

方法會使用主體名稱字串來執行憑證的子字串搜尋。 由於主體名稱不一定是唯一的，因此此方法會搜尋存放區中的第一個使用指定主體名稱且為客戶端驗證憑證的憑證。 您應該提供完整的主體名稱，以取得尋找單一相符項目的機會。 如果憑證不正確， (不受信任) ，當BITS嘗試傳輸檔案，且作業會移至錯誤狀態時，BG_E_HTTP_ERROR_403失敗。 如果您無法保證唯一的主體名稱，請考慮改用 IBackgroundCopyJobHttpOptions：：SetClientCertificateByID 方法。

不支援智慧卡憑證標識碼 (指紋) 。

範例

下列範例示範如何使用憑證的主體名稱來指定作業的客戶端憑證。 此範例假設 pJob 指向有效的作業。


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;

  // Change list of names to actual list of names.
  LPWSTR pSubjectName = L"name3, name2, name1";  
                                                    
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByName(BG_CERT_STORE_LOCATION_CURRENT_USER, 
                                      L"MY", pSubjectName));
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByName 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

IBackgroundCopyJobHttpOptions：：GetClientCertificate

IBackgroundCopyJobHttpOptions：：RemoveClientCertificate

IBackgroundCopyJobHttpOptions：：SetClientCertificateByID