IBackgroundCopyJobHttpOptions

証明書ベースのクライアント認証に使用するクライアント証明書や、HTTP リクエストに含めるカスタムヘッダーを指定するためのインターフェイスです。

HTTPS (SSL) リクエストでのクライアント認証に使用するクライアント証明書の識別子を指定します。

次の表に、返される可能性のある値の一部を示します。

クライアント証明書を指定できるのはジョブの所有者だけです。ジョブの所有権が変わると、BITS はジョブから証明書を削除します。

クライアント証明書は、HTTP または HTTPS プロトコルを使用するリモートファイルに対してのみ適用されます。証明書はすべてのジョブの種類に指定できます。

Web サイトが SSL クライアント証明書を必須とはしないが受け入れる構成で、かつ BITS ジョブがクライアント証明書を指定していない場合、ジョブは ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c) で失敗します。

ジョブまたはアプリケーション用に証明書を作成する場合、その証明書の識別子 (拇印) をレジストリまたはデータベースに保存しておき、証明書が必要なジョブで使用できます。また、ストア内の証明書を列挙してユーザーに選択させることもできます。もう 1 つの方法として、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();
  }

HTTPS (SSL) リクエストでのクライアント認証に使用するクライアント証明書のサブジェクト名を指定します。

次の表に、返される可能性のある値の一部を示します。

クライアント証明書を指定できるのはジョブの所有者だけです。ジョブの所有権が変わると、BITS はジョブから証明書を削除します。

クライアント証明書は、HTTP または HTTPS プロトコルを使用するリモートファイルに対してのみ適用されます。証明書はすべてのジョブの種類に指定できます。

Web サイトが 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::SetClientCertificateByID メソッドまたは IBackgroundCopyJobHttpOptions::SetClientCertificateByName メソッドを使用します。

ジョブからクライアント証明書を取得します。

次の表に、返される可能性のある値の一部を示します。

証明書を指定するには、IBackgroundCopyJobHttpOptions::SetClientCertificateByID メソッドまたは IBackgroundCopyJobHttpOptions::SetClientCertificateByName メソッドを使用します。

例

次の例は、クライアント証明書に関する情報を取得する方法を示しています。この例では、pJob が有効なジョブを指していることを前提としています。

#define THUMBPRINT_SIZE 20

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

  BG_CERT_STORE_LOCATION StoreLocation;
  LPWSTR pStoreName = NULL;
  BYTE* pThumbprint = NULL;
  LPWSTR pSubjectName = NULL;

  // Retrieve a pointer to the IBackgroundCopyJobHttpOptions interface.
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Retrieve information about the client certificate set on the job. 
  hr = pHttpOptions->GetClientCertificate(&StoreLocation, &pStoreName, 
         &pThumbprint, &pSubjectName);
  if (S_OK == hr)
  {
    wprintf(L"\nLocation: %d\nStore name: %s\nSubject: %s\n", 
        StoreLocation, pStoreName, pSubjectName);

    wprintf(L"Thumbprint: ");
    for (DWORD i = 0; i < THUMBPRINT_SIZE; i++)
    {
      wprintf(L"%x ", pThumbprint[i]);
    }
    wprintf(L"\n");

    CoTaskMemFree(pStoreName);
    CoTaskMemFree(pThumbprint);
    CoTaskMemFree(pSubjectName);
  }
  else if (RPC_X_BAD_STUB_DATA == hr)
  {
    wprintf(L"The job does not specify a client certificate or\n"
            L"the user does not have permission to access the certificate.\n");
  }
  else
  {
    wprintf(L"pHttpOptions->GetClientCertificate failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions)
  {
    hr = pHttpOptions->Release();
  }

HTTP リクエストに含める 1 つ以上のカスタム HTTP ヘッダーを指定します。

次の表に、返される可能性のある値の一部を示します。

カスタムヘッダーは、HTTP または HTTPS プロトコルを使用するリモートファイルに対してのみ適用されます。カスタムヘッダーはすべてのジョブの種類に指定できます。

カスタムヘッダーを指定できるのはジョブの所有者だけです。ジョブの所有権が変わると、BITS はジョブからヘッダーを削除します。

複数の HTTP リクエストが送信される場合、ヘッダーは各リクエストとともに送信される点に注意してください。

カスタムヘッダーを処理する ISAPI は、ヘッダーが無効な場合に HTTP エラーを返すことがあります。BITS がそのエラーをどのように処理するかの詳細については、Handling Server Application Errors を参照してください。

例

次の例は、ジョブにカスタムヘッダーを指定する方法を示しています。この例では、pJob が有効なジョブを指していることを前提としています。

// Custom headers to include in job.
#define HEADERS L"MyHeader_1: Header One Value\r\n" \
    L"MyHeader_2: Header Two Value\r\n" \
    L"MyHeader_3: Header Three Value\r\n"


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

  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

  hr = pHttpOptions->SetCustomHeaders(HEADERS);
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetCustomHeaders failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions) 
  {
    hr = pHttpOptions->Release();
  }

以前の IBackgroundCopyJobHttpOptions::SetCustomHeaders の呼び出しで設定されたカスタムヘッダー (つまり、BITS がリモートへ送信するヘッダーであり、BITS がリモートから受信するヘッダーではありません) を取得します。

次の表に、返される可能性のある値の一部を示します。

カスタムヘッダーを取得できるのはジョブの所有者だけです。ヘッダーを指定するには、IBackgroundCopyJobHttpOptions::SetCustomHeaders メソッドを呼び出します。

証明書失効リストを確認するかどうか、特定の証明書エラーを無視するかどうか、およびサーバーが HTTP リクエストをリダイレクトした場合に使用するポリシーを決定する HTTP 用のフラグを設定します。

次の表に、返される可能性のある値の一部を示します。

CRL チェックが要求された場合、BITS はジョブ内で HTTPS プロトコルを指定しているすべてのファイルに対してチェックを実行します。チェックは各ファイルの転送開始前に行われます。BITS がファイルを部分的にダウンロードした後にこの値を TRUE に設定した場合、BITS はジョブを再スケジュールし、そのファイルのダウンロードを最初からやり直します。すでにダウンロード済みのファイルは影響を受けません。

BITS はローカルコンピューターの CRL が最新であればそれを使用します。最新でない場合は、証明書に署名した証明機関 (CA) から CRL をダウンロードします。

次のエラーが発生した場合、ジョブは致命的エラー状態になります。

リダイレクトポリシーはダウンロードジョブ内のすべてのファイルに適用されます (アップロードジョブには適用されません)。

BITS 3.0 より前: リダイレクトポリシーはサポートされていません。

ポリシーが BG_HTTP_REDIRECT_POLICY_DISALLOW で、サーバーがリクエストをリダイレクトした場合、ジョブは次のいずれかのエラーコードで致命的エラー状態になります。エラーコードの説明については、HTTP Status Codes を参照してください。

• HRESULT_FROM_WIN32(HTTP_STATUS_AMBIGUOUS)
• HRESULT_FROM_WIN32(HTTP_STATUS_MOVED)
• HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT)
• HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT_METHOD)
• HRESULT_FROM_WIN32(HTTP_STATUS_REDIRECT_KEEP_VERB)

ピアキャッシュが有効で BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT を指定した場合、ファイルは最終的なリダイレクト先の URL でキャッシュに格納されます。その後、ピアが元の URL でファイルをダウンロードしようとすると、ピアのキャッシュ内にファイルが見つからず、結果としてオリジンサーバーからファイルをダウンロードすることになります。

を指定し、ファイルが からダウンロードされた場合

BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT を設定すると、IBackgroundCopyJob3::ReplaceRemotePrefix メソッドを呼び出したときの結果に影響する場合がある点に注意してください。サーバーがリクエストをリダイレクトした場合、BITS は元の URL をすでに最終的なリダイレクト先の URL に変更しているため、ReplaceRemotePrefix メソッドを呼び出しても元の URL を持つファイルは見つかりません。

証明書失効リストを確認するかどうか、特定の証明書エラーを無視するかどうか、およびサーバーが HTTP リクエストをリダイレクトした場合に使用するポリシーを決定する HTTP 用のフラグを取得します。

成功した場合は S_OK を返します。