HTTPReceiveRequestEntityBody 函式 (http.h)

發行項
02/26/2024

HttpReceiveRequestEntityBody 函式會接收指定 HTTP 要求的其他實體主體數據。

語法

HTTPAPI_LINKAGE ULONG HttpReceiveRequestEntityBody(
  [in]            HANDLE          RequestQueueHandle,
  [in]            HTTP_REQUEST_ID RequestId,
  [in]            ULONG           Flags,
  [out]           PVOID           EntityBuffer,
  [in]            ULONG           EntityBufferLength,
  [out, optional] PULONG          BytesReturned,
  [in, optional]  LPOVERLAPPED    Overlapped
);

參數

[in] RequestQueueHandle

要從中擷取指定實體主體數據之要求佇列的句柄。系統會建立要求佇列，並透過呼叫 HttpCreateRequestQueue 函式傳回其句柄。

Windows Server 2003 SP1 和 Windows XP SP2： 要求佇列的句柄是由 HttpCreateHttpHandle 函式所建立。

[in] RequestId

包含所擷取實體主體之 HTTP 要求的標識碼。呼叫 HttpReceiveHttpRequest 函式時，會在 HTTP_REQUEST 結構的 RequestId 成員中傳回這個值。這個值不能 HTTP_NULL_ID。

[in] Flags

此參數可以是下列旗標值。

Windows Server 2003 SP1 和 Windows XP SP2： 此參數是保留的，而且必須是零。

值	意義
HTTP_RECEIVE_REQUEST_ENTITY_BODY_FLAG_FILL_BUFFER	指定緩衝區會填入一或多個實體主體，除非沒有要複製的其餘實體主體。

[out] EntityBuffer

接收實體主體數據的緩衝區指標。

[in] EntityBufferLength

pBuffer 參數所指向緩衝區的大小，以位元組為單位。

[out, optional] BytesReturned

選擇性。變數的指標，可接收 pBuffer 緩衝區中傳回之實體主體數據的大小，以位元組為單位。

使用 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_HANDLE_EOF	已完全擷取指定的實體主體;在此情況下， pBytesReceived 所指向的值沒有意義，而且不應該檢查 pBuffer 。
ERROR_DLL_INIT_FAILED	呼叫應用程式在呼叫此函式之前未呼叫 HttpInitialize 。
其他	WinError.h 中定義的系統錯誤碼。

備註

若要擷取整個實體主體，應用程式預期會呼叫 HttpReceiveRequestEntityBody，並傳入新的緩衝區，直到函式傳回 ERROR_HANDLE_EOF為止。只要成功複製完整實體主體數據的緩衝區，而且仍有更多實體主體數據等待擷取，函式就會傳回 NO_ERROR。

規格需求

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