IBackgroundCopyJobHttpOptions3
COM公式ドキュメント
このインターフェイスを使用して、HTTP のカスタムヘッダーを書き込み専用に設定したり、独自に実装したサーバー証明書検証コールバックメソッドを設定したりします。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
サーバー証明書は HTTPS 接続が開かれるときに送信されます。このメソッドを使用して、それらのサーバー証明書を検証するために呼び出されるコールバックを設定します。
| certValidationCallback | IUnknown* | in | IBackgroundCopyServerCertificateValidationCallback を実装するオブジェクトへのポインター。現在のコールバックインターフェイスポインターを削除するには、このパラメーターに nullptr を設定します。 |
戻り値
型: HRESULT
関数が成功した場合は S_OK を返します。失敗した場合は HRESULT のエラーコードを返します。
| 戻り値 | 説明 |
|---|---|
| E_NOINTERFACE | IBackgroundCopyServerCertificateValidationCallback をクエリできないインターフェイスポインターを渡しました。 |
| BG_E_READ_ONLY_WHEN_JOB_ACTIVE | コールバックを設定するには、ジョブの状態が PAUSED である必要があります。 |
解説(Remarks)
サーバー証明書に対して独自のチェックを行いたい場合に、このメソッドを使用します。
このメソッドは、IBackgroundCopyServerCertificateValidationCallback インターフェイスを実装している場合にのみ呼び出してください。
検証インターフェイスはアプリケーションが終了すると無効になります。BITS は検証インターフェイスの記録を保持しません。そのため、証明書の検証要求を受け取りたい既存のジョブに対しては、アプリケーションの初期化処理で SetServerCertificateValidationInterface を呼び出す必要があります。
複数のアプリケーションが SetServerCertificateValidationInterface を呼び出してジョブの通知インターフェイスを設定した場合、最後に呼び出したアプリケーションが通知を受け取ります。他のアプリケーションは通知を受け取りません。
OS による証明書の検証中に証明書エラーが検出された場合、接続は中止され、カスタムコールバックは呼び出されません。OS の検証ロジックは IBackgroundCopyJobHttpOptions::SetSecurityFlags の呼び出しによってカスタマイズできます。たとえば、想定される証明書検証エラーを無視することができます。
OS の検証に成功した場合、TLS ハンドシェイクの完了前かつ HTTP 要求の送信前に、IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate メソッドが呼び出されます。
検証メソッドが証明書を拒否した場合、ジョブは BG_JOB_STATE_TRANSIENT_ERROR に遷移し、ジョブのエラーコンテキストは BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK となり、コールバックが返した HRESULT がエラーとして設定されます。コールバックを呼び出せなかった場合(たとえば、プログラムの終了後に BITS がサーバー証明書を検証する必要が生じた場合など)、ジョブのエラーコードは BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED になります。次回アプリケーションを実行したときに、検証コールバックを再度設定してジョブを再開することで、このエラーを解消できます。
このジョブの HTTP カスタムヘッダーを書き込み専用に設定します。
戻り値
戻り値は常に S_OK です。
解説(Remarks)
BITS のカスタムヘッダーに、同一コンピューター上で実行されている他のプログラムから読み取られたくないセキュリティ情報(API トークンなど)を含める必要がある場合に、この API を使用します。もちろん BITS プロセス自身はこれらのヘッダーを読み取り、HTTP 接続経由で送信できます。ヘッダーをいったん書き込み専用に設定すると、その設定を解除することはできません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IBackgroundCopyJobHttpOptions3 "{8A9263D3-FD4C-4EDA-9B28-30132A4D4E3C}"
#usecom global IBackgroundCopyJobHttpOptions3 IID_IBackgroundCopyJobHttpOptions3 "{}"
#comfunc global IBackgroundCopyJobHttpOptions3_SetServerCertificateValidationInterface 13 sptr
#comfunc global IBackgroundCopyJobHttpOptions3_MakeCustomHeadersWriteOnly 14
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。