Função HttpCreateRequestQueue (http.h)

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ções.

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ções existente por nome e recuperem o identificador da fila de solicitações. 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.

Retornar valor

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.

A HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER só pode ser definida 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ções 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 da 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 URLs e associar um ou mais Grupos de URLs à fila de solicitações chamando HttpSetUrlGroupProperty ao HttpServerBindingProperty. O aplicativo configura a fila de solicitações 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 os processos (exceto o aplicativo criador) abram, recebam solicitações e enviem respostas no identificador da fila de solicitações. 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ções existente com o sinalizador HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING e recuperem o identificador para a fila de solicitações. Aplicativos nã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 nela 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

Requisito Valor
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

Confira também

Funções da API do Servidor HTTP versão 2.0

HttpCloseRequestQueue

HttpCreateHttpHandle

HttpQueryRequestQueueProperty

HttpSetRequestQueueProperty

HttpShutdownRequestQueue