CreatePersistentUdpPortReservation, fonction (iphlpapi.h)

Article
03/14/2023

La fonction CreatePersistentUdpPortReservation crée une réservation de port UDP persistante pour un bloc consécutif de ports UDP sur l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE ULONG CreatePersistentUdpPortReservation(
  [in]  USHORT   StartPort,
  [in]  USHORT   NumberOfPorts,
  [out] PULONG64 Token
);

Paramètres

[in] StartPort

Numéro de port UDP de départ dans l’ordre d’octet réseau.

[in] NumberOfPorts

Nombre de numéros de port UDP à réserver.

[out] Token

Pointeur vers un jeton de réservation de port retourné si la fonction réussit.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_ACCESS_DENIED	L’accès est refusé. Cette erreur est retournée dans plusieurs conditions, notamment : l’utilisateur n’a pas les privilèges d’administration requis sur l’ordinateur local ou l’application ne s’exécute pas dans un interpréteur de commandes amélioré en tant qu’administrateur intégré (administrateur RunAs).
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si zéro est passé dans les paramètres StartPort ou NumberOfPorts . Cette erreur est également retournée si le paramètre NumberOfPorts est un bloc de ports trop grand selon le paramètre StartPort que le bloc de ports allocable dépasserait le port maximal qui peut être alloué.
ERROR_SHARING_VIOLATION	Le processus ne peut pas accéder au fichier car ce fichier est utilisé par un autre processus. Cette erreur est retournée si un port UDP dans le bloc de ports UDP spécifié par les paramètres StartPort et NumberOfPorts est déjà utilisé. Cette erreur est également retournée si une réservation persistante pour un bloc de ports UDP spécifié par les paramètres StartPort et NumberOfPorts correspond ou chevauche une réservation persistante pour un bloc de ports UDP qui a déjà été créé.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

La fonction CreatePersistentUdpPortReservation est définie sur Windows Vista et versions ultérieures.

La fonction CreatePersistentUdpPortReservation permet d’ajouter une réservation persistante pour un bloc de ports UDP.

Les applications et les services qui doivent réserver des ports se répartissent en deux catégories. La première catégorie inclut les composants qui ont besoin d’un port particulier dans le cadre de leur opération. Ces composants préfèrent généralement spécifier leur port requis au moment de l’installation (dans un manifeste d’application, par exemple). La deuxième catégorie inclut les composants qui ont besoin d’un port ou d’un bloc de ports disponibles au moment de l’exécution.

Ces deux catégories correspondent à des demandes de réservation de port spécifiques et génériques. Les demandes de réservation spécifiques peuvent être persistantes ou en cours d’exécution, tandis que les demandes de réservation de port générique ne sont prises en charge qu’au moment de l’exécution.

La fonction CreatePersistentUdpPortReservation permet à une application ou à un service de réserver de manière permanente un bloc de ports UDP. Les réservations TCP persistantes sont enregistrées dans un magasin persistant pour le module UDP dans Windows.

Un appelant obtient une réservation de port persistante en spécifiant le nombre de ports requis et si une plage spécifique est nécessaire. Si la demande peut être satisfaite, la fonction CreatePersistentUdpPortReservation retourne un jeton de ULONG64 opaque unique, qui identifie ensuite la réservation. Une réservation de port UDP persistante peut être libérée en appelant la fonction DeletePersistentUdpPortReservation . Notez que le jeton d’une réservation de port UDP persistante peut changer chaque fois que le système est redémarré.

Windows n’implémente pas la sécurité entre composants pour les réservations persistantes obtenues à l’aide de ces fonctions. Cela signifie que si un composant est autorisé à obtenir des réservations de port persistantes, ce composant obtient automatiquement la possibilité de consommer toutes les réservations de port persistantes accordées à n’importe quel autre composant sur le système. La sécurité au niveau du processus est appliquée pour les réservations d’exécution, mais ce contrôle ne peut pas être étendu aux réservations persistantes créées à l’aide de la fonction CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation .

Une fois qu’une réservation de port UDP persistante a été obtenue, une application peut demander des affectations de ports à partir de la réservation de port UDP en ouvrant un socket UDP, puis en appelant la fonction WSAIoctl en spécifiant le SIO_ASSOCIATE_PORT_RESERVATION IOCTL et en passant le jeton de réservation avant d’émettre un appel à la fonction de liaison sur le socket.

Le SIO_ACQUIRE_PORT_RESERVATION IOCTL peut être utilisé pour demander une réservation d’exécution pour un bloc de ports TCP ou UDP. Pour les réservations de ports d’exécution, le pool de ports nécessite que les réservations soient consommées à partir du processus sur lequel la réservation a été accordée. Les réservations de port d’exécution durent uniquement tant que la durée de vie du socket sur lequel le SIO_ACQUIRE_PORT_RESERVATION IOCTL a été appelé. En revanche, les réservations de ports persistants créées à l’aide de la fonction CreatePersistentUdpPortReservation peuvent être consommées par tout processus ayant la possibilité d’obtenir des réservations persistantes.

La fonction CreatePersistentUdpPortReservation ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si CreatePersistentUdpPortReservation est appelé par un utilisateur qui n’est pas membre du groupe Administrateurs, l’appel de fonction échoue et ERROR_ACCESS_DENIED est retourné. Cette fonction peut également échouer en raison du contrôle de compte d’utilisateur (UAC) sur Windows Vista et versions ultérieures. Si une application qui contient cette fonction est exécutée par un utilisateur connecté en tant que membre du groupe Administrateurs autre que l’administrateur intégré, cet appel échoue, sauf si l’application a été marquée dans le fichier manifeste avec un requestedExecutionLevel défini sur requireAdministrator. Si l’application ne dispose pas de ce fichier manifeste, un utilisateur connecté en tant que membre du groupe Administrateurs autre que l’administrateur intégré doit ensuite exécuter l’application dans un interpréteur de commandes amélioré en tant qu’administrateur intégré (administrateur d’exécution) pour que cette fonction réussisse.

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	iphlpapi.h
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll