HTTPSendResponseEntityBody 函式 (http.h)

發行項
03/05/2024

HttpSendResponseEntityBody 函式會傳送與 HTTP 回應相關聯的實體主體數據。

語法

HTTPAPI_LINKAGE ULONG HttpSendResponseEntityBody(
  [in]           HANDLE           RequestQueueHandle,
  [in]           HTTP_REQUEST_ID  RequestId,
  [in]           ULONG            Flags,
  [in]           USHORT           EntityChunkCount,
  [in]           PHTTP_DATA_CHUNK EntityChunks,
  [out]          PULONG           BytesSent,
  [in]           PVOID            Reserved1,
  [in]           ULONG            Reserved2,
  [in]           LPOVERLAPPED     Overlapped,
  [in, optional] PHTTP_LOG_DATA   LogData
);

參數

[in] RequestQueueHandle

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

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

[in] RequestId

這個回應所對應之 HTTP 要求的標識碼。呼叫 HttpReceiveHttpRequest 函式時，會在 HTTP_REQUEST 結構的 RequestId 成員中傳回這個值。無法 HTTP_NULL_ID。

[in] Flags

參數，可包含下列其中一個互斥旗標值。

Flags	意義
HTTP_SEND_RESPONSE_FLAG_DISCONNECT	傳送此回應之後，應該中斷網路連線，覆寫與使用中 HTTP 版本相關聯的任何持續性連線功能。如果未使用內容長度或區塊編碼，應用程式應該使用此旗標來指出實體的結尾。
HTTP_SEND_RESPONSE_FLAG_MORE_DATA	應用程式會透過對 HttpSendResponseEntityBody 的一或多個後續呼叫來傳送此回應的其他實體主體數據。最後一個呼叫接著會將此旗標設定為零。
HTTP_SEND_RESPONSE_FLAG_BUFFER_DATA	此旗標會根據每個回應來緩衝核心中的數據。它應該由執行同步 I/O 的應用程式使用，或由執行異步 I/O 的應用程式使用，且一次傳送未處理一個以上。使用異步 I/O 的應用程式一次可能有多個未處理傳送，不應該使用此旗標。設定此旗標時，也應該一致地用於對 HttpSendHttpResponse 函式的呼叫。 Windows Server 2003：不支援此旗標。這個旗標是 Windows Server 2003 SP1 的新功能。
HTTP_SEND_RESPONSE_FLAG_ENABLE_NAGLING	僅啟用此傳送的 TCP 導覽演算法。 Windows Vista 和更新版本：不支援此旗標。
HTTP_SEND_RESPONSE_FLAG_PROCESS_RANGES	指定針對範圍要求，會傳遞完整的響應內容，而呼叫端希望 HTTP API 適當地處理範圍。注意此旗標僅支援對 HTTP GET 要求的回應，並提供有限的功能子集。需要完整範圍處理的應用程式應該在使用者模式中執行，而不依賴 HTTP.sys。不建議使用。 Windows Server 2008 R2 和 Windows 7 或更新版本。注意支援此旗標。
HTTP_SEND_RESPONSE_FLAG_OPAQUE	指定要求/回應不符合 HTTP 規範，而且所有後續的位元組都應該視為實體主體。應用程式在接受 Web 套接字升級要求時指定此旗標，並通知 HTTP.sys 將連線數據視為不透明數據。只有在 pHttpResponse 的 StatusCode 成員為 101，切換通訊協定時，才允許此旗標。如果使用這個旗標，HttpSendResponseEntityBody 會針對所有其他 HTTP 回應類型傳回ERROR_INVALID_PARAMETER。 Windows 8 及更新版本：支援此旗標。

謹慎在對 HttpSendHttpResponse 函式的單一呼叫中結合這兩個旗標會產生未定義的結果。

[in] EntityChunkCount

pEntityChunks 所指向數位中的一些結構。此計數不能超過9999。

[in] EntityChunks

要當做實體主體數據傳送之HTTP_DATA_CHUNK 結構的陣列指標。

[out] BytesSent

選擇性。如果函式以同步方式運作，則為接收數位之變數的指標，以位元組為單位傳送。

使用 pOverlapped 進行異步呼叫時，請將 pBytesSent 設定為 NULL。否則，當 pOverlapped 設定為 NULL 時， pBytesSent 必須包含有效的記憶體位址，而且不能設定為 NULL。

[in] Reserved1

此參數是保留的，而且必須是 NULL。

[in] Reserved2

此參數是保留的，而且必須是零。

[in] Overlapped

針對異步呼叫，請將 pOverlapped 設定為指向重疊結構;若為同步呼叫，請將它設定為 NULL。

同步呼叫會封鎖，直到傳送 pEntityChunks 參數中指定的所有響應數據為止，而異步呼叫會立即傳回 ERROR_IO_PENDING ，然後呼叫應用程式會使用 GetOverlappedResult 或 I/O 完成埠來判斷作業何時完成。如需使用重疊結構進行同步處理的詳細資訊，請參閱同步處理和重疊的輸入和輸出。

[in, optional] LogData

用來記錄回應之HTTP_LOG_DATA 結構的指標。將指標傳遞至 HTTP_LOG_FIELDS_DATA 結構，並將它轉換成 PHTTP_LOG_DATA。

請注意，即使已在URL群組或伺服器會話上啟用記錄，除非應用程式提供記錄欄位數據結構，否則不會記錄回應。

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

Windows Vista 和 Windows Server 2008： 此參數是 Windows Vista 和 Windows Server 2008 的新功能

傳回值

如果函式成功，傳回值會 NO_ERROR。

如果以異步方式使用函式， ERROR_IO_PENDING 傳回值表示下一個要求尚未就緒，且稍後會透過一般重疊的 I/O 完成機制擷取。

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

值	意義
ERROR_INVALID_PARAMETER	提供的一或多個參數格式為無法使用。
ERROR_BAD_COMMAND	HttpSendHttpResponse 或 HttpSendResponseEntityBody 具有相同 RequestId 的呼叫擱置中。
其他	WinError.h 中定義的系統錯誤碼。

備註

如果回應標頭中未包含 Content-length 標頭或 Transfer-encoding 標頭，應用程式就必須使用 HTTP_SEND_RESPONSE_DISCONNECT 旗標明確關閉連線來指出回應的結尾。

注意HttpSendResponseEntityBody (或 HttpSendHttpResponse) 和 HttpSendResponseEntityBody 不得從相同 RequestId 上的不同線程同時呼叫。

規格需求

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