HttpReceiveHttpRequest 関数 (http.h)
HttpReceiveHttpRequest 関数は、指定された要求キューから、次に使用可能な HTTP 要求を同期的または非同期的に取得します。
構文
HTTPAPI_LINKAGE ULONG HttpReceiveHttpRequest(
[in] HANDLE RequestQueueHandle,
[in] HTTP_REQUEST_ID RequestId,
[in] ULONG Flags,
[out] PHTTP_REQUEST RequestBuffer,
[in] ULONG RequestBufferLength,
[out, optional] PULONG BytesReturned,
[in, optional] LPOVERLAPPED Overlapped
);
パラメーター
[in] RequestQueueHandle
次に使用可能な要求を取得する要求キューへのハンドル。 要求キューが作成され、そのハンドルが HttpCreateRequestQueue 関数の呼び出しによって返されます。
Windows Server 2003 SP1 と Windows XP SP2: 要求キューへのハンドルは、 HttpCreateHttpHandle 関数によって作成されます。
[in] RequestId
要求を取得する最初の呼び出しでは、このパラメーターを HTTP_NULL_IDする必要があります。 その後、要求全体を取得するために複数の呼び出しが必要な場合は、HttpReceiveHttpRequest または HttpReceiveRequestEntityBody を呼び出し、RequestID を pRequestBuffer が指すHTTP_REQUEST構造体の RequestId メンバーで返される値に設定できます。
[in] Flags
次のいずれかの値を指定できるパラメーター。
| 値 | 説明 |
|---|---|
|
要求ヘッダーのみが取得されます。エンティティ本体はコピーされません。 |
|
使用可能なエンティティ本文が要求ヘッダーと共にコピーされます。 HTTP_REQUEST構造体の pEntityChunks メンバーは、エンティティ本体を指します。 |
|
すべてのエンティティ本体が要求ヘッダーと共にコピーされます。 HTTP_REQUEST構造体の pEntityChunks メンバーは、エンティティ本体を指します。 |
[out] RequestBuffer
関数が HTTP 要求の HTTP_REQUEST 構造体とエンティティ本体をコピーするバッファーへのポインター。 HTTP_REQUEST。RequestId には、この HTTP 要求の識別子が含まれています。これは、アプリケーションが後続の呼び出し HttpReceiveRequestEntityBody、 HttpSendHttpResponse、または HttpSendResponseEntityBody で使用できます。
[in] RequestBufferLength
pRequestBuffer バッファーのサイズ (バイト単位)。
[out, optional] BytesReturned
省略可能。 エンティティ本体のサイズ (バイト単位)、またはエンティティ本体の残りの部分を受け取る変数へのポインター。
pOverlapped を使用して非同期呼び出しを行う場合は、pBytesReceived を NULL に設定します。 それ以外の場合、 pOverlapped が NULL に設定されている場合、 pBytesReceived には有効なメモリ アドレスを含める必要があり、 NULL に設定することはできません。
[in, optional] Overlapped
非同期呼び出しの場合は、 pOverlapped を OVERLAPPED 構造体をポイントするように設定します。同期呼び出しの場合は、NULL に設定 します。
同期呼び出しは、要求が指定されたキューに到着し、その一部またはすべてが取得されるまでブロックしますが、非同期呼び出しはすぐに ERROR_IO_PENDING を返し、呼び出し元のアプリケーションは GetOverlappedResult または I/O 完了ポートを使用して操作がいつ完了するかを判断します。 同期に OVERLAPPED 構造体を使用する方法の詳細については、以下を参照してください。
同期と重複入力と出力。
戻り値
関数が成功した場合、戻り値は NO_ERROR。
関数が非同期的に使用されている場合、戻り値 ERROR_IO_PENDING は、次の要求がまだ準備ができておらず、通常の重複した I/O 完了メカニズムを使用して後で取得されることを示します。
関数が失敗した場合、戻り値は次のいずれかのエラー コードになります。
| 値 | 説明 |
|---|---|
|
指定されたパラメーターの 1 つ以上が使用できない形式です。 |
|
指定された 1 つ以上のパラメーターは、無効なメモリ バッファーまたは整列されていないメモリ バッファーを指します。 pRequestBuffer パラメーターは、HTTP_REQUEST構造体のメモリアラインメント要件以上のメモリアラインメントを持つ有効なメモリ バッファーを指す必要があります。 |
|
RequestBufferLength の値は、受信した要求ヘッダーのサイズ以上ですが、要求構造とエンティティ本体の合計サイズほど大きくない。 エンティティ本体の残りの部分を読み取るために必要なバッファー サイズは、これが NULL 以外の場合と呼び出しが同期である場合は、pBytesReceived パラメーターで返されます。 すべてのデータを取得するのに十分な大きさのバッファーを使用して関数を再度呼び出します。 |
|
指定された要求は既に完全に取得されています。この場合、 pBytesReceived が指す値は意味を持たず、 pRequestBuffer を調べてはなりません。 |
|
WinError.h で定義されている システム エラー コード 。 |
解説
特定の要求を取得するには、複数の呼び出しが必要になる場合があります。 たとえば、 Flags パラメーターが 0 に設定されている場合、 HttpReceiveHttpRequest は要求ヘッダー構造のみをバッファーにコピーし、エンティティ本文のコピーを試みません。 この場合、 HttpReceiveRequestEntityBody 関数を使用してエンティティ本体を取得するか、 HttpReceiveHttpRequest に対して 2 回目の呼び出しを行うことができます。
または、アプリケーションによって提供されるバッファーが、要求の全部または一部を受信するのに十分な大きさでない場合があります。 要求の少なくとも一部を確実に受信するには、アプリケーションで少なくとも 4 KB のバッファーを提供し、ほとんどの HTTP 要求に対応することをお勧めします。 または、不明なヘッダーとして解析された認証ヘッダーは、最大 12 KB まで追加できるため、認証/承認を使用する場合は、少なくとも 16 KB のバッファー サイズをお勧めします。
HttpReceiveHttpRequest がERROR_MORE_DATAを返した場合、アプリケーションは引き続き追加の呼び出しを行い、HTTP_REQUESTを渡すことによって、追加の各呼び出しで要求を識別します。ERROR_HANDLE_EOFが返されるまで、最初の呼び出しによって返される RequestId 値。
要件
| サポートされている最小のクライアント | Windows Vista、SP2 を使用した Windows XP [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | http.h |
| Library | Httpapi.lib |
| [DLL] | Httpapi.dll |