HTTPReceiveHttpRequest 函式 (HTTP.h)

發行項
08/24/2023

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

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

值	意義
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 要求的識別碼，應用程式可以在後續呼叫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 完成機制擷取。

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

值	意義
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