Функция HttpReceiveHttpRequest (http.h)
Функция 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
Параметр, который может иметь одно из следующих значений.
| Значение | Значение |
|---|---|
|
Извлекаются только заголовки запросов; тело сущности не копируется. |
|
Текст доступной сущности копируется вместе с заголовками запроса. Элемент pEntityChunks структуры HTTP_REQUEST указывает на тело сущности. |
|
Все тела сущностей копируются вместе с заголовками запроса. Элемент 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 указывает, что следующий запрос еще не готов и будет получен позже с помощью обычных перекрывающихся механизмов завершения ввода-вывода.
Если функция завершается сбоем, возвращаемое значение представляет собой один из следующих кодов ошибок.
| Значение | Значение |
|---|---|
|
Один или несколько предоставленных параметров доступны в непригодном для использования виде. |
|
Один или несколько предоставленных параметров указывают на недопустимый или несровненный буфер памяти. Параметр pRequestBuffer должен указывать на допустимый буфер памяти с выравниванием памяти, равным или большему требованию к выравниванию памяти для структуры HTTP_REQUEST . |
|
Значение RequestBufferLength больше или равно размеру полученного заголовка запроса, но не так велико, как совокупный размер структуры запроса и тела сущности. Размер буфера, необходимый для чтения оставшейся части тела сущности, возвращается в параметре pBytesReceived , если это значение не равно NULL и если вызов является синхронным. Снова вызовите функцию с достаточно большим буфером для извлечения всех данных. |
|
Указанный запрос уже полностью извлечен; в этом случае значение, на которое указывает pBytesReceived , не является значимым, и pRequestBuffer не следует проверять. |
|
Код системной ошибки, определенный в WinError.h. |
Комментарии
Для получения заданного запроса может потребоваться несколько вызовов. Например, если для параметра Flags задано значение 0, HttpReceiveHttpRequest копирует только структуру заголовков запроса в буфер и не пытается скопировать тело сущности. В этом случае для получения тела сущности можно использовать функцию HttpReceiveRequestEntityBody или выполнить второй вызов HttpReceiveHttpRequest.
Кроме того, буфер, предоставляемый приложением, может быть недостаточно большим для получения всего запроса или его части. Чтобы гарантировать получение по крайней мере части запроса, рекомендуется, чтобы приложение предоставлялось по крайней мере буфер размером 4 КБ, который вмещает большинство HTTP-запросов. Кроме того, заголовки проверки подлинности, проанализированные как неизвестные заголовки, могут добавить до 12 КБ, поэтому при использовании проверки подлинности и авторизации рекомендуется размер буфера не менее 16 КБ.
Если HttpReceiveHttpRequest возвращает ERROR_MORE_DATA, приложение продолжает выполнять дополнительные вызовы, определяя запрос в каждом дополнительном вызове, передавая HTTP_REQUEST. Значение RequestId , возвращаемое первым вызовом, пока не будет возвращено ERROR_HANDLE_EOF .
Требования
| Минимальная версия клиента | Windows Vista, Windows XP с пакетом обновления 2 (SP2) [только классические приложения] |
| Минимальная версия сервера | Windows Server 2003 [только классические приложения] |
| Целевая платформа | Windows |
| Header | http.h |
| Библиотека | Httpapi.lib |
| DLL | Httpapi.dll |