listen, fonction (winsock2.h)

Article
08/27/2023

La fonction listen place un socket dans un état dans lequel il écoute une connexion entrante.

Syntaxe

int WSAAPI listen(
  [in] SOCKET s,
  [in] int    backlog
);

Paramètres

[in] s

Descripteur identifiant un socket lié et non connecté.

[in] backlog

Longueur maximale de la file d’attente des connexions en attente. S’il est défini sur SOMAXCONN, le fournisseur de services sous-jacent responsable des sockets définit le backlog sur une valeur raisonnable maximale. Si la valeur est SOMAXCONN_HINT(N) (où N est un nombre), la valeur du backlog est N, ajustée pour être comprise dans la plage (200, 65535). Notez que SOMAXCONN_HINT peut être utilisé pour définir le backlog sur une valeur supérieure à celle possible avec SOMAXCONN.

SOMAXCONN_HINT est uniquement pris en charge par le fournisseur de services MICROSOFT TCP/IP. Il n’existe pas de provisionnement standard pour obtenir la valeur de backlog réelle.

Valeur retournée

Si aucune erreur ne se produit, listen retourne zéro. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEADDRINUSE	L’adresse locale du socket est déjà utilisée et le socket n’a pas été marqué pour permettre la réutilisation de l’adresse avec SO_REUSEADDR. Cette erreur se produit généralement pendant l’exécution de la fonction de liaison , mais peut être retardée jusqu’à cette fonction si la liaison était une adresse générique partielle (impliquant ADDR_ANY) et si une adresse spécifique doit être validée au moment de cette fonction.
WSAEINPROGRESS	Un appel Windows Sockets 1.1 bloquant est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINVAL	Le socket n’a pas été lié à bind.
WSAEISCONN	Le socket est déjà connecté.
WSAEMFILE	Aucun descripteur de socket supplémentaire n'est disponible.
WSAENOBUFS	Aucune zone tampon disponible.
WSAENOTSOCK	Le descripteur n’est pas un socket.
WSAEOPNOTSUPP	Le socket référencé n’est pas d’un type qui prend en charge l’opération d’écoute .

Remarques

Pour accepter les connexions, un socket est d’abord créé avec la fonction socket et lié à une adresse locale avec la fonction bind . Un backlog pour les connexions entrantes est spécifié avec listen, puis les connexions sont acceptées avec la fonction accept . Les sockets orientés connexion, ceux de type SOCK_STREAM par exemple, sont utilisés avec listen. Les sockets sont mis en mode passif où les demandes de connexion entrantes sont reconnues et mises en file d’attente en attente d’acceptation par le processus.

Une valeur pour le backlog de SOMAXCONN est une constante spéciale qui indique au fournisseur de services sous-jacent responsable des sockets de définir la longueur de la file d’attente des connexions en attente sur une valeur raisonnable maximale.

Sur Windows Sockets 2, cette valeur maximale est définie par défaut sur une valeur élevée (généralement plusieurs centaines ou plus).

Lors de l’appel de la fonction listen dans une application Bluetooth, il est fortement recommandé d’utiliser une valeur beaucoup plus faible pour le paramètre backlog (généralement 2 à 4), car seules quelques connexions clientes sont acceptées. Cela réduit les ressources système allouées à l’utilisation par le socket d’écoute. Cette même recommandation s’applique aux autres applications réseau qui n’attendent que quelques connexions clientes.

La fonction listen est généralement utilisée par les serveurs qui peuvent avoir plusieurs demandes de connexion à la fois. Si une demande de connexion arrive et que la file d’attente est pleine, le client reçoit une erreur avec une indication de WSAECONNREFUSED.

S’il n’existe aucun descripteur de socket disponible, écoute tente de continuer à fonctionner. Si les descripteurs deviennent disponibles, un appel ultérieur pour écouter ou accepter recharge la file d’attente à la valeur actuelle ou la plus récente spécifiée pour le paramètre backlog , si possible, et reprend l’écoute des connexions entrantes.

Si la fonction listen est appelée sur un socket déjà à l’écoute, elle retourne la réussite sans modifier la valeur du paramètre backlog . La définition du paramètre backlog sur 0 dans un appel suivant pour écouter sur un socket d’écoute n’est pas considérée comme une réinitialisation appropriée, en particulier s’il existe des connexions sur le socket.

Note Lors de l’émission d’un appel Winsock bloquant tel que l’écoute, Winsock peut avoir besoin d’attendre un événement réseau avant que l’appel puisse se terminer. Winsock effectue une attente pouvant être alertée dans cette situation, qui peut être interrompue par un appel de procédure asynchrone (APC) planifié sur le même thread. L’émission d’un autre appel Winsock bloquant à l’intérieur d’un APC qui interrompt un appel Winsock bloquant en cours sur le même thread entraîne un comportement non défini et ne doit jamais être tenté par les clients Winsock.

Exemple de code

L’exemple suivant illustre l’utilisation de la fonction listen .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

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

int wmain()
{

    //----------------------
    // Initialize Winsock
    WSADATA wsaData;
    int iResult = 0;

    SOCKET ListenSocket = INVALID_SOCKET;
    sockaddr_in service;

    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"WSAStartup() failed with error: %d\n", iResult);
        return 1;
    }
    //----------------------
    // Create a SOCKET for listening for incoming connection requests.
    ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ListenSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // The sockaddr_in structure specifies the address family,
    // IP address, and port for the socket that is being bound.
    service.sin_family = AF_INET;
    service.sin_addr.s_addr = inet_addr("127.0.0.1");
    service.sin_port = htons(27015);

    iResult = bind(ListenSocket, (SOCKADDR *) & service, sizeof (service));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"bind function failed with error %d\n", WSAGetLastError());
        iResult = closesocket(ListenSocket);
        if (iResult == SOCKET_ERROR)
            wprintf(L"closesocket function failed with error %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // Listen for incoming connection requests 
    // on the created socket
    if (listen(ListenSocket, SOMAXCONN) == SOCKET_ERROR)
        wprintf(L"listen function failed with error: %d\n", WSAGetLastError());

    wprintf(L"Listening on socket...\n");

    iResult = closesocket(ListenSocket);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"closesocket function failed with error %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    WSACleanup();
    return 0;
}

Exemple de code

Pour obtenir un autre exemple qui utilise la fonction listen, consultez Prise en main With Winsock.

Remarques pour les sockets IrDA

Le fichier d’en-tête Af_irda.h doit être inclus explicitement.

Compatibilité

Le paramètre backlog est limité (en mode silencieux) à une valeur raisonnable déterminée par le fournisseur de services sous-jacent. Les valeurs non valides sont remplacées par la valeur légale la plus proche. Il n’existe pas de provisionnement standard pour déterminer la valeur réelle du backlog.

Windows Phone 8 : cette fonction est prise en charge pour les applications Windows Phone Store sur Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll