Função bind (winsock.h)
A função bind associa um endereço local a um soquete.
Sintaxe
int bind(
[in] SOCKET s,
const sockaddr *addr,
[in] int namelen
);
Parâmetros
[in] s
Um descritor que identifica um soquete não associado.
addr
Um ponteiro para uma estrutura sockaddr do endereço local a ser atribuída ao soquete associado.
[in] namelen
O comprimento, em bytes, do valor apontado por addr.
Retornar valor
Se nenhum erro ocorrer, bind retornará zero. Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico poderá ser recuperado chamando WSAGetLastError.
| Código do erro | Significado |
|---|---|
|
Nota Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
|
|
| O subsistema de rede falhou. | |
|
Houve uma tentativa de acesso não autorizado a um soquete conforme as permissões de acesso.
Esse erro será retornado se a tentativa de nn de associar um soquete de datagrama ao endereço de difusão falhar porque a opção setsockopt SO_BROADCAST não está habilitada. |
|
|
Normalmente, apenas um tipo de uso de cada endereço de soquete (endereço de rede/protocolo/porta) é permitido.
Esse erro será retornado se um processo no computador já estiver associado ao mesmo endereço totalmente qualificado e o soquete não tiver sido marcado para permitir a reutilização de endereço com SO_REUSEADDR. Por exemplo, o endereço IP e a porta especificados no parâmetro name já estão associados a outro soquete que está sendo usado por outro aplicativo. Para obter mais informações, consulte a opção de soquete SO_REUSEADDR na referência opções de soquete SOL_SOCKET, Usando SO_REUSEADDR e SO_EXCLUSIVEADDRUSE e SO_EXCLUSIVEADDRUSE. |
|
|
O endereço solicitado não é válido no respectivo contexto.
Esse erro será retornado se o endereço especificado apontado pelo parâmetro name não for um endereço IP local válido neste computador. |
|
|
O sistema detectou um endereço de ponteiro inválido ao tentar usar um argumento de ponteiro em uma chamada.
Esse erro será retornado se o parâmetro name for NULL, o nome ou o parâmetro namelen não for uma parte válida do espaço de endereço do usuário, o parâmetro namelen for muito pequeno, o parâmetro name contiver um formato de endereço incorreto para a família de endereços associada ou os dois primeiros bytes do bloco de memória especificado pelo nome não corresponderem à família de endereços associada aos descritores de soquete. |
|
| 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. | |
|
Foi fornecido um argumento inválido.
Esse erro é retornado do soquete s que já está associado a um endereço. |
|
| Normalmente, o WSAENOBUFS é uma indicação de que não há portas efêmeras suficientes para alocar para a associação. | |
|
Houve uma tentativa de executar uma operação em algo que não é um soquete.
Esse erro será retornado se o descritor no parâmetro s não for um soquete. |
Comentários
A função bind é necessária em um soquete não conectado antes de chamadas subsequentes para a função de escuta . Normalmente, ele é usado para associar a soquetes orientados a conexão (fluxo) ou sem conexão (datagram). A função bind também pode ser usada para associar a um soquete bruto (o soquete foi criado chamando a função de soquete com o parâmetro de tipo definido como SOCK_RAW). A função bind também pode ser usada em um soquete não conectado antes de chamadas subsequentes para as funções connect, ConnectEx, WSAConnect, WSAConnectByList ou WSAConnectByName antes de enviar operações.
Quando um soquete é criado com uma chamada para a função de soquete , ele existe em um namespace (família de endereços), mas não tem nenhum nome atribuído a ele. Use a função bind para estabelecer a associação local do soquete atribuindo um nome local a um soquete sem nome.
Um nome consiste em três partes ao usar a família de endereços da Internet:
- A família de endereços.
- Um endereço de host.
- Um número de porta que identifica o aplicativo.
No Windows Sockets 2, o parâmetro name não é estritamente interpretado como um ponteiro para uma estrutura sockaddr . Ele é convertido dessa forma para compatibilidade do Windows Sockets 1.1. Os provedores de serviços são livres para considerá-lo como um ponteiro para um bloco de memória de namelen de tamanho. Os primeiros 2 bytes nesse bloco (correspondentes ao membro sa_family da estrutura sockaddr , ao membro sin_family da estrutura sockaddr_in ou ao membro sin6_family da estrutura sockaddr_in6 ) devem conter a família de endereços que foi usada para criar o soquete. Caso contrário, ocorrerá um erro WSAEFAULT.
Se um aplicativo não se importar com o endereço local atribuído, especifique o valor constante INADDR_ANY para um endereço local IPv4 ou o valor constante in6addr_any para um endereço local IPv6 no membro sa_data do parâmetro name . Isso permite que o provedor de serviços subjacente use qualquer endereço de rede apropriado, potencialmente simplificando a programação de aplicativos na presença de hosts multihomed (ou seja, hosts com mais de um adaptador de rede e endereço).
Para TCP/IP, se a porta for especificada como zero, o provedor de serviços atribuirá uma porta exclusiva ao aplicativo do intervalo de portas do cliente dinâmico. No Windows Vista e posterior, o intervalo de portas do cliente dinâmico é um valor entre 49152 e 65535. Essa é uma alteração do Windows Server 2003 e anterior em que o intervalo de portas do cliente dinâmico era um valor entre 1025 e 5000. O valor máximo do intervalo de portas dinâmicas do cliente pode ser alterado definindo um valor na seguinte chave do Registro:
HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
O valor do registro MaxUserPort define o valor a ser usado para o valor máximo do intervalo de portas do cliente dinâmico. Você deve reiniciar o computador para que essa configuração entre em vigor.
No Windows Vista e posterior, o intervalo de portas do cliente dinâmico pode ser exibido e alterado usando comandos netsh . O intervalo de portas do cliente dinâmico pode ser definido de forma diferente para UDP e TCP e também para IPv4 e IPv6. Para obter mais informações, consulte KB 929851.
O aplicativo pode usar getsockname depois de chamar bind para saber o endereço e a porta que foi atribuída ao soquete. Se o endereço da Internet for igual a INADDR_ANY ou in6addr_any, getsockname não poderá necessariamente fornecer o endereço até que o soquete esteja conectado, pois vários endereços poderão ser válidos se o host for multihomed. A associação a um número de porta específico diferente da porta 0 não é desencorajada para aplicativos cliente, pois há um perigo de conflito com outro soquete que já usa esse número de porta no computador local.
Para operações multicast, o método preferencial é chamar a função de associação para associar um soquete a um endereço IP local e, em seguida, ingressar no grupo multicast. Embora essa ordem de operações não seja obrigatória, é altamente recomendável. Portanto, um aplicativo multicast selecionaria primeiro um endereço IPv4 ou IPv6 no computador local, o endereço IPv4 curinga (INADDR_ANY) ou o endereço IPv6 curinga (in6addr_any). Em seguida, o aplicativo multicast chamaria a função de associação com esse endereço no no membro sa_data do parâmetro name para associar o endereço IP local ao soquete. Se um endereço curinga tiver sido especificado, o Windows selecionará o endereço IP local a ser usado. Depois que a função de associação for concluída, um aplicativo ingressará no grupo multicast de interesse. Para obter mais informações sobre como ingressar em um grupo multicast, consulte a seção sobre Programação multicast. Esse soquete pode ser usado para receber pacotes multicast do grupo multicast usando as funções recv, recvfrom, WSARecv, WSARecvEx, WSARecvFrom ou LPFN_WSARECVMSG (WSARecvMsg ).
Normalmente, a função de associação não é necessária para enviar operações para um grupo multicast. As funções sendto, WSASendMsg e WSASendTo associam implicitamente o soquete ao endereço curinga se o soquete ainda não estiver associado. A função bind é necessária antes do uso das funções send ou WSASend que não executam uma associação implícita e são permitidas somente em soquetes conectados, o que significa que o soquete já deve ter sido associado para que ele seja conectado. A função bind pode ser usada antes de enviar operações usando as funções sendto, WSASendMsg ou WSASendTo se um aplicativo quiser selecionar um endereço IP local específico em um computador local com vários adaptadores de rede e endereços IP locais. Caso contrário, uma associação implícita ao endereço curinga usando as funções sendto, WSASendMsg ou WSASendTo pode resultar em um endereço IP local diferente sendo usado para operações de envio.
Notas para soquetes IrDA
- O arquivo de cabeçalho Af_irda.h deve ser incluído explicitamente.
- Os nomes locais não são expostos no IrDA. Portanto, os soquetes do cliente IrDA nunca devem chamar a função de associação antes da função de conexão . Se o soquete IrDA tiver sido associado anteriormente a um nome de serviço usando bind, a função connect falhará com SOCKET_ERROR.
- Se o nome do serviço for do formato "LSAP-SELxxx", em que xxx é um inteiro decimal no intervalo de 1 a 127, o endereço indica um LSAP-SEL xxx específico em vez de um nome de serviço. Nomes de serviço como esses permitem que aplicativos de servidor aceitem conexões de entrada direcionadas a um LSAP-SEL específico, sem primeiro executar uma consulta de nome de serviço ISA para obter o LSAP-SEL associado. Um exemplo desse tipo de nome de serviço é um dispositivo não Windows que não dá suporte à IAS.
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.
Exemplos
O exemplo a seguir demonstra o uso da função bind . Para obter outro exemplo que usa a função bind, consulte Introdução With Winsock.
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
int main()
{
// Declare some variables
WSADATA wsaData;
int iResult = 0; // used to return function results
// the listening socket to be created
SOCKET ListenSocket = INVALID_SOCKET;
// The socket address to be passed to bind
sockaddr_in service;
//----------------------
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != NO_ERROR) {
wprintf(L"Error at WSAStartup()\n");
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: %u\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);
//----------------------
// Bind the socket.
iResult = bind(ListenSocket, (SOCKADDR *) &service, sizeof (service));
if (iResult == SOCKET_ERROR) {
wprintf(L"bind failed with error %u\n", WSAGetLastError());
closesocket(ListenSocket);
WSACleanup();
return 1;
}
else
wprintf(L"bind returned success\n");
WSACleanup();
return 0;
}
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 | winsock.h (inclua Winsock2.h) |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de