funzione listen (winsock2.h)

La funzione di ascolto inserisce un socket in uno stato in cui è in ascolto per una connessione in ingresso.

Sintassi

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

Parametri

[in] s

Descrittore che identifica un socket associato, non connesso.

[in] backlog

Lunghezza massima della coda di connessioni in sospeso. Se impostato su SOMAXCONN, il provider di servizi sottostante responsabile del socket s imposta il backlog su un valore ragionevole massimo. Se impostato su SOMAXCONN_HINT(N) (dove N è un numero), il valore del backlog sarà N, modificato per essere compreso nell'intervallo (200, 65535). Si noti che SOMAXCONN_HINT può essere usato per impostare il backlog su un valore maggiore del possibile con SOMAXCONN.

SOMAXCONN_HINT è supportato solo dal provider di servizi TCP/IP Microsoft. Non è disponibile alcun provisioning standard per ottenere il valore del backlog effettivo.

Valore restituito

Se non si verifica alcun errore, il listen restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEADDRINUSE	L'indirizzo locale del socket è già in uso e il socket non è stato contrassegnato per consentire il riutilizzo degli indirizzi con SO_REUSEADDR. Questo errore si verifica in genere durante l'esecuzione della funzione di associazione, ma potrebbe essere ritardato fino a quando la funzione è stata associata a un indirizzo parzialmente jolly (che include ADDR_ANY) e se è necessario eseguire il commit di un indirizzo specifico al momento di questa funzione.
WSAEINPROGRESS	Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEINVAL	Il socket non è stato associato all'associazione.
WSAEISCONN	Il socket è già connesso.
WSAEMFILE	Descrittori di socket esauriti.
WSAENOBUFS	Nessuno spazio di buffer disponibile.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	Il socket a cui si fa riferimento non è di un tipo che supporta l'operazione di ascolto .

Commenti

Per accettare le connessioni, viene prima creato un socket con la funzione socket e associato a un indirizzo locale con la funzione di associazione . Viene specificato un backlog per le connessioni in ingresso con listen e quindi le connessioni vengono accettate con la funzione di accettazione . I socket orientati alla connessione, quelli di tipo SOCK_STREAM , ad esempio, vengono usati con l'ascolto. Il socket s viene inserito in modalità passiva in cui le richieste di connessione in ingresso vengono riconosciute e accodate in attesa dell'accettazione dal processo.

Un valore per il backlog di SOMAXCONN è una costante speciale che indica al provider di servizi sottostante responsabile del socket s di impostare la lunghezza della coda di connessioni in sospeso a un valore massimo ragionevole.

In Windows Sockets 2, questo valore massimo viene predefinito su un valore elevato (in genere diverse centinaia o più).

Quando si chiama la funzione di ascolto in un'applicazione Bluetooth, è consigliabile usare un valore molto inferiore per il parametro backlog (in genere da 2 a 4), poiché vengono accettate solo alcune connessioni client. Ciò riduce le risorse di sistema allocate per l'uso dal socket in ascolto. Questa stessa raccomandazione si applica ad altre applicazioni di rete che prevedono solo alcune connessioni client.

La funzione di ascolto viene in genere usata dai server che possono avere più richieste di connessione alla volta. Se una richiesta di connessione arriva e la coda è completa, il client riceverà un errore con un'indicazione di WSAECONNREFUSED.

Se non sono disponibili descrittori socket, il listen tenta di continuare a funzionare. Se i descrittori diventano disponibili, una chiamata successiva per l'ascolto o l'accettazione riempirà la coda al valore corrente o più recente specificato per il parametro backlog , se possibile e riprende l'ascolto per le connessioni in ingresso.

Se la funzione di ascolto viene chiamata su un socket già in ascolto, restituirà l'esito positivo senza modificare il valore per il parametro backlog . L'impostazione del parametro backlog su 0 in una chiamata successiva per l'ascolto su un socket di ascolto non viene considerata una reimpostazione corretta, soprattutto se sono presenti connessioni nel socket.

Nota Quando si emette una chiamata Winsock bloccata , ad esempio listen, Winsock potrebbe dover attendere un evento di rete prima che la chiamata possa completare. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di routine asincrona pianificata nello stesso thread. L'emissione di un'altra chiamata winsock bloccata all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread comporterà un comportamento non definito e non deve mai essere tentato dai client Winsock.

 

Codice di esempio

Nell'esempio seguente viene illustrato l'uso della funzione 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;
}

Codice di esempio

Per un altro esempio che usa la funzione di ascolto, vedere Introduzione With Winsock.

Note per i socket IrDA

• Il file di intestazione Af_irda.h deve essere incluso in modo esplicito.

Compatibilità

Il parametro backlog è limitato (in modo invisibile) a un valore ragionevole determinato dal provider di servizi sottostante. I valori illegali vengono sostituiti dal valore legale più vicino. Non è disponibile alcun provisioning standard per individuare il valore effettivo del backlog.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop | App UWP]
Server minimo supportato	Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll

Vedi anche

Funzioni Winsock

Informazioni di riferimento su Winsock

Accettare

connect

socket