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

Статья
08/24/2023

Функция HttpReceiveHttpRequest извлекает следующий доступный HTTP-запрос из указанной очереди запросов синхронно или асинхронно.

Синтаксис

HTTPAPI_LINKAGE ULONG HttpReceiveHttpRequest(
  [in]            HANDLE          RequestQueueHandle,
  [in]            HTTP_REQUEST_ID RequestId,
  [in]            ULONG           Flags,
  [out]           PHTTP_REQUEST   RequestBuffer,
  [in]            ULONG           RequestBufferLength,
  [out, optional] PULONG          BytesReturned,
  [in, optional]  LPOVERLAPPED    Overlapped
);

Параметры

[in] RequestQueueHandle

Дескриптор очереди запросов, из которой извлекается следующий доступный запрос. Создается очередь запроса, и ее дескриптор возвращается вызовом функции HttpCreateRequestQueue .

Windows Server 2003 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (SP2): Дескриптор очереди запросов создается функцией HttpCreateHttpHandle .

[in] RequestId

При первом вызове для получения запроса этот параметр должен быть HTTP_NULL_ID. Если для получения всего запроса требуется несколько вызовов, можно вызвать HttpReceiveHttpRequest или HttpReceiveRequestEntityBody со значением RequestID , возвращаемым в элементе RequestIdструктуры HTTP_REQUEST , на которую указывает pRequestBuffer.

[in] Flags

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

Значение	Значение
0 (ноль)	Извлекаются только заголовки запросов; тело сущности не копируется.
HTTP_RECEIVE_REQUEST_FLAG_COPY_BODY	Текст доступной сущности копируется вместе с заголовками запроса. Элемент pEntityChunks структуры HTTP_REQUEST указывает на тело сущности.
HTTP_RECEIVE_REQUEST_FLAG_FLUSH_BODY	Все тела сущностей копируются вместе с заголовками запроса. Элемент pEntityChunks структуры HTTP_REQUEST указывает на тело сущности.

[out] RequestBuffer

Указатель на буфер, в который функция копирует структуру HTTP_REQUEST и тело сущности для HTTP-запроса. HTTP_REQUEST. RequestId содержит идентификатор для этого HTTP-запроса, который приложение может использовать в последующих вызовах HttpReceiveRequestEntityBody, HttpSendHttpResponse или HttpSendResponseEntityBody.

[in] RequestBufferLength

Размер буфера pRequestBuffer в байтах.

[out, optional] BytesReturned

Необязательный элемент. Указатель на переменную, которая получает размер (в байтах) тела сущности или оставшейся части тела сущности.

При выполнении асинхронного вызова с помощью 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_NOACCESS	Один или несколько предоставленных параметров указывают на недопустимый или несровненный буфер памяти. Параметр pRequestBuffer должен указывать на допустимый буфер памяти с выравниванием памяти, равным или большему требованию к выравниванию памяти для структуры HTTP_REQUEST .
ERROR_MORE_DATA	Значение RequestBufferLength больше или равно размеру полученного заголовка запроса, но не так велико, как совокупный размер структуры запроса и тела сущности. Размер буфера, необходимый для чтения оставшейся части тела сущности, возвращается в параметре pBytesReceived , если это значение не равно NULL и если вызов является синхронным. Снова вызовите функцию с достаточно большим буфером для извлечения всех данных.
ERROR_HANDLE_EOF	Указанный запрос уже полностью извлечен; в этом случае значение, на которое указывает pBytesReceived , не является значимым, и pRequestBuffer не следует проверять.
Другое	Код системной ошибки, определенный в WinError.h.

Для получения заданного запроса может потребоваться несколько вызовов. Например, если для параметра Flags задано значение 0, HttpReceiveHttpRequest копирует только структуру заголовков запроса в буфер и не пытается скопировать тело сущности. В этом случае для получения тела сущности можно использовать функцию HttpReceiveRequestEntityBody или выполнить второй вызов HttpReceiveHttpRequest.

Кроме того, буфер, предоставляемый приложением, может быть недостаточно большим для получения всего запроса или его части. Чтобы гарантировать получение по крайней мере части запроса, рекомендуется, чтобы приложение предоставлялось по крайней мере буфер размером 4 КБ, который вмещает большинство HTTP-запросов. Кроме того, заголовки проверки подлинности, проанализированные как неизвестные заголовки, могут добавить до 12 КБ, поэтому при использовании проверки подлинности и авторизации рекомендуется размер буфера не менее 16 КБ.

Если HttpReceiveHttpRequest возвращает ERROR_MORE_DATA, приложение продолжает выполнять дополнительные вызовы, определяя запрос в каждом дополнительном вызове, передавая HTTP_REQUEST. Значение RequestId , возвращаемое первым вызовом, пока не будет возвращено ERROR_HANDLE_EOF .

Примечание Приложение должно проверить все соответствующие заголовки запросов, включая заголовки согласования содержимого, если они используются, и завершить запрос соответствующим образом на основе содержимого заголовка. HttpReceiveHttpRequest гарантирует, что строка заголовка будет правильно завершена и не содержит недопустимых символов.

Требования


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