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 設定為指向 重迭 結構;針對同步呼叫，請將它設定為 Null。
同步呼叫會封鎖直到要求抵達指定的佇列，並擷取部分或全部，而非同步呼叫會立即傳回 ERROR_IO_PENDING ，而呼叫應用程式接著會使用 GetOverlappedResult 或 I/O 完成埠來判斷作業何時完成。 如需使用 重迭 結構進行同步處理的詳細資訊，請參閱
同步處理和重迭的輸入和輸出。
傳回值
如果函式成功，傳回值 會NO_ERROR。
如果函式是以非同步方式使用， 則傳 回值ERROR_IO_PENDING表示下一個要求尚未就緒，且稍後會透過一般重迭的 I/O 完成機制擷取。
如果函式失敗，傳回值就是下列其中一個錯誤碼。
| 值 | 意義 |
|---|---|
|
一或多個提供的參數格式為無法使用。 |
|
提供的一或多個參數指向無效或未對齊的記憶體緩衝區。 pRequestBuffer參數必須指向記憶體對齊等於或大於HTTP_REQUEST結構的記憶體對齊需求的有效記憶體緩衝區。 |
|
RequestBufferLength的值大於或等於收到的要求標頭大小，但與要求結構和實體主體的合併大小不相同。 如果這是非Null且呼叫為同步，則會在pBytesReceived參數中傳回讀取實體主體剩餘部分所需的緩衝區大小。 使用夠大的緩衝區再次呼叫 函式，以擷取所有資料。 |
|
已完全擷取指定的要求;在此情況下， pBytesReceived 所指向的值沒有意義，而且不應該檢查 pRequestBuffer 。 |
|
WinError.h 中定義的 系統錯誤碼 。 |
備註
擷取指定要求可能需要一個以上的呼叫。 例如，當 Flags 參數設定為零時， HttpReceiveHttpRequest 只會將要求標頭結構複製到緩衝區，而且不會嘗試複製任何實體主體。 在此情況下， HttpReceiveRequestEntityBody 函式可用來擷取實體主體，或對 HttpReceiveHttpRequest進行第二次呼叫。
或者，應用程式所提供的緩衝區可能太大，無法接收要求的所有或部分。 為了確保至少接收部分的要求，建議應用程式至少提供 4 KB 的緩衝區，以容納大部分的 HTTP 要求。 或者，剖析為未知標頭的驗證標頭最多可將 12 KB 新增至該標頭，因此如果使用驗證/授權，建議使用至少 16 KB 的緩衝區大小。
如果 HttpReceiveHttpRequest 傳回 ERROR_MORE_DATA，應用程式會繼續進行其他呼叫，藉由傳入HTTP_REQUEST來識別每個額外呼叫中的要求 。第 一次呼叫所傳回的 RequestId 值，直到 傳回ERROR_HANDLE_EOF 為止。
需求
| 最低支援的用戶端 | Windows Vista、Windows XP 與 SP2 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | HTTP.h |
| 程式庫 | Httpapi.lib |
| Dll | Httpapi.dll |