Fonction HttpCreateRequestQueue (http.h)
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 :
[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 |
|---|---|
|
Le paramètre Version contient une version non valide. |
|
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. |
|
Le paramètre pName est en conflit avec une file d’attente de requêtes existante qui contient un nom identique. |
|
Le processus d’appel n’a pas l’autorisation d’ouvrir la file d’attente des demandes. |
|
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 |