listen, fonction (winsock2.h)

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.

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.

Exemple de code

#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

Remarques pour les sockets IrDA

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

Compatibilité

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

Voir aussi

Winsock Functions

Référence Winsock

Accepter

connect

socket