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

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

[in] SubjectName

包含憑證簡單主體名稱的空終端字串。 若主題名稱包含多個相關區別名稱（RDN），您可以指定一個或多個相鄰的 RDN。 若指定多個 RDN，列表會以逗號分隔。 字串限制為 256 個字元，包含空終止符。 你不能指定空主旨名稱。

請不要在名稱中包含物件識別碼。 你必須依照憑證顯示的順序來指定 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