IXMLHTTPRequest2Callback
COM公式ドキュメント
未完了の IXMLHTTPRequest2 リクエストを持つアプリケーションに対して、HTTP リクエストおよびレスポンスの処理に影響するイベントを通知するコールバックを定義します。注 このインターフェイスは Windows Phone 8.1 でサポートされます。 .
解説(Remarks)
IXMLHTTPRequest2 インターフェイスのメソッドは非同期であるため、アプリケーションはコールバック通知を受け取るために、IXMLHTTPRequest2 インターフェイスの Open メソッドの呼び出しで IXMLHTTPRequest2Callback オブジェクトをパラメーターとして渡す必要があります。
IXMLHTTPRequest2Callback インターフェイスは IXMLHTTPRequest3Callback インターフェイスによって拡張されます。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
クライアントが送信した HTTP リクエストを、サーバーが新しい URL にリダイレクトしたときに発生します。
| pXHR | IXMLHTTPRequest2* | in | リダイレクトされる HTTP リクエスト オブジェクト。 |
| pwszRedirectUrl | LPWSTR | in | HTTP リクエストの新しい URL。 |
戻り値
解説(Remarks)
リクエストのリダイレクトを許可しない場合は、pXHR オブジェクトの Abort メソッドを呼び出すことができます。
XMLHTTPRequest2 は、1 つのリクエストにつき最大 100 回のリダイレクトという制限を課します。この制限を超えるリダイレクトが発生すると OnError イベントが生成されます。 アプリケーションはリダイレクトのヘッダーにアクセスできません。
最終的なリダイレクトが完了し、最終的な URL に到達すると、アプリケーションは OnHeadersAvailable コールバックを受け取ります。
HTTP リクエストがサーバーに送信され、サーバーがレスポンス ヘッダーを返した後に発生します。
| pXHR | IXMLHTTPRequest2* | in | ヘッダーを返す最初の HTTP リクエスト オブジェクト。 |
| dwStatus | DWORD | in | リクエストのステータス コード。 注 このパラメーターに指定可能な値には、デスクトップ アプリ向けに winhttp.h で定義されている HTTP_STATUS_* の値も含まれます。
|
| pwszStatus | LPWSTR | in | リクエストのステータス コードを人間が読める形式で表した、null で終わる文字列。 |
戻り値
解説(Remarks)
個々のレスポンス ヘッダーを参照するには、IXMLHTTPRequest2 インターフェイスの GetResponseHeader メソッドを呼び出します。すべてのレスポンス ヘッダーを参照するには、GetAllResponseHeaders メソッドを呼び出します。リクエストを取り消すには、pXHR オブジェクトの Abort メソッドを呼び出します。
クライアントがサーバーから HTTP レスポンス データの一部を受信したときに発生します。
| pXHR | IXMLHTTPRequest2* | in | 最初の HTTP リクエスト。 |
| pResponseStream | ISequentialStream* | in | 受信中のレスポンス ストリーム。クライアントは ISequentialStream::Read を呼び出してデータの処理を開始することも、レスポンス全体を受信するまで待つこともできます。このレスポンス ストリームは、読み取りと書き込みの同時実行を防ぐストリーム同期オブジェクトでラップされているため、アプリケーションが独自の同期処理を実装する必要はありません。 |
戻り値
解説(Remarks)
このコールバック関数が戻ると、アプリケーションはレスポンス全体をまだ受信していなくても、HTTP レスポンスのデータの処理を開始できます。ただし、このコールバック関数が戻るまで、そのリクエストの受信は中断されます。また、このコールバックは 1 回のリクエスト中に複数回呼び出されることがあります。
このコールバック関数はブロックしてはならず、UI の更新など負荷の高い処理を行わせるべきではありません。
カスタム ストリームでは、OnDataAvailable が発生する前に ISequentialStream::Write が呼び出されます。クライアントはカスタム ストリームに対して ISequentialStream::Read を呼び出す代わりに、Write の呼び出しから直接データを処理でき、新しいデータが利用可能になったことを示すものとして Write の呼び出しを利用できます。
クライアントがサーバーから完全なレスポンスを受信したときに発生します。
| pXHR | IXMLHTTPRequest2* | in | 最初の HTTP リクエスト オブジェクト |
| pResponseStream | ISequentialStream* | in | 受信中のレスポンス ストリーム。クライアントは ISequentialStream::Read を呼び出してデータの処理を開始することも、後で処理するために pResponseStream への参照を保持することもできます。このレスポンス ストリームは、読み取りと書き込みの同時実行を防ぐストリーム同期オブジェクトでラップされているため、アプリケーションが独自の同期処理を実装する必要はありません。 |
戻り値
解説(Remarks)
このイベントが発生すると、アプリケーションは HTTP レスポンスのデータの処理を開始できます。これより前に OnDataAvailable イベントが発生していた場合は、このイベントの発生前に処理を開始することもできます。
OnError が呼び出されない限り、OnResponseReceived の呼び出しが最後のコールバックとなります。クライアントは、IXMLHTTPRequest2 オブジェクトへの参照の解放を含め、必要なクリーンアップを行う必要があります。
カスタム ストリームでは、OnResponseReceived が発生する前に、書き込みバイト数 0 を指定した ISequentialStream::Write が呼び出されます。クライアントはカスタム ストリームに対して ISequentialStream::Read を呼び出す代わりに、Write の呼び出しから直接データを処理でき、レスポンスの受信が完了したことを示すものとして 0 バイトの Write の呼び出しを利用できます。
エラーが発生したとき、またはリクエストが中止されたときに発生します。
| pXHR | IXMLHTTPRequest2* | in | 最初の HTTP リクエスト。 |
| hrError | HRESULT | in | HTTP リクエストで発生したエラーを表すコード。 |
戻り値
解説(Remarks)
OnResponseReceived によって示されるリクエストの正常完了が起きない限り、OnError の呼び出しが最後のコールバックとなります。クライアントは、IXMLHTTPRequest2 オブジェクトへの参照の解放を含め、必要なクリーンアップを行う必要があります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IXMLHTTPRequest2Callback "{A44A9299-E321-40DE-8866-341B41669162}"
#usecom global IXMLHTTPRequest2Callback IID_IXMLHTTPRequest2Callback "{}"
#comfunc global IXMLHTTPRequest2Callback_OnRedirect 3 sptr,wstr
#comfunc global IXMLHTTPRequest2Callback_OnHeadersAvailable 4 sptr,int,wstr
#comfunc global IXMLHTTPRequest2Callback_OnDataAvailable 5 sptr,sptr
#comfunc global IXMLHTTPRequest2Callback_OnResponseReceived 6 sptr,sptr
#comfunc global IXMLHTTPRequest2Callback_OnError 7 sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。