listen-Funktion (winsock2.h)

Artikel
03/06/2024

Die Listenfunktion versetzt einen Socket in einen Zustand, in dem er auf eine eingehende Verbindung lauscht.

Syntax

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

Parameter

[in] s

Ein Deskriptor, der einen gebundenen, nicht verbundenen Socket identifiziert.

[in] backlog

Die maximale Länge der Warteschlange ausstehender Verbindungen. Wenn auf SOMAXCONN festgelegt ist, legt der zugrunde liegende Dienstanbieter, der für Sockets verantwortlich ist, den Backlog auf einen maximal angemessenen Wert fest. Wenn auf SOMAXCONN_HINT(N) festgelegt ist (wobei N eine Zahl ist), ist der Backlogwert N, der so angepasst wird, dass er sich innerhalb des Bereichs (200, 65535) befindet. Beachten Sie, dass SOMAXCONN_HINT verwendet werden kann, um den Backlog auf einen größeren Wert als mit SOMAXCONN festzulegen.

SOMAXCONN_HINT wird nur vom Microsoft TCP/IP-Dienstanbieter unterstützt. Es gibt keine Standardbereitstellung, um den tatsächlichen Backlogwert abzurufen.

Rückgabewert

Wenn kein Fehler auftritt, gibt listen null zurück. Andernfalls wird der Wert SOCKET_ERROR zurückgegeben, und ein bestimmter Fehlercode kann durch Aufrufen von WSAGetLastError abgerufen werden.

Fehlercode	Bedeutung
WSANOTINITIALISIERT	Vor der Verwendung dieser Funktion muss ein erfolgreicher WSAStartup-Aufruf erfolgen.
WSAENETDOWN	Beim Netzwerksubsystem ist ein Fehler aufgetreten.
WSAEADDRINUSE	Die lokale Adresse des Sockets wird bereits verwendet, und der Socket wurde nicht markiert, um die Wiederverwendung von Adressen mit SO_REUSEADDR zu ermöglichen. Dieser Fehler tritt normalerweise während der Ausführung der Bindungsfunktion auf, kann jedoch bis zu dieser Funktion verzögert werden, wenn die Bindung an eine teilweise Aufplatzhalteradresse (mit ADDR_ANY) war und wenn eine bestimmte Adresse zum Zeitpunkt dieser Funktion festgelegt werden muss.
WSAEINPROGRESS	Ein blockierter Windows Sockets 1.1-Aufruf wird ausgeführt, oder der Dienstanbieter verarbeitet weiterhin eine Rückruffunktion.
WSAEINVAL	Der Socket wurde nicht an bind gebunden.
WSAEISCONN	Der Socket ist bereits verbunden.
WSAEMFILE	Es sind keine weiteren Socketbeschreibungen verfügbar.
WSAENOBUFS	Es ist kein Pufferplatz verfügbar.
WSAENOTSOCK	Der Deskriptor ist kein Socket.
WSAEOPNOTSUPP	Der Socket, auf den verwiesen wird, hat keinen Typ, der den Listenvorgang unterstützt.

Hinweise

Um Verbindungen zu akzeptieren, wird zunächst ein Socket mit der Socketfunktion erstellt und mit der Bindungsfunktion an eine lokale Adresse gebunden. Ein Backlog für eingehende Verbindungen wird mit listen angegeben, und dann werden die Verbindungen mit der Accept-Funktion akzeptiert. Verbindungsorientierte Sockets, z. B. vom Typ SOCK_STREAM , werden beim Listen verwendet. Der Socket s wird in den passiven Modus versetzt, in dem eingehende Verbindungsanforderungen bestätigt und in die Warteschlange gestellt werden, bis die Annahme durch den Prozess aussteht.

Ein Wert für den Backlog von SOMAXCONN ist eine spezielle Konstante, die den zugrunde liegenden Dienstanbieter anweist, der für Sockets verantwortlich ist, die Länge der Warteschlange der ausstehenden Verbindungen auf einen maximal angemessenen Wert festzulegen.

Unter Windows Sockets 2 wird dieser Maximalwert standardmäßig auf einen großen Wert (in der Regel mehrere hundert oder mehr) festgelegt.

Beim Aufrufen der Listenfunktion in einer Bluetooth-Anwendung wird dringend empfohlen, einen viel niedrigeren Wert für den Backlogparameter (in der Regel 2 bis 4) zu verwenden, da nur wenige Clientverbindungen akzeptiert werden. Dadurch werden die Systemressourcen reduziert, die für die Verwendung durch den Abhörsocket zugewiesen werden. Die gleiche Empfehlung gilt für andere Netzwerkanwendungen, die nur wenige Clientverbindungen erwarten.

Die Listenfunktion wird in der Regel von Servern verwendet, die mehrere Verbindungsanforderungen gleichzeitig aufweisen können. Wenn eine Verbindungsanforderung eingeht und die Warteschlange voll ist, erhält der Client eine Fehlermeldung mit einem Hinweis auf WSAECONNREFUSED.

Wenn keine Socketdeskriptoren verfügbar sind, versucht das Zuhören , weiterhin zu funktionieren. Wenn Deskriptoren verfügbar werden, füllt ein späterer Aufruf zum Lauschen oder Akzeptieren die Warteschlange erneut auf den aktuellen oder letzten Wert, der für den Backlogparameter angegeben ist, und setzt die Überwachung auf eingehende Verbindungen fort.

Wenn die Listenfunktion auf einem bereits lauschenden Socket aufgerufen wird, gibt sie erfolglos zurück, ohne den Wert für den Backlogparameter zu ändern. Das Festlegen des Backlogparameters auf 0 in einem nachfolgenden Aufruf zum Lauschen eines Abhörsockets wird nicht als ordnungsgemäßes Zurücksetzen angesehen, insbesondere, wenn verbindungen am Socket vorhanden sind.

Hinweis Wenn Sie einen blockierenden Winsock-Aufruf ausstellen, z. B . lauschen, muss Winsock möglicherweise auf ein Netzwerkereignis warten, bevor der Anruf abgeschlossen werden kann. Winsock führt in dieser Situation eine warnbare Wartezeit aus, die durch einen asynchronen Prozeduraufruf (APC) unterbrochen werden kann, der für denselben Thread geplant ist. Das Ausgeben eines weiteren blockierenden Winsock-Aufrufs in einem APC, der einen fortlaufenden blockierenden Winsock-Aufruf im selben Thread unterbrochen hat, führt zu nicht definiertem Verhalten und darf niemals von Winsock-Clients versucht werden.

Beispielcode

Im folgenden Beispiel wird die Verwendung der Listenfunktion veranschaulicht.

#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;
}

Beispielcode

Ein weiteres Beispiel, das die Listenfunktion verwendet, finden Sie unter Erste Schritte Mit Winsock.

Hinweise zu IrDA-Sockets

Die Af_irda.h-Headerdatei muss explizit enthalten sein.

Kompatibilität

Der Backlogparameter ist (unbeaufsichtigt) auf einen angemessenen Wert beschränkt, der vom zugrunde liegenden Dienstanbieter bestimmt wird. Ungültige Werte werden durch den nächstgelegenen gesetzlichen Wert ersetzt. Es gibt keine Standardbereitstellung, um den tatsächlichen Backlogwert zu ermitteln.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps auf Windows Phone 8 und höher unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock2.h
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll