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.
| Código do erro | Significado |
|---|---|
| Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função. | |
| O subsistema de rede falhou. | |
| O endereço local do soquete já está em uso e o soquete não foi marcado para permitir a reutilização de endereço com SO_REUSEADDR. Esse erro geralmente ocorre durante a execução da função de associação, mas pode ser adiado até essa função se a associação estiver em um endereço parcialmente curinga (envolvendo ADDR_ANY) e se um endereço específico precisar ser confirmado no momento dessa função. | |
| Uma chamada de bloqueio do Windows Sockets 1.1 está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada. | |
| O soquete não foi associado à associação. | |
| O soquete já está conectado. | |
| Nenhum descritor de soquete disponível. | |
| Nenhum espaço de buffer disponível. | |
| O descritor não é um soquete. | |
| O soquete referenciado não é de um tipo que dá suporte à operação de escuta . |
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
O exemplo a seguir demonstra o uso da função 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;
}
Código de exemplo
Para obter outro exemplo que usa a função listen, consulte Introdução With Winsock.Notas para soquetes IrDA
- O arquivo de cabeçalho Af_irda.h deve ser incluído explicitamente.
Compatibilidade
O parâmetro de lista de pendências é limitado (silenciosamente) a um valor razoável, conforme determinado pelo provedor de serviços subjacente. Valores ilegais são substituídos pelo valor legal mais próximo. Não há nenhuma provisão padrão para descobrir o valor real da lista de pendências.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
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |