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 |
|---|---|
| Prima di usare questa funzione, è necessario eseguire una chiamata WSAStartup riuscita. | |
| Il sottosistema di rete non è riuscito. | |
| 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. | |
| Una chiamata windows Sockets 1.1 bloccata è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback. | |
| Il socket non è stato associato all'associazione. | |
| Il socket è già connesso. | |
| Descrittori di socket esauriti. | |
| Nessuno spazio di buffer disponibile. | |
| Il descrittore non è un socket. | |
| 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.
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 |