HTTPSendHttpResponse 函式 (HTTP.h)

  • 發行項

HttpSendHttpResponse函式會將 HTTP 回應傳送至指定的 HTTP 要求。

語法

HTTPAPI_LINKAGE ULONG HttpSendHttpResponse(
  [in]           HANDLE             RequestQueueHandle,
  [in]           HTTP_REQUEST_ID    RequestId,
  [in]           ULONG              Flags,
  [in]           PHTTP_RESPONSE     HttpResponse,
  [in, optional] PHTTP_CACHE_POLICY CachePolicy,
  [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 版本相關聯的任何持續性連線功能。
謹慎在對 HttpSendHttpResponse函式的單一呼叫中結合HTTP_SEND_RESPONSE_FLAG_DISCONNECT和HTTP_SEND_RESPONSE_FLAG_MORE_DATA會產生未定義的結果。
 
HTTP_SEND_RESPONSE_FLAG_MORE_DATA
 此回應的其他實體主體資料會透過對 HttpSendResponseEntityBody的一或多個後續呼叫傳送給應用程式。 最後一次呼叫傳送實體主體資料，然後將這個旗標設定為零。
謹慎在對 HttpSendHttpResponse函式的單一呼叫中結合HTTP_SEND_RESPONSE_FLAG_DISCONNECT和HTTP_SEND_RESPONSE_FLAG_MORE_DATA會產生未定義的結果。
 
HTTP_SEND_RESPONSE_FLAG_BUFFER_DATA
 此旗標會根據每個回應來緩衝核心中的資料。

應用程式應該使用同步 I/O，或應用程式執行非同步 I/O，一次沒有一個未完成的傳送。

使用非同步 I/O 且一次可能有多個傳送未完成的應用程式不應該使用此旗標。

設定此旗標時，也應該在 呼叫 HttpSendResponseEntityBody 函式時一致地使用它。

Windows Server 2003： 不支援此旗標。 此旗標是 Windows Server 2003 SP1 的新功能。
HTTP_SEND_RESPONSE_FLAG_ENABLE_NAGLING
 僅啟用此傳送的 TCP 流覽演算法。

Windows Server 2003 SP1 和 Windows XP SP2： 不支援此旗標。
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 Socket 升級要求時指定此旗標，並通知 HTTP.sys 將連線資料視為不透明資料。

只有在pHttpResponse的StatusCode成員為101、切換通訊協定時，才允許此旗標。 如果使用此旗標，HttpSendHttpResponse會針對所有其他 HTTP 回應類型傳回ERROR_INVALID_PARAMETER。

Windows 8 和更新版本： 支援此旗標。

[in] HttpResponse

定義 HTTP 回應之 HTTP_RESPONSE 結構的指標。

[in, optional] CachePolicy

用來快取回應之 HTTP_CACHE_POLICY 結構的指標。

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

[out] BytesSent

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

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

[in] Reserved1

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

[in] Reserved2

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

[in] Overlapped

針對非同步呼叫，請將 pOverlapped 設定為指向 重迭 結構;針對同步呼叫，請將 設定為 Null。

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

[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
 一或多個提供的參數格式為無法使用。
其他
 WinError.h 中定義的 系統錯誤碼 。

備註

HttpSendHttpResponse函式可用來建立和傳送回應標頭，而HttpSendResponseEntityBody函式可用來視需要傳送實體主體資料。

如果回應中未包含內容長度標頭或傳輸編碼標頭，應用程式必須使用 HTTP_SEND_RESPONSE_DISCONNECT 旗標明確關閉連線來指出回應的結尾。

如果應用程式在回應中指定 「Server：」 標頭，請使用HTTP_KNOWN_HEADER結構中的HttpHeaderServer識別碼，該指定值會放在標頭的第一個部分，後面接著空格，然後是 「Microsoft-HTTPAPI/1.0」。 如果未指定伺服器標頭， HttpSendHttpResponse 會提供 「Microsoft-HTTPAPI/1.0」 做為伺服器標頭。

注意HttpSendHttpResponse和HttpSendResponseEntityBody函式不得從相同RequestId上的不同執行緒同時呼叫。
 

需求

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

另請參閱

HTTP 伺服器 API 1.0 版函式

HTTP_RESPONSE

HttpReceiveHttpRequest

HttpReceiveRequestEntityBody

HttpSendResponseEntityBody