Função de retorno de chamada LPWSPBIND (ws2spi.h)

Artigo
08/28/2023

A função LPWSPBind associa um endereço local (ou seja, nome) a um soquete.

Sintaxe

LPWSPBIND Lpwspbind;

int Lpwspbind(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [out] LPINT lpErrno
)
{...}

Parâmetros

[in] s

Um descritor que identifica um soquete não associado.

[in] name

O endereço a ser atribuído ao soquete, na forma de uma estrutura sockaddr .

Exceto para o membro sa_family , o conteúdo sockaddr é expresso na ordem de bytes de rede. No Windows Sockets 2, o parâmetro name não é estritamente interpretado como um ponteiro para uma estrutura sockaddr . É convertido desta maneira para compatibilidade winsock. A estrutura real é interpretada de forma diferente no contexto de diferentes famílias de endereços. Os únicos requisitos são que o primeiro u_short seja a família de endereços e o tamanho total do buffer de memória, em bytes, seja namelen.

[in] namelen

O comprimento, em bytes, da estrutura apontada pelo parâmetro name .

[out] lpErrno

Um ponteiro para o código de erro.

Retornar valor

Se nenhum erro ocorrer, LPWSPBind retornará zero. Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico estará disponível no lpErrno.

Código do Erro	Significado
WSAENETDOWN	O subsistema de rede falhou.
WSAEADDRINUSE	Alguns processos no computador local já associaram ao mesmo endereço totalmente qualificado (por exemplo, endereço IP e porta no caso AF_INET e o soquete não foi marcado para permitir a reutilização de endereço com SO_REUSEADDR. (Consulte a opção de soquete SO_REUSEADDR em LPWSPSetSockOpt.)
WSAEADDRNOTAVAIL	O endereço especificado não é um endereço válido para este computador.
WSAEFAULT	O nome ou o parâmetro namelen não é uma parte válida do espaço de endereço do usuário, o parâmetro namelen é muito pequeno, o parâmetro name contém o 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 correspondem à família de endereços associada aos descritores de soquete.
WSAEINPROGRESS	A função é invocada quando um retorno de chamada está em andamento.
WSAEINVAL	O soquete já está associado a um endereço.
WSAENOBUFS	Não há buffers suficientes disponíveis, há muitas conexões.
WSAENOTSOCK	O descritor não é um soquete.

Comentários

A função LPWSPBind é usada em um soquete sem conexão ou orientado à conexão, antes das chamadas subsequentes para as funções LPWSPConnect ou LPWSPListen . Quando um soquete é criado com LPWSPSocket, ele existe em um namespace (família de endereços), mas não tem nenhum nome ou endereço local atribuído. A função LPWSPBind estabelece a associação local do soquete atribuindo um nome local a um soquete sem nome.

Por exemplo, na família de endereços da Internet, um nome consiste em três partes: a família de endereços, um endereço de host e um número de porta que identifica o cliente WINSock SPI. No Windows Sockets 2, o parâmetro name não é estritamente interpretado como um ponteiro para uma estrutura sockaddr . 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 dois primeiros bytes neste bloco (correspondentes a sa_family na declaração sockaddr ) devem conter a família de endereços que foi usada para criar o soquete. Caso contrário, o erro WSAEFAULT será indicado.

Se um cliente SPI do Windows Sockets 2 não se importar com o endereço local atribuído a ele, ele especificará o valor constante de manifesto ADDR_ANY para o membro sa_data do parâmetro name . Isso instrui o provedor de serviços a usar qualquer endereço de rede apropriado. Para TCP/IP, se a porta for especificada como zero, o provedor de serviços atribuirá uma porta exclusiva ao cliente WINSock SPI com um valor entre 1024 e 5000. O cliente SPI pode usar LPWSPGetSockName após LPWSPBind para aprender o endereço e a porta que foi atribuída a ele. No entanto, observe que, se o endereço da Internet for igual a INADDR_ANY, LPWSPGetSockOpt não será necessariamente capaz de fornecer o endereço até que o soquete esteja conectado, pois vários endereços podem ser válidos se o host for multihomed.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ws2spi.h