Функция HttpSendResponseEntityBody (http.h)

Статья
08/24/2023

Функция 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 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (SP2): Дескриптор очереди запросов создается функцией HttpCreateHttpHandle .

[in] RequestId

Идентификатор HTTP-запроса, которому соответствует этот ответ. Это значение возвращается в элементе RequestIdструктуры HTTP_REQUEST путем вызова функции HttpReceiveHttpRequest . Его нельзя HTTP_NULL_ID.

[in] Flags

Параметр, который может включать одно из следующих взаимоисключающих значений флага.

Флаги	Значение
HTTP_SEND_RESPONSE_FLAG_DISCONNECT	После отправки этого ответа сетевое подключение должно быть отключено, переопределяя все функции постоянного подключения, связанные с используемой версией HTTP. Приложения должны использовать этот флаг, чтобы указать конец сущности в случаях, когда не используется ни длина содержимого, ни фрагментированная кодировка.
HTTP_SEND_RESPONSE_FLAG_MORE_DATA	Дополнительные данные тела сущности для этого ответа отправляются приложением через один или несколько последующих вызовов HttpSendResponseEntityBody. После этого последний вызов устанавливает для этого флага значение 0.
HTTP_SEND_RESPONSE_FLAG_BUFFER_DATA	Этот флаг обеспечивает буферизацию данных в ядре на основе каждого ответа. Его должно использовать приложение, выполняющее синхронные операции ввода-вывода, или приложение, выполняющее асинхронные операции ввода-вывода с не более чем одним незавершенным отправкой за раз. Приложения, использующие асинхронные ввод-вывод, которые могут иметь несколько невыполненных операций отправки за раз, не должны использовать этот флаг. Если этот флаг установлен, он также должен использоваться согласованно в вызовах функции HttpSendHttpResponse . Windows Server 2003: Этот флаг не поддерживается. Этот флаг является новым для Windows Server 2003 с пакетом обновления 1 (SP1).
HTTP_SEND_RESPONSE_FLAG_ENABLE_NAGLING	Включает алгоритм tcp-nagling только для этой отправки. Windows Vista и более поздних версий: Этот флаг не поддерживается.
HTTP_SEND_RESPONSE_FLAG_PROCESS_RANGES	Указывает, что для запроса диапазона передается полное содержимое ответа, и вызывающий объект хочет, чтобы API HTTP правильно обрабатывал диапазоны. Примечание Этот флаг поддерживается только для ответов на HTTP-запросы GET и предоставляет ограниченное подмножество функциональных возможностей. Приложения, требующие полной обработки, должны выполнять ее в пользовательском режиме и не полагаться на HTTP.sys. Его использование не рекомендуется. Windows Server 2008 R2 и Windows 7 или более поздней версии. Примечание Этот флаг поддерживается.
HTTP_SEND_RESPONSE_FLAG_OPAQUE	Указывает, что запрос или ответ не соответствует HTTP и все последующие байты должны рассматриваться как тело сущности. Приложения задают этот флаг при принятии запроса на обновление веб-сокета и информировании HTTP.sys о том, что данные подключения обрабатываются как непрозрачные данные. Этот флаг разрешен только в том случае, если элемент StatusCodeв pHttpResponse равен 101, коммутационные протоколы. HttpSendResponseEntityBody возвращает ERROR_INVALID_PARAMETER для всех других типов HTTP-ответов, если используется этот флаг. 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 так, чтобы он указывал на структуру OVERLAPPED ; для синхронных вызовов задайте значение NULL.

Синхронный вызов блокируется, пока не будут отправлены все данные ответа, указанные в параметре pEntityChunks , в то время как асинхронный вызов немедленно возвращает ERROR_IO_PENDING , а вызывающее приложение затем использует порты getOverlappedResult или завершения ввода-вывода, чтобы определить, когда операция будет завершена. Дополнительные сведения об использовании структур OVERLAPPED для синхронизации см. в разделе Синхронизация и перекрытие входных и выходных данных.

[in, optional] LogData

Указатель на структуру HTTP_LOG_DATA , используемую для регистрации ответа. Передайте указатель на структуру HTTP_LOG_FIELDS_DATA и приведите его к PHTTP_LOG_DATA.

Имейте в виду, что даже если ведение журнала включено в группе URL-адресов или сеансе сервера, ответ не будет регистрироваться, если приложение не предоставит структуру данных полей журнала.

Windows Server 2003 и Windows XP с пакетом обновления 2 (SP2): Этот параметр зарезервирован и должен иметь значение NULL.

Windows Vista и Windows Server 2008: Этот параметр является новым для Windows Vista и Windows Server 2008

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.

Если функция используется асинхронно, возвращаемое значение ERROR_IO_PENDING указывает, что следующий запрос еще не готов и извлекается позже с помощью обычных перекрывающихся механизмов завершения ввода-вывода.

Если функция завершается сбоем, возвращается один из следующих кодов ошибок.

Значение	Значение
ERROR_INVALID_PARAMETER	Один или несколько предоставленных параметров находится в непригодной для использования форме.
ERROR_BAD_COMMAND	Ожидается вызов HttpSendHttpResponse или HttpSendResponseEntityBody с тем же Идентификатором запроса.
Другое	Код системной ошибки, определенный в WinError.h.

Если ни заголовок Content-length, ни заголовок Transfer-encoding не включены в заголовки ответа, приложение должно указать конец ответа, явно закрыв подключение с помощью флага HTTP_SEND_RESPONSE_DISCONNECT .

ПримечаниеHttpSendResponseEntityBody (или HttpSendHttpResponse) и HttpSendResponseEntityBody не должны вызываться одновременно из разных потоков в одном и том же RequestId.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista, Windows XP с пакетом обновления 2 (SP2) [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	http.h
Библиотека	Httpapi.lib
DLL	Httpapi.dll