Função listen (winsock2.h)

A função listen coloca um soquete em um estado no qual ele está escutando uma conexão de entrada.

Sintaxe

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

Parâmetros

[in] s

Um descritor que identifica um soquete associado e não conectado.

[in] backlog

O comprimento máximo da fila de conexões pendentes. Se definido como SOMAXCONN, o provedor de serviços subjacente responsável pelo soquete s definirá a lista de pendências com um valor máximo razoável. Se definido como SOMAXCONN_HINT(N) (em que N é um número), o valor da lista de pendências será N, ajustado para estar dentro do intervalo (200, 65535). Observe que SOMAXCONN_HINT pode ser usado para definir a lista de pendências para um valor maior do que o possível com SOMAXCONN.

SOMAXCONN_HINT só tem suporte do provedor de serviços TCP/IP da Microsoft. Não há nenhuma provisão padrão para obter o valor real da lista de pendências.

Retornar valor

Se nenhum erro ocorrer, listen retornará zero. Caso contrário, um valor de SOCKET_ERROR será retornado e um código de erro específico poderá ser recuperado chamando WSAGetLastError.

Comentários

Para aceitar conexões, um soquete é criado primeiro com a função de soquete e associado a um endereço local com a função bind . Uma lista de pendências para conexões de entrada é especificada com listen e, em seguida, as conexões são aceitas com a função accept . Soquetes orientados à conexão, aqueles do tipo SOCK_STREAM , por exemplo, são usados com escuta. O soquete s é colocado no modo passivo em que as solicitações de conexão de entrada são confirmadas e enfileiradas até a aceitação pelo processo.

Um valor para a lista de pendências de SOMAXCONN é uma constante especial que instrui o provedor de serviços subjacente responsável por soquetes a definir o comprimento da fila de conexões pendentes para um valor máximo razoável.

No Windows Sockets 2, esse valor máximo usa como padrão um valor grande (normalmente várias centenas ou mais).

Ao chamar a função listen em um aplicativo Bluetooth, é altamente recomendável que um valor muito menor seja usado para o parâmetro de lista de pendências (normalmente de 2 a 4), já que apenas algumas conexões de cliente são aceitas. Isso reduz os recursos do sistema alocados para uso pelo soquete de escuta. Essa mesma recomendação se aplica a outros aplicativos de rede que esperam apenas algumas conexões de cliente.

A função de escuta normalmente é usada por servidores que podem ter mais de uma solicitação de conexão por vez. Se uma solicitação de conexão chegar e a fila estiver cheia, o cliente receberá um erro com uma indicação de WSAECONNREFUSED.

Se não houver descritores de soquete disponíveis, a escuta tentará continuar a funcionar. Se os descritores estiverem disponíveis, uma chamada posterior para escutar ou aceitar encherá a fila para o valor atual ou mais recente especificado para o parâmetro de lista de pendências , se possível, e retomará a escuta de conexões de entrada.

Se a função de escuta for chamada em um soquete de escuta, ela retornará êxito sem alterar o valor do parâmetro de lista de pendências . Definir o parâmetro de lista de pendências como 0 em uma chamada subsequente para escutar em um soquete de escuta não é considerado uma redefinição adequada, especialmente se houver conexões no soquete.

Código de exemplo

#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 exemplo

Notas para soquetes IrDA

• O arquivo de cabeçalho Af_irda.h deve ser incluído explicitamente.

Compatibilidade

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Confira também

Funções Winsock

Referência de Winsock

accept

connect

socket