функция listen (winsock2.h)

Статья
03/08/2023

Функция listen помещает сокет в состояние, в котором он прослушивает входящее соединение.

Синтаксис

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

Параметры

[in] s

Дескриптор, идентифицирующие связанный неподключаемый сокет.

[in] backlog

Максимальная длина очереди ожидающих подключений. Если задано значение SOMAXCONN, базовый поставщик услуг, ответственный за сокеты , установит для невыполненной работы максимально допустимое значение. Если задано значение SOMAXCONN_HINT(N) (где N — число), значение невыполненной работы будет равно N, скорректированное на диапазон (200, 65535). Обратите внимание, что SOMAXCONN_HINT можно использовать для установки большего значения невыполненной работы, чем это возможно с помощью SOMAXCONN.

SOMAXCONN_HINT поддерживается только поставщиком служб MICROSOFT TCP/IP. Нет стандартной подготовки для получения фактического значения невыполненной работы.

Возвращаемое значение

Если ошибка не возникает, функция listen возвращает ноль. В противном случае возвращается значение SOCKET_ERROR , а конкретный код ошибки можно получить, вызвав WSAGetLastError.

Код ошибки	Значение
WSANOTINITIALISED	Перед использованием этой функции должен произойти успешный вызов WSAStartup .
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAEADDRINUSE	Локальный адрес сокета уже используется, и сокет не помечен, чтобы разрешить повторное использование адреса с SO_REUSEADDR. Эта ошибка обычно возникает во время выполнения функции bind , но может быть отложена до выполнения этой функции, если привязка была к частичному адресу с подстановочными знаками (с ADDR_ANY) и если во время выполнения этой функции необходимо зафиксировать определенный адрес.
WSAEINPROGRESS	Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEINVAL	Сокет не был привязан с помощью привязки.
WSAEISCONN	Сокет уже подключен.
WSAEMFILE	Больше нет доступных дескрипторов сокетов.
WSAENOBUFS	Нет свободного места в буфере.
WSAENOTSOCK	Дескриптор не является сокетом.
WSAEOPNOTSUPP	Указанный сокет не имеет типа, поддерживающего операцию прослушивания .

Чтобы принять подключения, сначала создается сокет с помощью функции сокета и привязывается к локальному адресу с помощью функции привязки . Невыполненная работа для входящих подключений указывается с параметром listen, а затем подключения принимаются с помощью функции accept . Сокеты, ориентированные на подключение, например SOCK_STREAM типа, используются с прослушивания. Сокет переводится в пассивный режим, когда входящие запросы на подключение подтверждаются и помещаются в очередь в ожидании принятия процессом.

Значение невыполненной работыSOMAXCONN — это специальная константа, которая предписывает базовому поставщику услуг, ответственному за сокеты , задать максимально допустимое значение длины очереди ожидающих подключений.

В windows Sockets 2 это максимальное значение по умолчанию имеет большое значение (обычно несколько сотен или более).

При вызове функции прослушивания в приложении Bluetooth настоятельно рекомендуется использовать гораздо меньшее значение для параметра невыполненной работы (обычно от 2 до 4), так как принимается только несколько клиентских подключений. Это сокращает системные ресурсы, выделенные для использования прослушивающим сокетом. Эта же рекомендация применяется к другим сетевым приложениям, которые ожидают только несколько клиентских подключений.

Функция прослушивания обычно используется серверами, которые могут одновременно иметь несколько запросов на подключение. Если запрос на подключение поступает и очередь заполнена, клиент получит сообщение об ошибке с указанием WSAECONNREFUSED.

Если доступных дескрипторов сокета нет, прослушивание пытается продолжить работу. Если дескрипторы станут доступны, последующий вызов для прослушивания или принятия по возможности перезаполним очередь до текущего или последнего значения, указанного для параметра невыполненной работы , и возобновит прослушивание входящих подключений.

Если функция прослушивания вызывается в уже прослушивающем сокете, она возвращает успешное выполнение без изменения значения параметра невыполненной работы . Задание для параметра невыполненной работы значения 0 в последующем вызове прослушивания прослушивающего сокета не считается правильным сбросом, особенно при наличии подключений к сокету.

Примечание При выполнении блокирующего вызова Winsock, например прослушивания, winsock может потребоваться дождаться сетевого события, прежде чем вызов сможет завершиться. В этой ситуации Winsock выполняет оповещенное ожидание, которое может быть прервано асинхронным вызовом процедуры (APC), запланированным в том же потоке. Выполнение другого блокирующего вызова Winsock внутри APC, который прервал текущий блокирующий вызов Winsock в том же потоке, приведет к неопределенному поведению, и клиенты Winsock никогда не должны пытаться его выполнять.

Пример кода

В следующем примере показано использование функции 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;
}

Пример кода

Еще один пример, в котором используется функция прослушивания, см. в разделе начало работы с помощью Winsock.

Примечания для сокетов IrDA

Файл заголовка Af_irda.h должен быть явно включен.

Совместимости

Параметр невыполненной работы ограничен (автоматически) разумным значением, определяемым базовым поставщиком услуг. Недопустимые значения заменяются ближайшим допустимым значением. Нет стандартной подготовки для получения фактического значения невыполненной работы.

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone на Windows Phone 8 и более поздних версиях.

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows на Windows 8.1, Windows Server 2012 R2 и более поздних версиях.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winsock2.h
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll