Função HttpCreateRequestQueue (http.h)

Artigo
08/24/2023

A função HttpCreateRequestQueue cria uma nova fila de solicitações ou abre uma fila de solicitações existente.

Essa função substitui a função HTTP versão 1.0 HttpCreateHttpHandle .

Sintaxe

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

Parâmetros

[in] Version

Uma estrutura HTTPAPI_VERSION que indica a versão da fila de solicitação. Para a versão 2.0, declare uma instância da estrutura e defina-a como o valor predefinido HTTPAPI_VERSION_2 antes de passá-la para HttpCreateRequestQueue.

A versão deve ser 2.0; HttpCreateRequestQueue não dá suporte a filas de solicitação da versão 1.0.

[in, optional] Name

O nome da fila de solicitação. O comprimento, em bytes, não pode exceder MAX_PATH.

O parâmetro de nome opcional permite que outros processos acessem a fila de solicitações pelo nome.

[in, optional] SecurityAttributes

Um ponteiro para a estrutura SECURITY_ATTRIBUTES que contém as permissões de acesso para a fila de solicitação.

Esse parâmetro deve ser NULL ao abrir uma fila de solicitação existente.

[in, optional] Flags

O parâmetro flags define o escopo da fila de solicitação. Esse parâmetro pode ser um ou mais dos seguintes:

Valor	Significado
HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER	O identificador para a fila de solicitação criada usando esse sinalizador não pode ser usado para executar operações de E/S. Esse sinalizador só pode ser definido quando o identificador da fila de solicitação é criado.
HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING	O sinalizador HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING permite que os aplicativos abram uma fila de solicitação existente pelo nome e recuperem o identificador da fila de solicitação. O parâmetro pName deve conter um nome de fila de solicitação válido; não pode ser NULL.

[out] RequestQueueHandle

Um ponteiro para uma variável que recebe um identificador para a fila de solicitação. Esse parâmetro deve conter um ponteiro válido; não pode ser NULL.

Valor retornado

Se a função for bem-sucedida, ela retornará NO_ERROR

Se a função falhar, ela retornará um dos seguintes códigos de erro.

Valor	Significado
ERROR_REVISION_MISMATCH	O parâmetro Version contém uma versão inválida.
ERROR_INVALID_PARAMETER	O comprimento, em bytes, do nome da fila de solicitação não pode exceder MAX_PATH. O parâmetro pSecurityAttributes deve ser NULL ao abrir uma fila de solicitação existente. O HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER só pode ser definido quando a fila de solicitação é criada. O HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING só pode ser definido quando o aplicativo tem permissão para abrir uma fila de solicitação existente. Nesse caso, o parâmetro pReqQueueHandle deve ser um ponteiro válido e o parâmetro pName deve conter um nome de fila de solicitação válido; não pode ser NULL. O parâmetro pReqQueueHandle retornado por HttpCreateRequestQueue é NULL.
ERROR_ALREADY_EXISTS	O parâmetro pName está em conflito com uma fila de solicitação existente que contém um nome idêntico.
ERROR_ACCESS_DENIED	O processo de chamada não tem permissão para abrir a fila de solicitações.
ERROR_DLL_INIT_FAILED	O aplicativo não chamou HttpInitialize antes de chamar HttpCreateRequestQueue.

Comentários

A API do servidor HTTP dá suporte a aplicativos existentes usando as filas de solicitação da versão 1.0, no entanto, o novo desenvolvimento com a API do servidor HTTP deve usar HttpCreateRequestQueue para criar filas de solicitação; HttpCreateHttpHandle não deve ser usado. A API versão 2.0 só é compatível com as filas de solicitação da versão 2.0 criadas por HttpCreateRequestQueue.

As filas de solicitação HTTP versão 2 exigem configuração manual; o aplicativo deve criar os Grupos de URL e associar um ou mais Grupos de URL à fila de solicitações chamando HttpSetUrlGroupProperty com HttpServerBindingProperty. O aplicativo configura a fila de solicitação chamando HttpSetRequestQueueProperty com a configuração desejada no parâmetro Property . Para obter mais informações sobre como criar e configurar grupos de URLs, consulte HttpCreateUrlGroup e HttpSetUrlGroupProperty.

Os atributos de segurança podem ser fornecidos no parâmetro pSecurityAttributes somente quando a fila de solicitação é criada. Somente o aplicativo que cria a fila de solicitações pode definir Controle de Acesso Listas (ACLs) no identificador de fila de solicitação para permitir que processos (exceto o aplicativo criador) abram, recebam solicitações e enviem respostas no identificador da fila de solicitação. Por padrão, os aplicativos não têm permissão para abrir uma fila de solicitação, a menos que tenham recebido permissão na ACL.

Opcionalmente, o processo do criador pode usar o sinalizador HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER para indicar que ele não deseja receber solicitações http.

HttpCreateRequestQueue permite que os aplicativos abram uma fila de solicitação existente com o sinalizador HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING e recuperem o identificador para a fila de solicitação. Aplicativos que não são controladores podem usar esse identificador para executar operações de E/S HTTP. Somente o aplicativo que cria a fila de solicitações pode definir propriedades nele chamando HttpSetRequestQueueProperty.

O identificador para a fila de solicitação criada por HttpCreateRequestQueue deve ser fechado chamando HttpCloseRequestQueue antes que o aplicativo seja encerrado ou quando a sessão não for mais necessária.

Os aplicativos devem chamar HttpInitialize antes de chamar HttpCreateRequestQueue.

Requisitos


Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	http.h
Biblioteca	Httpapi.lib
DLL	Httpapi.dll