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.

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

Confira também

Programação multicast

Opções de soquete SOL_SOCKET

SO_EXCLUSIVEADDRUSE

Soquetes brutos TCP/IP

Usando SO_REUSEADDR e SO_EXCLUSIVEADDRUSE

WSACancelBlockingCall

Funções Winsock

Referência de Winsock

connect

Getsockname

listen

Setsockopt

Sockaddr

socket