code de contrôle SIO_ACQUIRE_PORT_RESERVATION

Article
06/13/2023

Description

Le code de contrôle SIO_ACQUIRE_PORT_RESERVATION acquiert une réservation d’exécution pour un bloc de ports TCP ou UDP.

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_ACQUIRE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RANGE structure
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to an INET_PORT_RESERVATION_INSTANCE structure
  (DWORD) cbOutBuffer,   // 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_ACQUIRE_PORT_RESERVATION, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to an INET_PORT_RANGE structure
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,             // pointer to a INET_PORT_RESERVATION_INSTANCE structure
  (DWORD) cbOutBuffer,   // 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_ACQUIRE_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_RANGE qui spécifie le numéro de point de départ et le nombre de ports à réserver.

cbInBuffer

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

lpvOutBuffer

Pointeur vers la mémoire tampon de sortie. En cas de sortie réussie, ce paramètre contient un pointeur vers une structure INET_PORT_RESERVATION_INSTANCE .

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie. Ce paramètre doit être au moins la taille de la structure INET_PORT_RESERVATION_INSTANCE .

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 .
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_ACQUIRE_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_ACQUIRE_PORT_RESERVATION IOCTL est effectuée sur un socket autre qu’UDP ou TCP.

Notes

Le SIO_ACQUIRE_PORT_RESERVATION IOCTL est pris 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_ACQUIRE_PORT_RESERVATION IOCTL est 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 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_ACQUIRE_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é.

Exemples

L’exemple suivant acquiert une réservation de port d’exécution, crée un socket et alloue un port à partir de la réservation de port d’exécution pour le socket, puis ferme le socket et libère la réservation de port d’exécution.

#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <Windows.h.>
#include <winsock2.h>
#include <mstcpip.h>
#include <ws2ipdef.h>
#include <stdio.h>
#include <stdlib.h>

// Need to link with Ws2_32.lib for Winsock functions
#pragma comment(lib, "ws2_32.lib")

int wmain(int argc, WCHAR ** argv)
{

    // Declare and initialize variables

    int startPort = 0;          // host byte order
    int numPorts = 0;
    USHORT startPortns = 0;     // Network byte order

    INET_PORT_RANGE portRange = { 0 };
    INET_PORT_RESERVATION_INSTANCE portRes = { 0 };

    unsigned long status = 0;

    WSADATA wsaData = { 0 };
    int iResult = 0;

    SOCKET sock = INVALID_SOCKET;
    int iFamily = AF_INET;
    int iType = 0;
    int iProtocol = 0;

    SOCKET sockRes = INVALID_SOCKET;

    DWORD bytesReturned = 0;

    // Note that the sockaddr_in struct works only with AF_INET not AF_INET6
    // An application needs to use the sockaddr_in6 for AF_INET6
    sockaddr_in service;
    sockaddr_in sockName;
    int nameLen = sizeof (sockName);

    // Validate the parameters
    if (argc != 6) {
        wprintf
            (L"usage: %s <addressfamily> <type> <protocol> <StartingPort> <NumberOfPorts>\n",
             argv[0]);
        wprintf(L"Opens a socket for the specified family, type, & protocol\n");
        wprintf
            (L"and then acquires a runtime port reservation for the protocol specified\n");
        wprintf(L"%ws example usage\n", argv[0]);
        wprintf(L"   %ws 2 2 17 5000 20\n", argv[0]);
        wprintf(L"   where AF_INET=2 SOCK_DGRAM=2 IPPROTO_UDP=17 StartPort=5000 NumPorts=20", argv[0]);

        return 1;
    }

    iFamily = _wtoi(argv[1]);
    iType = _wtoi(argv[2]);
    iProtocol = _wtoi(argv[3]);

    startPort = _wtoi(argv[4]);
    if (startPort < 0 || startPort > 65535) {
        wprintf(L"Starting point must be either 0 or between 1 and 65,535\n");
        return 1;
    }
    startPortns = htons((USHORT) startPort);

    numPorts = _wtoi(argv[5]);
    if (numPorts < 0) {
        wprintf(L"Number of ports must be a positive number\n");
        return 1;
    }

    portRange.StartPort = startPortns;
    portRange.NumberOfPorts = (USHORT) numPorts;

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed with error = %d\n", iResult);
        return 1;
    }

    sock = socket(iFamily, iType, iProtocol);
    if (sock == INVALID_SOCKET) {
        wprintf(L"socket function failed with error = %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    } else {
        wprintf(L"socket function succeeded\n");

        iResult =
            WSAIoctl(sock, SIO_ACQUIRE_PORT_RESERVATION, (LPVOID) & portRange,
                     sizeof (INET_PORT_RANGE), (LPVOID) & portRes,
                     sizeof (INET_PORT_RESERVATION_INSTANCE), &bytesReturned, NULL, NULL);
        if (iResult != 0) {
            wprintf(L"WSAIoctl(SIO_ACQUIRE_PORT_RESERVATION) failed with error = %d\n",
                    WSAGetLastError());
            closesocket(sock);
            WSACleanup();
            return 1;
        } else {
            wprintf
                (L"WSAIoctl(SIO_ACQUIRE_PORT_RESERVATION) succeeded, bytesReturned = %u\n",
                 bytesReturned);
            wprintf(L"  Starting port=%d,  Number of Ports=%d, Token=%I64d\n",
                    htons(portRes.Reservation.StartPort),
                    portRes.Reservation.NumberOfPorts, portRes.Token);

            sockRes = socket(iFamily, iType, iProtocol);
            if (sockRes == INVALID_SOCKET) {
                wprintf(L"socket function for second socket failed with error = %d\n",
                        WSAGetLastError());
                closesocket(sock);
                WSACleanup();
                return 1;
            } else {
                wprintf(L"socket function for second socket succeeded\n");

                iResult =
                    WSAIoctl(sock, SIO_ASSOCIATE_PORT_RESERVATION,
                             (LPVOID) & portRes.Token, sizeof (ULONG64), NULL, 0,
                             &bytesReturned, NULL, NULL);
                if (iResult != 0) {
                    wprintf
                        (L"WSAIoctl(SIO_ASSOCIATE_PORT_RESERVATION) failed with error = %d\n",
                         WSAGetLastError());
                } else {
                    wprintf
                        (L"WSAIoctl(SIO_ASSOCIATE_PORT_RESERVATION) succeeded, bytesReturned = %u\n",
                         bytesReturned);

                    service.sin_family = (ADDRESS_FAMILY) iFamily;
                    service.sin_addr.s_addr = INADDR_ANY;
                    service.sin_port = 0;

                    iResult = bind(sock, (SOCKADDR *) & service, sizeof (service));
                    if (iResult == SOCKET_ERROR)
                        wprintf(L"bind failed with error = %d\n", WSAGetLastError());
                    else {
                        wprintf(L"bind succeeded\n");
                        iResult = getsockname(sock, (SOCKADDR *) & sockName, &nameLen);
                        if (iResult == SOCKET_ERROR)
                            wprintf(L"getsockname failed with error = %d\n",
                                    WSAGetLastError());
                        else {
                            wprintf(L"getsockname succeeded\n");
                            wprintf(L"Port number allocated = %u\n",
                                    ntohs(sockName.sin_port));
                        }
                    }
                }
            }

            // comment out this block of code if you don't want to delete the reservation just created
            iResult =
                WSAIoctl(sock, SIO_RELEASE_PORT_RESERVATION, (LPVOID) & portRes.Token,
                         sizeof (ULONG64), NULL, 0, &bytesReturned, NULL, NULL);
            if (iResult != 0) {
                wprintf
                    (L"WSAIoctl(SIO_RELEASE_PORT_RESERVATION) failed with error = %d\n",
                     WSAGetLastError());
            } else {
                wprintf
                    (L"WSAIoctl(SIO_RELEASE_PORT_RESERVATION) succeeded, bytesReturned = %u\n",
                     bytesReturned);
            }
        }

        if (sockRes != INVALID_SOCKET) {
            iResult = closesocket(sockRes);
            if (iResult == SOCKET_ERROR) {
                wprintf(L"closesocket for second socket failed with error = %d\n",
                        WSAGetLastError());
            }
        }
        if (sock != INVALID_SOCKET) {
            iResult = closesocket(sock);
            if (iResult == SOCKET_ERROR) {
                wprintf(L"closesocket for first socket failed with error = %d\n",
                        WSAGetLastError());
            }
        }
    }

    WSACleanup();

    return 0;
}