code de contrôle SIO_ASSOCIATE_PORT_RESERVATION

Article
06/13/2023

Description

Le code de contrôle SIO_ASSOCIATE_PORT_RESERVATION associe un socket à une réservation persistante ou runtime pour un bloc de TCP ou UDP identifié par le jeton de réservation de port. Ce IOCTL doit être émis avant que le socket ne soit lié. Si et quand le socket est lié, le port qui lui est affecté est sélectionné à partir de la réservation de port identifiée par le jeton donné. Si aucun port n’est disponible à partir de la réservation spécifiée, l’appel de la fonction de liaison échoue.

Pour effectuer cette opération, appelez la fonction WSAIoctl ou WSPIoctl avec les paramètres suivants.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_ASSOCIATE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RESERVATION_TOKEN
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  NULL,           // lpvOutBuffer is a pointer to the output buffer
  0,              // cbOutBuffer is the size, in bytes, of the output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Paramètres

s

Descripteur identifiant un socket.

dwIoControlCode

Code de contrôle pour l’opération. Utilisez SIO_ASSOCIATE_PORT_RESERVATION pour cette opération.

lpvInBuffer

Pointeur vers la mémoire tampon d’entrée. Ce paramètre contient un pointeur vers une structure INET_PORT_RESERVATION_TOKEN avec le jeton pour la réservation de port TCP ou UDP à associer au socket.

cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée. Ce paramètre doit être au moins de la taille de la structure INET_PORT_RESERVATION_TOKEN .

lpvOutBuffer

Pointeur vers la mémoire tampon de sortie. Ce paramètre n’est pas utilisé pour cette opération.

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie. Ce paramètre doit être défini sur zéro.

lpcbBytesReturned

Pointeur vers une variable qui reçoit la taille, en octets, des données stockées dans la mémoire tampon de sortie.

Si la mémoire tampon de sortie est trop petite, l’appel échoue, WSAGetLastError renvoie WSAEINVAL et le paramètre lpcbBytesReturned pointe vers une valeur DWORD de zéro.

Si lpOverlapped a la valeur NULL, la valeur DWORD pointée par le paramètre lpcbBytesReturned retourné lors d’un appel réussi ne peut pas être égale à zéro.

Si le paramètre lpOverlapped n’est pas NULL pour les sockets superposés, les opérations qui ne peuvent pas être effectuées immédiatement sont lancées et l’achèvement sera indiqué ultérieurement. La valeur DWORD pointée par le paramètre lpcbBytesReturned retourné peut être égale à zéro, car la taille des données stockées ne peut pas être déterminée tant que l’opération superposée n’est pas terminée. La status d’achèvement finale peut être récupérée lorsque la méthode d’achèvement appropriée est signalée lorsque l’opération est terminée.

lpvOverlapped

Pointeur vers une structure WSAOVERLAPPED .

Si le socket s a été créé sans l’attribut superposé, le paramètre lpOverlapped est ignoré.

Si s a été ouvert avec l’attribut qui se chevauche et que le paramètre lpOverlapped n’a pas la valeur NULL, l’opération est effectuée en tant qu’opération (asynchrone) qui se chevauche. Dans ce cas, le paramètre lpOverlapped doit pointer vers une structure WSAOVERLAPPED valide.

Pour les opérations qui se chevauchent, la fonction WSAIoctl ou WSPIoctl retourne immédiatement, et la méthode d’achèvement appropriée est signalée une fois l’opération terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou qu’une erreur se produit.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée (ignorée pour les sockets qui ne se chevauchent pas).

lpThreadId

Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

lpErrno

Pointeur vers le code d’erreur.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

Valeur retournée

Si l’opération se termine correctement, la fonction WSAIoctl ou WSPIoctl retourne zéro.

Si l’opération échoue ou est en attente, la fonction WSAIoctl ou WSPIoctl retourne SOCKET_ERROR. Pour obtenir des informations d’erreur étendues, appelez WSAGetLastError.

Code d'erreur	Signification
WSA_IO_PENDING	L’opération d’E/S qui se chevauche est en cours. Cette valeur est retournée si une opération qui se chevauche a été lancée avec succès et que l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	L'opération d'E/S a été abandonnée en raison de l'arrêt d'un thread ou de la requête d'une application. Cette erreur est retournée si une opération qui se chevauche a été annulée en raison de la fermeture du socket ou de l’exécution de la commande IOCTL SIO_FLUSH .
WSAEACCES	Une tentative d’accès à un socket a été effectuée d’une manière interdite par ses autorisations d’accès. Cette erreur est retournée dans plusieurs conditions pour les réservations de ports persistantes qui incluent les éléments suivants : 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é (`RunAs administrator`).
WSAEFAULT	Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un argument pointeur dans un appel. Cette erreur est retournée du paramètre lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINPROGRESS	Une opération de blocage est actuellement en cours d'exécution. Cette erreur est retournée si la fonction est appelée lorsqu’un rappel est en cours.
WSAEINTR	Une opération de blocage a été interrompue par un appel à WSACancelBlockingCall. Cette erreur est retournée si une opération de blocage a été interrompue.
WSAEINVAL	Argument non valide fourni. Cette erreur est retournée si le paramètre dwIoControlCode n’est pas une commande valide, si un paramètre d’entrée spécifié n’est pas acceptable ou si la commande n’est pas applicable au type de socket spécifié.
WSAENETDOWN	Une opération de socket a rencontré un réseau inactif. Cette erreur est retournée si le sous-système réseau a échoué.
WSAENOTSOCK	Une opération a été tentée sur un objet qui n’est pas un socket. Cette erreur est retournée si le descripteur s n’est pas un socket.
WSAEOPNOTSUPP	L’opération tentée n’est pas prise en charge pour le type d’objet référencé. Cette erreur est retournée si la commande IOCTL spécifiée n’est pas prise en charge. Cette erreur est également retournée si le SIO_ASSOCIATE_PORT_RESERVATION IOCTL n’est pas pris en charge par le fournisseur de transport. Cette erreur est également retournée lorsqu’une tentative d’utilisation du SIO_ASSOCIATE_PORT_RESERVATION IOCTL est effectuée sur un socket autre qu’UDP ou TCP.

Notes

La SIO_ASSOCIATE_PORT_RESERVATION IOCTL est prise en charge sur Windows Vista et les versions ultérieures du système d’exploitation.

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.

Le SIO_ASSOCIATE_PORT_RESERVATION IOCTL est utilisé pour associer une réservation de port TCP ou UDP à une réservation persistante ou runtime.

La fonction CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation permet à une application ou à un service de réserver un bloc persistant de ports TCP ou UDP. Les réservations de ports persistants sont enregistrées dans un magasin persistant pour le module TCP ou UDP dans Windows. Notez que le jeton d’une réservation de port persistante donnée peut changer chaque fois que le système est redémarré.

Une fois qu’une réservation de port TCP ou UDP persistante a été obtenue, une application peut demander des affectations de port à partir de la réservation de port en ouvrant un socket TCP ou 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 port persistant créées à l’aide de la fonction CreatePersistentTcpPortReservation ou CreatePersistentUdpPortReservation peuvent être consommées par n’importe quel processus ayant la possibilité d’obtenir des réservations persistantes.

Une fois qu’une réservation de port TCP ou UDP d’exécution a été obtenue, une application peut demander des affectations de port à partir de la réservation de port en ouvrant un socket TCP ou 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 bind sur le socket.

Si les paramètres lpOverlapped et lpCompletionRoutine ont la valeur NULL, le socket dans cette fonction est traité comme un socket qui ne se chevauche pas. Pour un socket non chevauché, les paramètres lpOverlapped et lpCompletionRoutine sont ignorés, sauf que la fonction peut bloquer si le socket est en mode bloquant. Si le socket s est en mode non bloquant, cette fonction est toujours bloquée, car ce type DETL particulier ne prend pas en charge le mode non bloquant.

Pour les sockets qui se chevauchent, les opérations qui ne peuvent pas être effectuées immédiatement sont lancées et l’achèvement sera indiqué ultérieurement.

Tout IOCTL peut se bloquer indéfiniment, en fonction de l’implémentation du fournisseur de services. Si l’application ne peut pas tolérer le blocage dans un appel de fonction WSAIoctl ou WSPIoctl , les E/S qui se chevauchent sont recommandées pour les IOCTL qui sont particulièrement susceptibles de se bloquer.

Le SIO_ASSOCIATE_PORT_RESERVATION IOCTL peut échouer avec WSAEINTR ou WSA_OPERATION_ABORTED dans les cas suivants :

La demande est annulée par le gestionnaire d’E/S.
Le socket est fermé.

La SIO_ASSOCIATE_PORT_RESERVATION IOCTL passée à la fonction WSAIoctl ou WSPIoctl pour une réservation de port persistant ne peut être utilisée dans une application que lorsque l’utilisateur est connecté en tant que membre du groupe Administrateurs. Si SIO_ASSOCIATE_PORT_RESERVATION IOCTL est utilisé dans une application lorsque l’utilisateur n’est pas membre du groupe Administrateurs, l’appel de fonction échoue et WSAEACCES est retourné. L’utilisation de la SIO_ASSOCIATE_PORT_RESERVATION IOCTL peut également échouer en raison du contrôle de compte d’utilisateur (UAC) sur Windows Vista et versions ultérieures. Si une application qui utilise cet IOCTL avec une réservation de port persistante 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é (RunAs administrator) pour que cette fonction réussisse.