Win での HINTERNET ハンドルHTTP
Microsoft Windows HTTP Services (WinHTTP) は、HTTP プロトコルを使用するときに必要な設定と情報を追跡するためにハンドルを使用します。 各ハンドルは、HTTP セッション、HTTP サーバーとの接続、または特定のリソースに関連する情報を保持します。 このトピックでは、さまざまな種類のハンドル、これらのハンドルの名前付け規則、およびそれらの階層構造について説明します。
HINTERNET ハンドルについて
WinHTTP によって作成および使用されるハンドルは HINTERNET ハンドルと呼ばれます。 WinHTTP 関数は、他のハンドルと互換性のない HINTERNET ハンドルを返します。そのため、 ReadFile や CloseHandle などの関数では使用できません。 同様に、WinHTTP 関数では他のハンドルを使用できません。 たとえば、 CreateFile によって返されるハンドルを WinHttpReadData に渡すことはできません。 ハンドルを使用した API 呼び出しの進行中は、これらの HINTERNET ハンドルを閉じることができません。 競合状態を回避するために、アプリケーションはハンドルを保護し、API 呼び出しが進行中である限り閉じないようにする必要があります。
Microsoft Win32 Internet (WinInet) 関数では 、HINTERNET ハンドルも使用されます。 ただし、WinInet 関数で使用されるハンドルは、WinHTTP 関数で使用されるハンドルと交換できません。 WinInet の詳細については、「 WinINet について」を参照してください。
WinHttpCloseHandle 関数は、WinHTTP HINTERNET ハンドルを閉じます。
名前付けハンドル
WinHTTP ドキュメント全体で、アプリケーション プログラミング インターフェイス (API) とサンプル コードの関数の説明には、さまざまな種類の HINTERNET ハンドルの作成と使用が示されています。 使用可能なさまざまな種類のハンドルを追跡するために、これらのハンドルの名前付けには一貫性があります。 次の表は、ドキュメントの規則で使用される識別子を示しています。
| ハンドルの種類 | 関数の作成ハンドル | 識別子 |
|---|---|---|
| 汎用ハンドル | WinHttpOpen、 WinHttpConnect、または WinHttpOpenRequest | hInternet |
| セッション ハンドル | WinHttpOpen | hSession |
| 接続ハンドル | WinHttpConnect | hConnect |
| 要求ハンドル | WinHttpOpenRequest | hRequest |
| Web ソケット ハンドル | WinHttpWebSocketCompleteUpgrade | hWebSocket |
階層の処理
HINTERNET ハンドルは階層に保持されます。 WinHttpOpen によって返されるハンドルは、セッション HINTERNET ハンドルです。 WinHttpOpen を呼び出すと、WinHTTP 関数が初期化され、セッション ハンドルの有効期間を通じてユーザー情報と設定を維持するセッション コンテキストが開始されます。 WinHttpConnect は、ターゲット HTTP または HTTPS サーバーを指定し、接続 HINTERNET ハンドルを作成します。 既定では、接続ハンドルはセッション ハンドルの設定を継承します。 WinHttpOpenRequest の呼び出しで指定された各リソースには、要求 HINTERNET ハンドルが割り当てられます。
次の図は 、HINTERNET ハンドルの階層を示しています。 図の各ボックスは、 HINTERNET ハンドルを返す WinHTTP 関数を表します。
ハンドルを閉じた後、最後の WINHTTP_CALLBACK_STATUS_HANDLE_CLOSED 値が返されてハンドルが完全に閉じられるまで (または、保留中の非同期操作からコールバックを追跡して待機し、そのハンドルを使用してそれ以上の操作が試行されないようにするなど、アプリケーションが独自の同等の同期を実行するまで) ハンドルに対するコールバック通知を受け取るようにアプリケーションを準備する必要があります。
セッション ハンドルは、作成に使用されるすべての接続ハンドルの親と呼びます。同様に、接続ハンドルとその親セッション ハンドルは、接続ハンドルを作成するために使用されるすべての要求ハンドルの親と呼びます。
親ハンドルを閉じると、親ハンドルが閉じていない場合でも、その親ハンドルが間接的に無効になり、それを使用する後続の要求はエラー ERROR_INVALID_HANDLEで失敗します。 保留中の非同期要求は、正しく完了するために依存できません。
次の図は、WinHttpOpenRequest によって作成された HINTERNET ハンドルを使用する関数を示しています。 網掛けされたボックスはハンドルを作成する WinHTTP 関数を表し、プレーン ボックスにはそれらの HINTERNET ハンドルを使用する関数が表示されます。 この図は、WinHTTP 関数が通常呼び出される順序を示すように編成されています。
ハンドル階層の説明
まず、 WinHttpOpen を使用してセッション ハンドルが作成されます。 WinHttpConnect では、セッション ハンドルを最初のパラメーターとして必要とし、指定されたサーバーの接続ハンドルを返します。 要求ハンドルは WinHttpOpenRequest によって作成され、 WinHttpConnect によって作成された接続ハンドルが使用されます。 アプリケーションが要求にヘッダーを追加することを選択した場合、またはアプリケーションで認証用の資格情報を設定する必要がある場合は、この要求ハンドルを使用して WinHttpAddRequestHeaders と WinHttpSetCredentials を呼び出すことができます。 要求は、要求ハンドルを使用する WinHttpSendRequest によって送信されます。 要求を送信した後、 WinHttpWriteData を使用して追加のデータをサーバーに送信するか、アプリケーションを WinHttpReceiveResponse に直接スキップして、サーバーにそれ以上の情報が送信されていないことを指定できます。 この時点で、アプリケーションの目的に応じて、要求ハンドルを使用して WinHttpQueryHeaders、 WinHttpQueryAuthSchemes を呼び出したり、 WinHttpQueryDataAvailable と WinHttpReadData を使用してリソースを取得したりできます。
ハンドル階層内の Web ソケット
Web ソケット ハンドルは、接続ハンドルとセッション ハンドルを継承し、要求ハンドルと同様の位置をハンドル階層内で占有します。 Web ソケット ハンドルを作成するには、要求ハンドルが存在する必要があります。ただし、Web ソケット ハンドルが作成されると、要求が閉じられ、Web ソケット ハンドルは引き続き機能します。