共用方式為


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。 然後,如果需要多個呼叫來擷取整個要求,則可以呼叫HttpReceiveHttpRequestHttpReceiveRequestEntityBody,並將RequestID設定為pRequestBuffer所指向HTTP_REQUEST之requestId成員中所傳回的值。

[in] Flags

可以是下列其中一個值的參數。

意義
0 (零)
只會擷取要求標頭;實體主體不會複製。
HTTP_RECEIVE_REQUEST_FLAG_COPY_BODY
可用的實體主體會連同要求標頭一起複製。 HTTP_REQUEST結構的pEntityChunks成員會指向實體主體。
HTTP_RECEIVE_REQUEST_FLAG_FLUSH_BODY
所有實體主體都會連同要求標頭一起複製。 HTTP_REQUEST結構的pEntityChunks成員會指向實體主體。

[out] RequestBuffer

函式針對 HTTP 要求複製 HTTP_REQUEST 結構和實體主體的緩衝區指標。 HTTP_REQUEST。RequestId包含此 HTTP 要求的識別碼,應用程式可以在後續呼叫HttpReceiveRequestEntityBodyHttpSendHttpResponse 或 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 完成機制擷取。

如果函式失敗,傳回值就是下列其中一個錯誤碼。

意義
ERROR_INVALID_PARAMETER
一或多個提供的參數格式為無法使用。
ERROR_NOACCESS
提供的一或多個參數指向無效或未對齊的記憶體緩衝區。 pRequestBuffer參數必須指向記憶體對齊等於或大於HTTP_REQUEST結構的記憶體對齊需求的有效記憶體緩衝區。
ERROR_MORE_DATA
RequestBufferLength的值大於或等於收到的要求標頭大小,但與要求結構和實體主體的合併大小不相同。 如果這是非Null且呼叫為同步,則會在pBytesReceived參數中傳回讀取實體主體剩餘部分所需的緩衝區大小。 使用夠大的緩衝區再次呼叫 函式,以擷取所有資料。
ERROR_HANDLE_EOF
已完全擷取指定的要求;在此情況下, 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 為止。

注意 應用程式必須檢查所有相關的要求標頭,包括使用的內容交涉標頭,並根據標頭內容適當地失敗要求。 HttpReceiveHttpRequest 只會確保標頭行已正確終止,且不包含不合法的字元。
 

需求

   
最低支援的用戶端 Windows Vista、Windows XP 與 SP2 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 HTTP.h
程式庫 Httpapi.lib
Dll Httpapi.dll

另請參閱

HTTP 伺服器 API 1.0 版函式

HTTP_REQUEST

HttpReceiveRequestEntityBody

HttpSendHttpResponse

HttpSendResponseEntityBody