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

  • [アーティクル]

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

サーバーから Secure Sockets Layer (SSL) 証明書を取得中に、1 つ以上のエラーが発生しました。 lpvStatusInformation パラメーターには フラグが含まれています。 詳細については、 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 およびインターネット エクスプローラー 5.01 以降がインストールされています。

こちらもご覧ください

WinHTTP バージョン

WinHttpSetStatusCallback