Função WSAConnect (winsock2.h)

Artigo
08/27/2023

A função WSAConnect estabelece uma conexão com outro aplicativo de soquete, troca dados de conexão e especifica a qualidade de serviço necessária com base na estrutura FLOWSPEC especificada.

Sintaxe

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

Parâmetros

[in] s

Um descritor que identifica um soquete não conectado.

[in] name

Um ponteiro para uma estrutura sockaddr que especifica o endereço ao qual se conectar. Para IPv4, o sockaddr contém AF_INET para a família de endereços, o endereço IPv4 de destino e a porta de destino. Para IPv6, a estrutura sockaddr contém AF_INET6 para a família de endereços, o endereço IPv6 de destino, a porta de destino e pode conter informações adicionais de fluxo e ID de escopo.

[in] namelen

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

[in] lpCallerData

Um ponteiro para os dados do usuário que devem ser transferidos para o outro soquete durante o estabelecimento da conexão. Consulte Observações.

[out] lpCalleeData

Um ponteiro para os dados do usuário que devem ser transferidos de volta do outro soquete durante o estabelecimento da conexão. Consulte Observações.

[in] lpSQOS

Um ponteiro para as estruturas FLOWSPEC para soquetes s, um para cada direção.

[in] lpGQOS

Reservado para uso futuro com grupos de soquetes. Um ponteiro para as estruturas FLOWSPEC para o grupo de soquetes (se aplicável). Esse parâmetro deve ser NULL.

Retornar valor

Se nenhum erro ocorrer, o WSAConnect retornará zero. Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico poderá ser recuperado chamando WSAGetLastError. Em um soquete de bloqueio, o valor retornado indica êxito ou falha da tentativa de conexão.

Com um soquete sem bloqueio, a tentativa de conexão não pode ser concluída imediatamente. Nesse caso, o WSAConnect retornará SOCKET_ERROR e WSAGetLastError retornará WSAEWOULDBLOCK; o aplicativo poderia, portanto:

Use select para determinar a conclusão da solicitação de conexão verificando se o soquete é gravável.
Se o aplicativo estiver usando WSAAsyncSelect para indicar interesse em eventos de conexão, o aplicativo receberá uma notificação de FD_CONNECT quando a operação de conexão for concluída (bem-sucedida ou não).
Se o aplicativo estiver usando WSAEventSelect para indicar interesse em eventos de conexão, o objeto de evento associado será sinalizado quando a operação de conexão for concluída (bem-sucedida ou não).

Para um soquete sem bloqueio, até que a tentativa de conexão conclua todas as chamadas subsequentes para WSAConnect no mesmo soquete falhará com o código de erro WSAEALREADY.

Se o código de erro de retorno indicar que a tentativa de conexão falhou (ou seja, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), o aplicativo poderá chamar WSAConnect novamente para o mesmo soquete.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSAEADDRINUSE	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 associação, mas pode ser adiado até essa função se a função de associação operar em um endereço parcialmente curinga (envolvendo ADDR_ANY) e se um endereço específico precisar ser "confirmado" no momento dessa função.
WSAEINTR	A chamada do Windows Socket 1.1 (bloqueio) foi cancelada por meio de WSACancelBlockingCall.
WSAEINPROGRESS	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.
WSAEALREADY	Uma chamada de conexão sem bloqueio ou WSAConnect está em andamento no soquete especificado.
WSAEADDRNOTAVAIL	O endereço remoto não é um endereço válido (como ADDR_ANY).
WSAEAFNOSUPPORT	Os endereços na família especificada não podem ser usados com este soquete.
WSAECONNREFUSED	A tentativa de conexão foi rejeitada.
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 comprimento do buffer para lpCalleeData, lpSQOS e lpGQOS é muito pequeno ou o comprimento do buffer para lpCallerData é muito grande.
WSAEINVAL	O parâmetro s é um soquete de escuta ou o endereço de destino especificado não é consistente com o do grupo restrito ao qual o soquete pertence ou o parâmetro lpGQOS não é NULL.
WSAEISCONN	O soquete já está conectado (somente soquetes orientados à conexão).
WSAENETUNREACH	A rede não pode ser alcançada através deste host neste momento.
WSAEHOSTUNREACH	Uma operação de soquete foi tentada em um host inacessível.
WSAENOBUFS	Nenhum espaço de buffer disponível. O soquete não pode ser conectado.
WSAENOTSOCK	O descritor não é um soquete.
WSAEOPNOTSUPP	As estruturas FLOWSPEC especificadas em lpSQOS e lpGQOS não podem ser atendidas.
WSAEPROTONOSUPPORT	O parâmetro lpCallerData não tem suporte do provedor de serviços.
WSAETIMEDOUT	Tente se conectar com o tempo limite sem estabelecer uma conexão.
WSAEWOULDBLOCK	O soquete é marcado como de não desbloqueio e a conexão não pode ser concluída imediatamente.
WSAEACCES	Falha ao tentar conectar o soquete de datagrama ao endereço de difusão porque setsockopt SO_BROADCAST não está habilitado.

Comentários

A função WSAConnect é usada para criar uma conexão com o destino especificado e para executar várias outras operações auxiliares que ocorrem no momento da conexão. Se o soquete, s, for desassociado, os valores exclusivos serão atribuídos à associação local pelo sistema e o soquete será marcado como associado.

Para aplicativos direcionados ao Windows Vista e posteriores, considere usar a função WSAConnectByList ou WSAConnectByName que simplifica muito o design do aplicativo cliente.

Para soquetes orientados à conexão (por exemplo, digite SOCK_STREAM), uma conexão ativa é iniciada com o host estrangeiro usando o nome (um endereço no namespace do soquete; para obter uma descrição detalhada, consulte bind). Quando essa chamada for concluída com êxito, o soquete estará pronto para enviar/receber dados. Se o parâmetro address da estrutura de nome for todos zeros, o WSAConnect retornará o erro WSAEADDRNOTAVAIL. Qualquer tentativa de reconectar uma conexão ativa falhará com o código de erro WSAEISCONN.

Nota Se um soquete for aberto, uma chamada setsockopt será feita e, em seguida, uma chamada sendto será feita, o Windows Sockets executará uma chamada de função de associação implícita.

Para soquetes orientados a conexão e sem bloqueio, geralmente não é possível concluir a conexão imediatamente. Nesses casos, essa função retorna o erro WSAEWOULDBLOCK. No entanto, a operação continua. Quando o resultado de êxito ou falha se torna conhecido, ele pode ser relatado de várias maneiras, dependendo de como o cliente se registra para notificação. Se o cliente usar select, o êxito será relatado no conjunto writefds e a falha será relatada no conjunto exceptfds . Se o cliente usar WSAAsyncSelect ou WSAEventSelect, a notificação será anunciada com FD_CONNECT e o código de erro associado ao FD_CONNECT indicará êxito ou um motivo específico para falha.

Para um soquete sem conexão (por exemplo, digite SOCK_DGRAM), a operação executada pelo WSAConnect é apenas estabelecer um endereço de destino padrão para que o soquete possa ser usado em operações de envio e recebimento subsequentes orientadas à conexão (send, WSASend, recv e WSARecv). Todos os datagramas recebidos de um endereço diferente do endereço de destino especificado serão descartados. Se toda a estrutura de nome for todos zeros (não apenas o parâmetro de endereço da estrutura de nome), o soquete será desconectado. Em seguida, o endereço remoto padrão será indeterminado, portanto, as chamadas send, WSASend, recv e WSARecv retornarão o código de erro WSAENOTCONN. No entanto, sendto, WSASendTo, recvfrom e WSARecvFrom ainda podem ser usados. O destino padrão pode ser alterado simplesmente chamando WSAConnect novamente, mesmo que o soquete já esteja conectado. Todos os datagramas enfileirados para recibo serão descartados se o nome for diferente do WSAConnect anterior.

Para soquetes sem conexão, o nome pode indicar qualquer endereço válido, incluindo um endereço de difusão. No entanto, para se conectar a um endereço de difusão, um soquete deve ter setsockopt SO_BROADCAST habilitado. Caso contrário, o WSAConnect falhará com o código de erro WSAEACCES.

Em soquetes sem conexão, a troca de dados de usuário para usuário não é possível e os parâmetros correspondentes serão ignorados silenciosamente.

O aplicativo é responsável por alocar qualquer espaço de memória apontado direta ou indiretamente por qualquer um dos parâmetros especificados por ele.

O parâmetro lpCallerData contém um ponteiro para todos os dados de usuário que devem ser enviados junto com a solicitação de conexão (chamada de dados de conexão). Esses são dados adicionais, não no fluxo de dados de rede normal, que são enviados com solicitações de rede para estabelecer uma conexão. Essa opção é usada por protocolos herdados, como DECNet, OSI TP4 e outros.

Nota Não há suporte para conectar dados pelo protocolo TCP/IP no Windows. Os dados de conexão têm suporte apenas no ATM (RAWWAN) em um soquete bruto.

Se lpCallerData for NULL, nenhum dado de usuário será passado para o par. O lpCalleeData é um parâmetro de resultado que conterá todos os dados de usuário passados do outro soquete como parte do estabelecimento de conexão em uma estrutura WSABUF . O membro len da estrutura WSABUF apontado pelo parâmetro lpCalleeData inicialmente contém o comprimento do buffer alocado pelo aplicativo para o membro buf da estrutura WSABUF . O membro len da estrutura WSABUF apontada pelo parâmetro lpCalleeData será definido como zero se nenhum dado do usuário tiver sido passado de volta. As informações de lpCalleeData serão válidas quando a operação de conexão for concluída. Para bloqueio de soquetes, a operação de conexão é concluída quando a função WSAConnect retorna. Para soquetes sem bloqueio, a conclusão será após o FD_CONNECT notificação. Se lpCalleeData for NULL, nenhum dado do usuário será passado de volta. O formato exato dos dados do usuário é específico para a família de endereços à qual o soquete pertence.

No momento da conexão, um aplicativo pode usar o parâmetro lpSQOS e lpGQOS para substituir qualquer especificação de qualidade de serviço anterior feita para o soquete por meio de WSAIoctl com o SIO_SET_QOS ou SIO_SET_GROUP_QOS opcode.

O parâmetro lpSQOS especifica as estruturas FLOWSPEC para soquetes s, uma para cada direção, seguida por quaisquer parâmetros adicionais específicos do provedor. Se o provedor de transporte associado em geral ou o tipo específico de soquete em particular não puder respeitar a qualidade da solicitação de serviço, um erro será retornado conforme indicado a seguir. Os valores de especificação de fluxo de envio ou recebimento serão ignorados, respectivamente, para quaisquer soquetes unidirecionais. Se nenhum parâmetro específico do provedor for especificado, os membros buf e len da estrutura WSABUF apontada pelo parâmetro lpCalleeData deverão ser definidos como NULL e zero, respectivamente. Um valor NULL para o parâmetro lpSQOS indica nenhuma qualidade de serviço fornecida pelo aplicativo.

Reservado para uso futuro com grupos de soquetes lpGQOS especifica as estruturas FLOWSPEC para o grupo de soquetes (se aplicável), uma para cada direção, seguida por quaisquer parâmetros adicionais específicos do provedor. Se nenhum parâmetro específico do provedor for especificado, os membros buf e len da estrutura WSABUF apontada pelo parâmetro lpCalleeData deverão ser definidos como NULL e zero, respectivamente. Um valor NULL para lpGQOS indica nenhuma qualidade de serviço de grupo fornecida pelo aplicativo. Esse parâmetro será ignorado se s não for o criador do grupo de soquetes.

Quando soquetes conectados ficam fechados por qualquer motivo, eles devem ser descartados e recriados. É mais seguro supor que, quando as coisas derem errado por qualquer motivo em um soquete conectado, o aplicativo deve descartar e recriar os soquetes necessários para retornar a um ponto estável.

Nota Ao emitir uma chamada winsock de bloqueio, como WSAConnect, o Winsock pode precisar aguardar um evento de rede antes que a chamada possa ser concluída. O Winsock executa uma espera alertável nessa situação, que pode ser interrompida por uma APC (chamada de procedimento assíncrono) agendada no mesmo thread. A emissão de outra chamada winsock de bloqueio dentro de um APC que interrompeu uma chamada Winsock de bloqueio contínuo no mesmo thread levará a um comportamento indefinido e nunca deve ser tentada por clientes Winsock.

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