WINHTTP_STATUS_CALLBACK コールバック関数 (winhttp.h)

[アーティクル]
03/15/2023

WINHTTP_STATUS_CALLBACK型は、アプリケーション定義の状態コールバック関数を表します。

構文

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

パラメーター

[in] hInternet

コールバック関数が呼び出されるハンドル。

[in] dwContext

hInternet パラメーターのハンドルに関連付けられているアプリケーション定義のコンテキスト値を指定する DWORD へのポインター。

コンテキスト値は、WINHTTP_OPTION_CONTEXT_VALUE オプションを指定して WinHttpSetOption を呼び出すことによって、セッション、接続、または要求ハンドルに割り当てることができます。または、 WinHttpSendRequest を使用して、コンテキスト値を要求ハンドルに関連付けることができます。

[in] dwInternetStatus

コールバック関数が呼び出される理由を示す状態コードを指定する 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_AVAILABLE

WinHttpReadData を使用してデータを取得できます。 lpvStatusInformation パラメーターは、使用可能なデータのバイト数を含む DWORD を指します。 dwStatusInformationLength パラメーター自体は 4 (DWORD のサイズ) です。

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

HINTERNET ハンドルが作成されました。 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_REDIRECT

HTTP 要求によって要求が自動的にリダイレクトされようとしています。 lpvStatusInformation パラメーターには、新しい URL を示す LPWSTR へのポインターが含まれています。この時点で、アプリケーションはリダイレクト応答を使用してサーバーから返されたデータを読み取り、応答ヘッダーに対してクエリを実行できます。ハンドルを閉じて操作を取り消すこともできます。

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

HTTP 要求の送信中にエラーが発生しました。 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_COMPLETE

WinHttpGetProxyForUrlEx の呼び出しによって開始された操作が完了しました。 WinHttpReadData を使用してデータを取得できます。

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

WinHttpWebSocketClose の呼び出しによって接続が正常に閉じられました。 lpvStatusInformation パラメーターは NULL です。

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

WinHttpWebSocketShutdown の呼び出しによって接続が正常にシャットダウンされました。 lpvStatusInformation パラメーターは NULL です。

[in] lpvStatusInformation

コールバック関数のこの呼び出しに関連する情報を指定するバッファーへのポインター。これらのデータの形式は、 dwInternetStatus 引数の値によって異なります。詳細については、「 dwInternetStatus」を参照してください。

dwInternetStatus 引数がWINHTTP_CALLBACK_STATUS_SECURE_FAILUREの場合、lpvStatusInformation は、次の 1 つ以上の値のビットごとの OR の組み合わせである DWORD を指します。

値	意味
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED	認定失効チェックは有効になっていますが、失効チェックは証明書が失効しているかどうかを確認できませんでした。失効の確認に使用されたサーバーに到達できない可能性があります。
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT	SSL 証明書が無効です。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED	SSL 証明書が取り消されました。
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA	この関数は、サーバーの証明書を生成した証明機関に慣れていない。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID	SSL 証明書の共通名 (ホスト名フィールド) が正しくありません。たとえば、www.microsoft.com 入力し、証明書に共通名が www.msn.com と表示されている場合などです。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID	サーバーから受信した SSL 証明書の日付が正しくありません。証明書の有効期限が切れています。
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR	アプリケーションで SSL ライブラリの読み込み中に内部エラーが発生しました。

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT 状態コールバックは、 lpvStatusInformation によって指される LPWSTR の文字数に対応する dwStatusInformationLength 値を提供します。

戻り値

なし

解説

コールバック関数は、別の要求に対して別のスレッドで呼び出し、現在の要求の同じスレッドに再入力できるため、スレッドセーフで再入可能である必要があります。したがって、処理中に再入を安全に処理するようにコーディングする必要があります。 dwInternetStatus パラメーターが WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING と等しい場合、コールバックは同じ要求の再入を処理できる必要はありません。これは、このコールバックが最後であることが保証され、この要求の他のメッセージが処理されるときには発生しないためです。

状態コールバック関数は、通知フラグを介して非同期操作の状態の更新を受け取ります。特定の操作が完了したことを示す通知は、完了通知と呼ばれるか、完了と呼ばれます。次の表に、6 つの完了フラグと、このフラグを受信したときに完了した対応する関数を示します。

完了フラグ	機能
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE	WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE	WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE	WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE	WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE	WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR	上記の関数は、エラーが発生したときに機能します。

コールバックは要求の処理中に行われるため、アプリケーションは、ネットワーク上のデータスループットの低下を回避するために、コールバック関数にできるだけ少ない時間を費やす必要があります。たとえば、コールバック関数でダイアログボックスを表示する操作は、サーバーが要求を終了するような長い操作になる可能性があります。

コールバック関数は、要求を開始したスレッドとは異なるスレッドコンテキストで呼び出すことができます。

同様に、WinHttp を非同期で呼び出すときにコールバックスレッドアフィニティはありません。呼び出しは 1 つのスレッドから開始される可能性がありますが、他のスレッドはコールバックを受け取ることができます。

メモ Windows XP および Windows 2000 での実装の詳細については、「ランタイム要件」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP、Windows 2000 Professional sp3 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003、Windows 2000 Server SP3 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winhttp.h
再頒布可能パッケージ	Windows XP および Windows 2000 で WinHTTP 5.0 および Internet Explorer 5.01 以降。

こちらもご覧ください

WinHTTP バージョン

WinHttpSetStatusCallback

次の方法で共有