WinHttpSetStatusCallback 関数 (winhttp.h)
WinHttpSetStatusCallback 関数は、操作中に進行状況が行われると WinHTTP が呼び出すことができるコールバック関数を設定します。
構文
WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
[in] HINTERNET hInternet,
[in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
[in] DWORD dwNotificationFlags,
[in] DWORD_PTR dwReserved
);
パラメーター
[in] hInternet
コールバックを設定する HINTERNET ハンドル。
[in] lpfnInternetCallback
進行状況が行われたときに呼び出すコールバック関数へのポインター。 既存のコールバック関数を削除するには、これを NULL に 設定します。 コールバック関数の詳細については、「 WINHTTP_STATUS_CALLBACK」を参照してください。
[in] dwNotificationFlags
コールバック関数をアクティブにするイベントを示すフラグを指定する符号なし long 整数値。
有効値は次のとおりです。
| 値 | 意味 |
|---|---|
|
完了通知時にアクティブ化します。 このフラグは、読み取り操作または書き込み操作に必要なすべての通知を使用することを指定します。 入力候補の一覧については、「 WINHTTP_STATUS_CALLBACK 」を参照してください。 |
|
完了を含む状態変更通知を有効にします。 通知 の 一覧については、「WINHTTP_STATUS_CALLBACK」を参照してください。 |
|
名前解決の開始時と完了時にアクティブになります。 |
|
サーバーへの接続の開始と完了時にアクティブ化します。 |
|
プロキシ サーバーを検出するときにアクティブ化します。 |
|
データのクエリを完了するときにアクティブ化します。 |
|
応答ヘッダーを取得できる場合にアクティブ化します。 |
|
データ読み取り操作の完了時にアクティブ化します。 |
|
非同期エラーが発生したときにアクティブになります。 |
|
WinHttpSendRequest を使用して要求ヘッダーの送信を開始して完了するとアクティブになります。 |
|
WinHttpSendRequest で要求ヘッダーが送信されたときにアクティブ化します。 |
|
データポスト操作の完了時にアクティブ化します。 |
|
HTTP サーバーからのリソースの受信の開始時と完了時にアクティブ化します。 |
|
HTTP 接続の終了を開始および完了するときにアクティブ化します。 |
|
HINTERNET ハンドルが作成または閉じられたときにアクティブになります。 |
|
要求がリダイレクトされたときにアクティブ化します。 |
|
サーバーから中間 (100 レベル) の状態コード メッセージを受信するときにアクティブ化します。 |
|
セキュリティで保護された接続エラー時にアクティブ化します。 |
[in] dwReserved
このパラメーターは予約されており、 NULL である必要があります。
戻り値
成功した場合は、以前に定義された状態コールバック関数へのポインターを返し、以前に定義された状態コールバック関数がない場合は NULL を 返します。 コールバック関数 を インストールできなかった場合は、WINHTTP_INVALID_STATUS_CALLBACKを返します。 拡張エラー情報については、 GetLastError を呼び出します。 返されるエラー コードは次のとおりです。
| エラー コード | 説明 |
|---|---|
|
指定されたハンドルの種類が、この操作に対して正しくありません。 |
|
内部エラーが発生しました。 |
|
要求された操作を完了するのに十分なメモリが使用できませんでした。 (Windows エラー コード) |
注釈
要求ハンドルを作成する前にセッション ハンドルにコールバックを設定した場合、要求ハンドルは親セッションからコールバック関数ポインターを継承します。
WinHTTP が非同期モードで使用されている場合 (つまり、WinHttpOpen でWINHTTP_FLAG_ASYNCが設定されている場合) でも、この関数は同期的に動作します。 戻り値は成功または失敗を示します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
同期関数と非同期関数の両方で、コールバック関数を使用して、名前の解決、サーバーへの接続など、要求の進行状況を示します。 非同期操作にはコールバック関数が必要です。
コールバック関数は、任意のハンドルに設定でき、派生ハンドルによって継承されます。 以前のコールバック値を使用する必要がある保留中の要求がない場合は、 WinHttpSetStatusCallback を使用してコールバック関数を変更できます。 ただし、ハンドルのコールバック関数を変更しても、 WinHttpConnect によって返されるなどの派生ハンドルのコールバックは変更されません。 各レベルでコールバック関数を変更する必要があります。
多くの WinHTTP 関数は、ネットワーク上で複数の操作を実行します。 各操作の完了には時間がかかる場合があり、それぞれが失敗する可能性があります。
WinHttpSetStatusCallback 関数を開始した後、時間のかかるネットワーク操作を監視するために、WinHTTP 内からコールバック関数にアクセスできます。
非同期処理の終了時に、アプリケーションによってコールバック関数が NULL に設定される場合があります。 これにより、クライアント アプリケーションが追加の通知を受信できなくなります。
次のコード スニペットは、コールバック関数を NULL に設定するための推奨される方法を示しています。
WinHttpSetStatusCallback( hOpen,
NULL,
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
NULL );
ただし、WinHTTP は WinHttpSetStatusCallback をワーカー スレッドと同期しないことに注意してください。 アプリケーションが WinHttpSetStatusCallback を呼び出したときに別のスレッドで発生したコールバックが進行中の場合、アプリケーションは、 WinHttpSetStatusCallback がコールバック関数を NULL に正常に設定して返した後でも、コールバック通知を受け取ります。
例
次の例は、非同期 WinHTTP 関数のコールバック関数をインストールする方法を示しています。 この例では、"AsyncCallback( )" という名前 のWINHTTP_STATUS_CALLBACK 関数が以前に実装されていることを前提としています。
// Use WinHttpOpen to obtain an HINTERNET handle.
HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
if (hSession)
{
// Install the status callback function.
WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
(WINHTTP_STATUS_CALLBACK)AsyncCallback,
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
NULL);
// Place additional code here.
// When finished, release the HINTERNET handle.
WinHttpCloseHandle(hSession);
}
else
{
printf("Error %u in WinHttpOpen.\n", GetLastError());
}
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP、Windows 2000 Professional SP3 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2003、Windows 2000 Server SP3 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winhttp.h |
| Library | Winhttp.lib |
| [DLL] | Winhttp.dll |
| 再頒布可能パッケージ | Windows XP および Windows 2000 では、WinHTTP 5.0 およびインターネット エクスプローラー 5.01 以降がインストールされています。 |