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 終止符。 您可以指定下列其中一個系統存放區或應用程式定義的存放區。 存放區可以是本機或遠端存放區。

[in] SubjectName

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

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

傳回值

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

備註

只有作業擁有者可以指定客戶端憑證。 如果作業變更擁有權，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();
  }

規格需求

另請參閱

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions：：GetClientCertificate

IBackgroundCopyJobHttpOptions：：RemoveClientCertificate

IBackgroundCopyJobHttpOptions：：SetClientCertificateByID