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

Статья
08/24/2023

Функция HttpCreateRequestQueue создает новую очередь запросов или открывает существующую.

Эта функция заменяет http версии 1.0 HttpCreateHttpHandle .

Синтаксис

HTTPAPI_LINKAGE ULONG HttpCreateRequestQueue(
  [in]           HTTPAPI_VERSION      Version,
  [in, optional] PCWSTR               Name,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in, optional] ULONG                Flags,
  [out]          PHANDLE              RequestQueueHandle
);

Параметры

[in] Version

Структура HTTPAPI_VERSION, указывающая версию очереди запросов. Для версии 2.0 объявите экземпляр структуры и присвойте ему предопределенное значение HTTPAPI_VERSION_2 перед передачей в HttpCreateRequestQueue.

Версия должна быть 2.0; HttpCreateRequestQueue не поддерживает очереди запросов версии 1.0.

[in, optional] Name

Имя очереди запросов. Длина в байтах не может превышать MAX_PATH.

Необязательный параметр name позволяет другим процессам получать доступ к очереди запросов по имени.

[in, optional] SecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , содержащую разрешения на доступ для очереди запросов.

Этот параметр должен иметь значение NULL при открытии существующей очереди запросов.

[in, optional] Flags

Параметр flags определяет область очереди запросов. Этот параметр может быть одним или несколькими из следующих:

Значение	Значение
HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER	Дескриптор очереди запросов, созданный с помощью этого флага, не может использоваться для выполнения операций ввода-вывода. Этот флаг можно установить только при создании дескриптора очереди запросов.
HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING	Флаг HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING позволяет приложениям открывать существующую очередь запросов по имени и получать дескриптор очереди запросов. Параметр pName должен содержать допустимое имя очереди запросов; значение не может иметь значение NULL.

Значение

HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER

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

HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING

Флаг HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING позволяет приложениям открывать существующую очередь запросов по имени и получать дескриптор очереди запросов. Параметр pName должен содержать допустимое имя очереди запросов; значение не может иметь значение NULL.

[out] RequestQueueHandle

Указатель на переменную, получающую дескриптор очереди запросов. Этот параметр должен содержать допустимый указатель; значение не может иметь значение NULL.

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

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

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

Значение	Значение
ERROR_REVISION_MISMATCH	Параметр Version содержит недопустимую версию.
ERROR_INVALID_PARAMETER	Длина имени очереди запросов в байтах не может превышать MAX_PATH. Параметр pSecurityAttributes должен иметь значение NULL при открытии существующей очереди запросов. HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER можно задать только при создании очереди запросов. HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING можно задать, только если у приложения есть разрешение на открытие существующей очереди запросов. В этом случае параметр pReqQueueHandle должен быть допустимым указателем, а параметр pName должен содержать допустимое имя очереди запросов; значение не может иметь значение NULL. Параметр pReqQueueHandle, возвращаемый httpCreateRequestQueue, имеет значение NULL.
ERROR_ALREADY_EXISTS	Параметр pName конфликтует с существующей очередью запросов, содержащей идентичное имя.
ERROR_ACCESS_DENIED	Вызывающий процесс не имеет разрешения на открытие очереди запросов.
ERROR_DLL_INIT_FAILED	Приложение не вызывало HttpInitialize до вызова HttpCreateRequestQueue.

API HTTP-сервера поддерживает существующие приложения, использующие очереди запросов версии 1.0, однако новые разработки с помощью API HTTP-сервера должны использовать HttpCreateRequestQueue для создания очередей запросов; HttpCreateHttpHandle не следует использовать. API версии 2.0 совместим только с очередями запросов версии 2.0, созданными httpCreateRequestQueue.

Очереди запросов HTTP версии 2 требуют настройки вручную; приложение должно создать группы URL-адресов и связать одну или несколько групп URL-адресов с очередью запросов, вызвав HttpSetUrlGroupProperty с httpServerBindingProperty. Приложение настраивает очередь запросов, вызывая HttpSetRequestQueueProperty с требуемой конфигурацией в параметре Property . Дополнительные сведения о создании и настройке групп URL-адресов см. в разделах HttpCreateUrlGroup и HttpSetUrlGroupProperty.

Атрибуты безопасности могут быть предоставлены в параметре pSecurityAttributes только при создании очереди запросов. Только приложение, создающее очередь запросов, может задать контроль доступа Списки (ACL) в дескрипторе очереди запросов, чтобы разрешить процессам (кроме приложения-создателя) разрешение на открытие, получение запросов и отправку ответов на дескриптор очереди запросов. По умолчанию приложениям не разрешено открывать очередь запросов, если только им не предоставлено разрешение в ACL.

При необходимости процесс создателя может использовать флаг HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER , чтобы указать, что он не хочет получать HTTP-запросы.

HttpCreateRequestQueue позволяет приложениям открывать существующую очередь запросов с флагом HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING и извлекать дескриптор в очередь запросов. Приложения без контроллера могут использовать этот дескриптор для выполнения операций ввода-вывода HTTP. Только приложение, создающее очередь запросов, может задать для нее свойства, вызвав HttpSetRequestQueueProperty.

Дескриптор очереди запросов, созданной httpCreateRequestQueue, должен быть закрыт путем вызова HttpCloseRequestQueue до завершения работы приложения или когда сеанс больше не требуется.

Приложения должны вызывать HttpInitialize перед вызовом HttpCreateRequestQueue.

Требования

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