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_CALLBACK_FLAG_ALL_COMPLETIONS
 完了通知時にアクティブ化します。 このフラグは、読み取り操作または書き込み操作に必要なすべての通知を使用することを指定します。 入力候補の一覧については、「 WINHTTP_STATUS_CALLBACK 」を参照してください。
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS
 完了を含む状態変更通知を有効にします。 通知 の 一覧については、「WINHTTP_STATUS_CALLBACK」を参照してください。
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME
 名前解決の開始時と完了時にアクティブになります。
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER
 サーバーへの接続の開始と完了時にアクティブ化します。
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY
 プロキシ サーバーを検出するときにアクティブ化します。
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE
 データのクエリを完了するときにアクティブ化します。
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE
 応答ヘッダーを取得できる場合にアクティブ化します。
WINHTTP_CALLBACK_FLAG_READ_COMPLETE
 データ読み取り操作の完了時にアクティブ化します。
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR
 非同期エラーが発生したときにアクティブになります。
WINHTTP_CALLBACK_FLAG_SEND_REQUEST
 WinHttpSendRequest を使用して要求ヘッダーの送信を開始して完了するとアクティブになります。
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE
 WinHttpSendRequest で要求ヘッダーが送信されたときにアクティブ化します。
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE
 データポスト操作の完了時にアクティブ化します。
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE
 HTTP サーバーからのリソースの受信の開始時と完了時にアクティブ化します。
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION
 HTTP 接続の終了を開始および完了するときにアクティブ化します。
WINHTTP_CALLBACK_FLAG_HANDLES
 HINTERNET ハンドルが作成または閉じられたときにアクティブになります。
WINHTTP_CALLBACK_FLAG_REDIRECT
 要求がリダイレクトされたときにアクティブ化します。
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE
 サーバーから中間 (100 レベル) の状態コード メッセージを受信するときにアクティブ化します。
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE
 セキュリティで保護された接続エラー時にアクティブ化します。

[in] dwReserved

このパラメーターは予約されており、 NULL である必要があります。

戻り値

成功した場合は、以前に定義された状態コールバック関数へのポインターを返し、以前に定義された状態コールバック関数がない場合は NULL を 返します。 コールバック関数 を インストールできなかった場合は、WINHTTP_INVALID_STATUS_CALLBACKを返します。 拡張エラー情報については、 GetLastError を呼び出します。 返されるエラー コードは次のとおりです。

エラー コード 説明
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
 指定されたハンドルの種類が、この操作に対して正しくありません。
ERROR_WINHTTP_INTERNAL_ERROR
 内部エラーが発生しました。
ERROR_NOT_ENOUGH_MEMORY
 要求された操作を完了するのに十分なメモリが使用できませんでした。 (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 に正常に設定して返した後でも、コールバック通知を受け取ります。

メモ Windows XP と Windows 2000 については、WinHttp スタート ページの 「ランタイム要件 」セクションを参照してください。
 

例

次の例は、非同期 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 以降がインストールされています。

こちらもご覧ください

Microsoft Windows HTTP Services (WinHTTP) について

WINHTTP_STATUS_CALLBACK

WinHTTP バージョン

WinHttpConnect

WinHttpOpen