HttpCreateRequestQueue, fonction (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ête. 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 transmettre à HttpCreateRequestQueue.
La version doit être 2.0 ; HttpCreateRequestQueue ne prend pas en charge les files d’attente de requêtes version 1.0.
[in, optional] Name
Nom de la file d’attente de requête. 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ête par nom.
[in, optional] SecurityAttributes
Pointeur vers la structure SECURITY_ATTRIBUTES qui contient les autorisations d’accès pour la file d’attente de demandes.
Ce paramètre doit être NULL lors de l’ouverture d’une file d’attente de requêtes existante.
[in, optional] Flags
Le paramètre d’indicateurs définit l’étendue de la file d’attente de requêtes. Ce paramètre peut être 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êtes. Ce paramètre doit contenir un pointeur valide ; il ne peut pas être NULL.
Valeur de retour
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 être NULL lors de l’ouverture d’une file d’attente de requête existante. Le HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER ne peut être défini que lorsque la file d’attente de requête est créée. Le HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING ne peut être défini que lorsque l’application est autorisée à ouvrir une file d’attente de demandes 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 |
|
Le paramètre pName est en conflit avec une file d’attente de requêtes existante qui contient un nom identique. |
|
Le processus appelant n’a pas l’autorisation d’ouvrir la file d’attente de demandes. |
|
L’application n’a pas appelé HttpInitialize avant d’appeler HttpCreateRequestQueue. |
Remarques
L’API serveur HTTP prend en charge les applications existantes à l’aide des files d’attente de requêtes version 1.0. Toutefois, le nouveau développement avec l’API serveur HTTP doit utiliser HttpCreateRequestQueue pour créer des files d’attente de requête ; httpCreateHttpHandle ne doit pas être utilisé. L’API version 2.0 n’est compatible que 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 le 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 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ête peut définir des listes de contrôle d’accès (ACL) sur le handle de file d’attente de requête pour autoriser les processus (autres que l’application créateur) à ouvrir, recevoir des demandes et envoyer des réponses sur le handle de file d’attente de requête. Par défaut, les applications ne sont pas autorisées à ouvrir une file d’attente de demandes, sauf si elles ont reçu 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 de requêtes. Les applications non-contrôleur 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 le HttpSetRequestQueueProperty.
Le handle de la file d’attente de requêtes créé par HttpCreateRequestQueue doit être fermé en appelant HttpCloseRequestQueue avant que l’application ne se termine ou lorsque la session n’est plus nécessaire.
Les applications doivent appeler HttpInitialize avant d’appeler HttpCreateRequestQueue.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows Vista [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | http.h |
| bibliothèque | Httpapi.lib |
| DLL | Httpapi.dll |