Fonction HttpCreateRequestQueue (http.h)

Article
08/24/2023

La fonction HttpCreateRequestQueue crée une file d’attente de requêtes ou ouvre une file d’attente de requêtes existante.

Cette fonction remplace la fonction HTTP version 1.0 HttpCreateHttpHandle .

Syntaxe

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

Paramètres

[in] Version

Structure HTTPAPI_VERSION indiquant la version de la file d’attente de requêtes. Pour la version 2.0, déclarez une instance de la structure et définissez-la sur la valeur prédéfinie HTTPAPI_VERSION_2 avant de la passer à HttpCreateRequestQueue.

La version doit être 2.0 ; HttpCreateRequestQueue ne prend pas en charge les files d’attente de requêtes de la version 1.0.

[in, optional] Name

Nom de la file d’attente de requêtes. La longueur, en octets, ne peut pas dépasser MAX_PATH.

Le paramètre de nom facultatif permet à d’autres processus d’accéder à la file d’attente de requêtes par nom.

[in, optional] SecurityAttributes

Pointeur vers la structure SECURITY_ATTRIBUTES qui contient les autorisations d’accès pour la file d’attente des requêtes.

Ce paramètre doit avoir la valeur NULL lors de l’ouverture d’une file d’attente de requêtes existante.

[in, optional] Flags

Le paramètre flags définit l’étendue de la file d’attente de requêtes. Ce paramètre peut être l’un ou plusieurs des éléments suivants :

Valeur	Signification
HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER	Le handle de la file d’attente de requête créé à l’aide de cet indicateur ne peut pas être utilisé pour effectuer des opérations d’E/S. Cet indicateur ne peut être défini que lorsque le handle de file d’attente de requête est créé.
HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING	L’indicateur HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING permet aux applications d’ouvrir une file d’attente de requêtes existante par nom et de récupérer le handle de file d’attente des requêtes. Le paramètre pName doit contenir un nom de file d’attente de requêtes valide ; il ne peut pas être NULL.

[out] RequestQueueHandle

Pointeur vers une variable qui reçoit un handle vers la file d’attente de requête. Ce paramètre doit contenir un pointeur valide ; il ne peut pas être NULL.

Valeur retournée

Si la fonction réussit, elle retourne NO_ERROR

Si la fonction échoue, elle retourne l’un des codes d’erreur suivants.

Valeur	Signification
ERROR_REVISION_MISMATCH	Le paramètre Version contient une version non valide.
ERROR_INVALID_PARAMETER	La longueur, en octets, du nom de la file d’attente de requête ne peut pas dépasser MAX_PATH. Le paramètre pSecurityAttributes doit avoir la valeur NULL lors de l’ouverture d’une file d’attente de requêtes existante. Le HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER ne peut être défini que lorsque la file d’attente de requêtes est créée. Le HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING ne peut être défini que lorsque l’application a l’autorisation d’ouvrir une file d’attente de requêtes existante. Dans ce cas, le paramètre pReqQueueHandle doit être un pointeur valide et le paramètre pName doit contenir un nom de file d’attente de requête valide ; il ne peut pas être NULL. Le paramètre pReqQueueHandle retourné par HttpCreateRequestQueue est NULL.
ERROR_ALREADY_EXISTS	Le paramètre pName est en conflit avec une file d’attente de requêtes existante qui contient un nom identique.
ERROR_ACCESS_DENIED	Le processus d’appel n’a pas l’autorisation d’ouvrir la file d’attente des demandes.
ERROR_DLL_INIT_FAILED	L’application n’a pas appelé HttpInitialize avant d’appeler HttpCreateRequestQueue.

Remarques

L’API serveur HTTP prend en charge les applications existantes utilisant les files d’attente de requêtes version 1.0. Toutefois, le nouveau développement avec l’API de serveur HTTP doit utiliser HttpCreateRequestQueue pour créer des files d’attente de requêtes ; HttpCreateHttpHandle ne doit pas être utilisé. L’API version 2.0 est uniquement compatible avec les files d’attente de requêtes de la version 2.0 créées par HttpCreateRequestQueue.

Les files d’attente de requêtes HTTP version 2 nécessitent une configuration manuelle ; l’application doit créer les groupes d’URL et associer un ou plusieurs groupes d’URL à la file d’attente de requêtes en appelant HttpSetUrlGroupProperty avec httpServerBindingProperty. L’application configure la file d’attente de requêtes en appelant HttpSetRequestQueueProperty avec la configuration souhaitée dans le paramètre Property . Pour plus d’informations sur la création et la configuration de groupes d’URL, consultez HttpCreateUrlGroup et HttpSetUrlGroupProperty.

Les attributs de sécurité peuvent être fournis dans le paramètre pSecurityAttributes uniquement lorsque la file d’attente de requête est créée. Seule l’application qui crée la file d’attente de requêtes peut définir Access Control Listes (ACL) sur le handle de file d’attente des demandes pour autoriser les processus (autres que l’application créatrice) à ouvrir, recevoir des requêtes et envoyer des réponses sur le handle de file d’attente des demandes. Par défaut, les applications ne sont pas autorisées à ouvrir une file d’attente de requêtes, sauf si elles ont obtenu l’autorisation dans la liste de contrôle d’accès.

Le processus créateur peut éventuellement utiliser l’indicateur HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER pour indiquer qu’il ne souhaite pas recevoir de requêtes http.

HttpCreateRequestQueue permet aux applications d’ouvrir une file d’attente de requêtes existante avec l’indicateur HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING et de récupérer le handle dans la file d’attente des requêtes. Les applications non-contrôleurs peuvent utiliser ce handle pour effectuer des opérations d’E/S HTTP. Seule l’application qui crée la file d’attente de requêtes peut définir des propriétés sur celle-ci en appelant httpSetRequestQueueProperty.

Le handle de la file d’attente de requêtes créée par HttpCreateRequestQueue doit être fermé en appelant HttpCloseRequestQueue avant l’arrêt de l’application ou lorsque la session n’est plus nécessaire.

Les applications doivent appeler HttpInitialize avant d’appeler HttpCreateRequestQueue.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	http.h
Bibliothèque	Httpapi.lib
DLL	Httpapi.dll