WINHTTP_STATUS_CALLBACK
コールバックシグネチャ
void WINHTTP_STATUS_CALLBACK(
void* hInternet,
UINT_PTR dwContext,
DWORD dwInternetStatus,
void* lpvStatusInformation,
DWORD dwStatusInformationLength
);パラメーター
| フィールド | 型 | 説明 |
|---|---|---|
| hInternet | void* | コールバック関数が呼び出される対象のハンドル。 |
| dwContext | UINT_PTR | hInternet パラメーターのハンドルに関連付けられた、アプリケーション定義のコンテキスト値を指定する DWORD へのポインター。 コンテキスト値は、WinHttpSetOption を WINHTTP_OPTION_CONTEXT_VALUE オプションとともに呼び出すことで、セッション、接続、または要求のハンドルに割り当てることができます。あるいは、WinHttpSendRequest を使用して、コンテキスト値を要求ハンドルに関連付けることもできます。 |
| dwInternetStatus | DWORD | コールバック関数が呼び出された理由を示すステータスコードを指定する DWORD を指します。次のいずれかの値になります。 WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTIONサーバーへの接続を切断しています。lpvStatusInformation パラメーターは NULL です。 WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVERサーバーへの接続に成功しました。lpvStatusInformation パラメーターには、サーバーの IP アドレスをドット表記で示す LPWSTR へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVERサーバーに接続しています。lpvStatusInformation パラメーターには、サーバーの IP アドレスをドット表記で示す LPWSTR へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSEDサーバーへの接続を正常に切断しました。lpvStatusInformation パラメーターは NULL です。 WINHTTP_CALLBACK_STATUS_DATA_AVAILABLEWinHttpReadData で取得できるデータがあります。lpvStatusInformation パラメーターは、利用可能なデータのバイト数を格納した DWORD を指します。dwStatusInformationLength パラメーター自体は 4 (DWORD のサイズ) です。 WINHTTP_CALLBACK_STATUS_HANDLE_CREATEDHINTERNET ハンドルが作成されました。lpvStatusInformation パラメーターには、HINTERNET ハンドルへのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSINGこのハンドル値は破棄されました。lpvStatusInformation パラメーターには、HINTERNET ハンドルへのポインターが格納されます。このハンドルに対するコールバックは、これ以降発生しません。 WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE応答ヘッダーを受信し、WinHttpQueryHeaders で取得できる状態になりました。lpvStatusInformation パラメーターは NULL です。 WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSEサーバーから中間 (100 番台) のステータスコードメッセージを受信しました。lpvStatusInformation パラメーターには、そのステータスコードを示す DWORD へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_NAME_RESOLVEDサーバーの IP アドレスの検出に成功しました。lpvStatusInformation パラメーターには、解決された名前を示す LPWSTR へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_READ_COMPLETEサーバーからのデータの読み取りに成功しました。lpvStatusInformation パラメーターには、WinHttpReadData の呼び出しで指定したバッファーへのポインターが格納されます。dwStatusInformationLength パラメーターには、読み取ったバイト数が格納されます。 WinHttpWebSocketReceive で使用される場合、lpvStatusInformation パラメーターには WINHTTP_WEB_SOCKET_STATUS 構造体へのポインターが格納され、dwStatusInformationLength パラメーターは lpvStatusInformation のサイズを示します。 WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE要求に対するサーバーの応答を待機しています。lpvStatusInformation パラメーターは NULL です。 WINHTTP_CALLBACK_STATUS_REDIRECTHTTP 要求が、これから自動的にリダイレクトされます。lpvStatusInformation パラメーターには、新しい URL を示す LPWSTR へのポインターが格納されます。この時点でアプリケーションは、リダイレクト応答でサーバーから返されたデータを読み取り、応答ヘッダーを照会できます。また、ハンドルを閉じることで操作をキャンセルすることもできます。 WINHTTP_CALLBACK_STATUS_REQUEST_ERRORHTTP 要求の送信中にエラーが発生しました。lpvStatusInformation パラメーターには、WINHTTP_ASYNC_RESULT 構造体へのポインターが格納されます。その dwResult メンバーは呼び出された関数の ID を示し、dwError は戻り値を示します。 WINHTTP_CALLBACK_STATUS_REQUEST_SENT情報要求をサーバーへ正常に送信しました。lpvStatusInformation パラメーターには、送信されたバイト数を示す DWORD へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_RESOLVING_NAMEサーバー名の IP アドレスを検索しています。lpvStatusInformation パラメーターには、解決中のサーバー名へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVEDサーバーからの応答を正常に受信しました。lpvStatusInformation パラメーターには、受信したバイト数を示す DWORD へのポインターが格納されます。 WINHTTP_CALLBACK_STATUS_SECURE_FAILUREサーバーとのセキュリティで保護された (HTTPS) 接続を確立する際に、1 つ以上のエラーが発生しました。lpvStatusInformation パラメーターには、エラー値のビットごとの OR の組み合わせである DWORD へのポインターが格納されます。詳細については、lpvStatusInformation の説明を参照してください。 WINHTTP_CALLBACK_STATUS_SENDING_REQUEST情報要求をサーバーへ送信しています。lpvStatusInformation パラメーターは NULL です。 WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE要求が正常に完了しました。lpvStatusInformation パラメーターは、WinHttpSendRequest に渡された lpOptional の値 (最初の要求本文) であり、dwStatusInformationLength パラメーターは、正常に書き込まれた最初の本文のバイト数 (WinHttpSendRequest に渡された dwOptionalLength の値) を示します。 WINHTTP_CALLBACK_STATUS_WRITE_COMPLETEサーバーへのデータの書き込みに成功しました。lpvStatusInformation パラメーターには、書き込まれたバイト数を示す DWORD へのポインターが格納されます。 WinHttpWebSocketSend で使用される場合、lpvStatusInformation パラメーターには WINHTTP_WEB_SOCKET_STATUS 構造体へのポインターが格納され、dwStatusInformationLength パラメーターは lpvStatusInformation のサイズを示します。 WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETEWinHttpGetProxyForUrlEx の呼び出しによって開始された操作が完了しました。WinHttpReadData で取得できるデータがあります。 WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETEWinHttpWebSocketClose の呼び出しにより、接続が正常に閉じられました。lpvStatusInformation パラメーターは NULL です。 WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETEWinHttpWebSocketShutdown の呼び出しにより、接続が正常にシャットダウンされました。lpvStatusInformation パラメーターは NULL です。 |
| lpvStatusInformation | void* | コールバック関数へのこの呼び出しに関連する情報を格納したバッファーへのポインター。これらのデータの形式は、dwInternetStatus 引数の値によって異なります。詳細については、dwInternetStatus を参照してください。 dwInternetStatus 引数が WINHTTP_CALLBACK_STATUS_SECURE_FAILURE の場合、lpvStatusInformation は、次の値のうち 1 つ以上のビットごとの OR の組み合わせである DWORD を指します。 |
| dwStatusInformationLength | DWORD | WINHTTP_CALLBACK_STATUS_REDIRECT のステータスコールバックでは、dwStatusInformationLength の値として、lpvStatusInformation が指す LPWSTR の文字数が渡されます。 |
公式ドキュメント
WINHTTP_STATUS_CALLBACK 型は、アプリケーション定義のステータスコールバック関数を表します。
解説(Remarks)
このコールバック関数は、別の要求のために他のスレッドから呼び出されたり、現在の要求のために同じスレッドで再入されたりする可能性があるため、スレッドセーフかつ再入可能である必要があります。したがって、処理中の再入を安全に扱えるように実装しなければなりません。dwInternetStatus パラメーターが WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING の場合は、このコールバックが必ず最後のものであることが保証され、この要求に関する他のメッセージの処理中には発生しないため、同じ要求についての再入に対応する必要はありません。
ステータスコールバック関数は、通知フラグを通じて非同期操作の状況の更新を受け取ります。特定の操作が完了したことを示す通知は、完了通知 (completion) と呼ばれます。次の表に、6 つの完了フラグと、そのフラグを受け取った時点で完了している対応する関数を示します。
コールバックは要求の処理中に行われるため、アプリケーションはネットワークのデータスループットを低下させないよう、コールバック関数内での処理時間を可能な限り短くする必要があります。たとえば、コールバック関数内でダイアログボックスを表示すると、処理に時間がかかりすぎてサーバーが要求を終了させてしまうことがあります。
コールバック関数は、要求を開始したスレッドとは異なるスレッドコンテキストで呼び出されることがあります。
同様に、WinHttp を非同期に呼び出す場合、コールバックにスレッドアフィニティはありません。あるスレッドから呼び出しを開始しても、コールバックは他の任意のスレッドで受け取られる可能性があります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)