Función listen (winsock2.h)

Artículo
03/08/2023

La función de escucha coloca un socket en un estado en el que escucha una conexión entrante.

Sintaxis

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

Parámetros

[in] s

Descriptor que identifica un socket enlazado y no conectado.

[in] backlog

Longitud máxima de la cola de conexiones pendientes. Si se establece en SOMAXCONN, el proveedor de servicios subyacente responsable de sockets establecerá el trabajo pendiente en un valor máximo razonable. Si se establece en SOMAXCONN_HINT(N) (donde N es un número), el valor del trabajo pendiente será N, ajustado para estar dentro del intervalo (200, 65535). Tenga en cuenta que SOMAXCONN_HINT se puede usar para establecer el trabajo pendiente en un valor mayor que posible con SOMAXCONN.

SOMAXCONN_HINT solo es compatible con el proveedor de servicios TCP/IP de Microsoft. No hay ninguna aprovisionamiento estándar para obtener el valor real del trabajo pendiente.

Valor devuelto

Si no se produce ningún error, la escucha devuelve cero. De lo contrario, se devuelve un valor de SOCKET_ERROR y se puede recuperar un código de error específico mediante una llamada a WSAGetLastError.

Código de error	Significado
WSANOTINITIALISED	Debe producirse una llamada WSAStartup correcta antes de usar esta función.
WSAENETDOWN	Error en el subsistema de red.
WSAEADDRINUSE	La dirección local del socket ya está en uso y el socket no se marcó para permitir la reutilización de direcciones con SO_REUSEADDR. Este error suele producirse durante la ejecución de la función de enlace , pero podría retrasarse hasta esta función si el enlace era a una dirección con caracteres comodín parcial (que implica ADDR_ANY) y si es necesario confirmar una dirección específica en el momento de esta función.
WSAEINPROGRESS	Una llamada de Bloqueo de Windows Sockets 1.1 está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada.
WSAEINVAL	El socket no se ha enlazado con bind.
WSAEISCONN	El socket ya está conectado.
WSAEMFILE	No hay más descriptores de socket disponibles.
WSAENOBUFS	No hay espacio disponible en el búfer.
WSAENOTSOCK	El descriptor no es un socket.
WSAEOPNOTSUPP	El socket al que se hace referencia no es de un tipo que admita la operación de escucha .

Comentarios

Para aceptar conexiones, primero se crea un socket con la función socket y se enlaza a una dirección local con la función bind . Se especifica un trabajo pendiente para las conexiones entrantes con escucha y, a continuación, las conexiones se aceptan con la función accept . Los sockets orientados a la conexión, los de tipo SOCK_STREAM , por ejemplo, se usan con escucha. El socket s se coloca en modo pasivo donde el proceso reconoce y pone en cola las solicitudes de conexión entrantes pendientes de aceptación.

Un valor para el trabajo pendiente de SOMAXCONN es una constante especial que indica al proveedor de servicios subyacente responsable de sockets que establezca la longitud de la cola de conexiones pendientes en un valor razonable máximo.

En Windows Sockets 2, este valor máximo tiene como valor predeterminado un valor grande (normalmente varios cientos o más).

Al llamar a la función de escucha en una aplicación Bluetooth, se recomienda encarecidamente usar un valor mucho menor para el parámetro de trabajo pendiente (normalmente de 2 a 4), ya que solo se aceptan algunas conexiones de cliente. Esto reduce los recursos del sistema asignados para su uso por el socket de escucha. Esta misma recomendación se aplica a otras aplicaciones de red que esperan solo algunas conexiones de cliente.

Normalmente, los servidores que pueden tener más de una solicitud de conexión a la vez usan la función de escucha . Si llega una solicitud de conexión y la cola está llena, el cliente recibirá un error con una indicación de WSAECONNREFUSED.

Si no hay ningún descriptor de socket disponible, escuche los intentos de continuar funcionando. Si los descriptores están disponibles, una llamada posterior para escuchar o aceptar rellenará la cola al valor actual o más reciente especificado para el parámetro de trabajo pendiente , si es posible, y reanudará la escucha de las conexiones entrantes.

Si se llama a la función de escucha en un socket que ya está escuchando, devolverá éxito sin cambiar el valor del parámetro de trabajo pendiente . Establecer el parámetro de trabajo pendiente en 0 en una llamada posterior para escuchar en un socket de escucha no se considera un restablecimiento adecuado, especialmente si hay conexiones en el socket.

Nota Al emitir una llamada de Winsock de bloqueo como escucha, Puede que Winsock tenga que esperar un evento de red antes de que se pueda completar la llamada. Winsock realiza una espera alertable en esta situación, que se puede interrumpir mediante una llamada de procedimiento asincrónica (APC) programada en el mismo subproceso. La emisión de otra llamada winsock de bloqueo dentro de un APC que interrumpió una llamada de Winsock de bloqueo en curso en el mismo subproceso provocará un comportamiento indefinido y los clientes winsock nunca deben intentarlo.

Código de ejemplo

En el ejemplo siguiente se muestra el uso de la función de escucha .

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

Código de ejemplo

Para obtener otro ejemplo que usa la función de escucha, vea Introducción With Winsock.

Notas para sockets IrDA

El archivo de encabezado Af_irda.h debe incluirse explícitamente.

Compatibilidad

El parámetro de trabajo pendiente está limitado (silenciosamente) a un valor razonable determinado por el proveedor de servicios subyacente. Los valores no válidos se reemplazan por el valor legal más cercano. No hay ningún aprovisionamiento estándar para averiguar el valor real del trabajo pendiente.

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1, Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winsock2.h
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll