função bind (winsock2.h)

A função associar associa um endereço local a um soquete.

Sintaxe

int WSAAPI bind(
  [in] SOCKET         s,
  [in] const sockaddr *name,
  [in] int            namelen
);

Parâmetros

[in] s

Um descritor que identifica um soquete não associado.

[in] name

Um ponteiro para uma estrutura de sockaddr do endereço local para atribuir ao soquete associado.

[in] namelen

O comprimento, em bytes, do valor apontado pelo nome parâmetro.

Valor de retorno

Se nenhum erro ocorrer, associar retornará zero. Caso contrário, ele retorna SOCKET_ERROR e um código de erro específico pode ser recuperado chamando WSAGetLastError.

Observações

A função associar é necessária em um soquete não conectado antes das chamadas subsequentes para a função de escuta . Normalmente, ele é usado para associar-se a soquetes orientados à conexão (fluxo) ou sem conexão (datagram). A função associar também pode ser usada para associar a um soquete bruto (o soquete foi criado chamando a função do soquete com o tipo parâmetro definido como SOCK_RAW). A função associar também pode ser usada em um soquete não conectado antes das chamadas subsequentes para o connect, ConnectEx, WSAConnect, WSAConnectByListou funções WSAConnectByName antes de enviar operações.

Quando um soquete é criado com uma chamada para a função do 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 associar 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 nome parâmetro não é estritamente interpretado como um ponteiro para uma estrutura de de soquete . 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 tamanho namelen. Os primeiros 2 bytes neste bloco (correspondentes ao membro sa_family da estrutura do sockaddr , o membro sin_family da estrutura sockaddr_in ou o membro sin6_family da estrutura sockaddr_in6) devem conter a família de endereços 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 nome parâmetro. 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 de 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 MaxUserPort valor do registro 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 de nome de choque depois de chamar associar para aprender 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 é desencorajada para aplicativos cliente, pois há o perigo de entrar em 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 associar 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 primeiro selecionaria 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 associar com esse endereço no membro sa_data do nome parâmetro 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 associar função for concluída, um aplicativo ingressará no grupo de interesse multicast. Para obter mais informações sobre como ingressar em um grupo multicast, consulte a seção Multicast Programming. Esse soquete pode ser usado para receber pacotes multicast do grupo multicast usando ode recv, revfrom, WSARecv, funções WSARecvEx, WSARecvFromou LPFN_WSARECVMSG (WSARecvMsg).

A função associar normalmente não é necessária para enviar operações para um grupo multicast. As funções sendto,WSASendMsge WSASendTo associar implicitamente o soquete ao endereço curinga se o soquete ainda não estiver associado. A função associar é necessária antes do uso do enviar ou funções de 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 associar pode ser usada antes de enviar operações usando as funções sendto,WSASendMsgou WSASendTo se um aplicativo quisesse selecionar um endereço IP local específico em um computador local com várias interfaces 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 de cliente do IrDA nunca devem chamar a função associar antes que a se conecte função. Se o soquete IrDA tiver sido associado anteriormente a um nome de serviço usando associação, a função de conexão falhará com SOCKET_ERROR.
• Se o nome do serviço for do formulário "LSAP-SELxxx", em que xxx é um inteiro decimal no intervalo de 1 a 127, o endereço indicará 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 executar primeiro 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 no Windows 8.1, Windows Server 2012 R2 e posterior.

Exemplos

O exemplo a seguir demonstra o uso da função de associação . Para outro exemplo que usa a função associar, consulte Introdução ao 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

Consulte também

de programação multicast

opções de soquete SOL_SOCKET

SO_EXCLUSIVEADDRUSE

soquetes brutos TCP/IP

usando SO_REUSEADDR e SO_EXCLUSIVEADDRUSE

WSACancelBlockingCall

do Winsock Functions

referência Winsock

conectar

de nome de choque

escuta

setsockopt

de soquete

soquete