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.
| Code d'erreur | Signification |
|---|---|
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. | |
| Le sous-système réseau a échoué. | |
| 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. | |
| Un appel Windows Sockets 1.1 bloquant est en cours ou le fournisseur de services traite toujours une fonction de rappel. | |
| Le socket n’a pas été lié à bind. | |
| Le socket est déjà connecté. | |
| Aucun descripteur de socket supplémentaire n'est disponible. | |
| Aucune zone tampon disponible. | |
| Le descripteur n’est pas un socket. | |
| 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.
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 |