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

Статья
08/24/2023

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

[in] RequestId

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

[in] Flags

Этот параметр может быть следующим значением флага.

Windows Server 2003 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (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 значение , указывающее на структуру OVERLAPPED ; для синхронных вызовов присвойте ему значение NULL.

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

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

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

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

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

Значение	Значение
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 с пакетом обновления 2 (SP2) [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	http.h
Библиотека	Httpapi.lib
DLL	Httpapi.dll