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

Artigo
08/28/2023

A função LPWSPConnect estabelece uma conexão com um par, troca dados de conexão e especifica a qualidade de serviço necessária com base na especificação de fluxo fornecida.

Sintaxe

LPWSPCONNECT Lpwspconnect;

int Lpwspconnect(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [in]  LPWSABUF lpCallerData,
  [out] LPWSABUF lpCalleeData,
  [in]  LPQOS lpSQOS,
  [in]  LPQOS lpGQOS,
  [out] LPINT lpErrno
)
{...}

Parâmetros

[in] s

Descritor que identifica um soquete não conectado.

[in] name

Nome do par ao qual o soquete no sockaddr deve ser conectado.

[in] namelen

Comprimento do nome, em bytes.

[in] lpCallerData

Ponteiro para os dados do usuário que devem ser transferidos para o par durante o estabelecimento da conexão.

[out] lpCalleeData

Ponteiro para um buffer no qual todos os dados de usuário recebidos do par durante o estabelecimento da conexão podem ser copiados.

[in] lpSQOS

Ponteiro para as especificações de fluxo para soquetes s, um para cada direção.

[in] lpGQOS

Reservado.

[out] lpErrno

Ponteiro para o código de erro.

Retornar valor

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

Em um soquete de bloqueio, o valor retornado indica êxito ou falha da tentativa de conexão. Se o código de erro de retorno indicar que a tentativa de conexão falhou (ou seja, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), o cliente SPI winsock poderá chamar LPWSPConnect novamente para o mesmo soquete.

Código do Erro	Significado
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 no momento da associação, mas pode ser adiado até essa função se a associação estiver 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 (bloqueio) foi cancelada por meio de LPWSPCancelBlockingCall.
WSAEINPROGRESS	O bloqueio da chamada winsock está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEALREADY	A chamada LPWSPConnect não desbloqueada está em andamento no soquete especificado. Para preservar a compatibilidade com versões anteriores, esse erro é relatado como WSAEINVAL para aplicativos do Windows Sockets 1.1 que se vinculam a Winsock.dll ou Wsock32.dll.
WSAEADDRNOTAVAIL	O endereço remoto não é um endereço válido (por exemplo, ADDR_ANY).
WSAEAFNOSUPPORT	Os endereços na família especificada não podem ser usados com este soquete.
WSAECONNREFUSED	Uma 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.
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.
WSAENOBUFS	Nenhum espaço de buffer disponível. O soquete não pode ser conectado.
WSAENOTSOCK	O descritor não é um soquete.
WSAEOPNOTSUPP	As especificações de fluxo especificadas no lpSQOS não podem ser atendidas.
WSAEPROTONOSUPPORT	Não há suporte para o aumento de lpCallerData pelo provedor de serviços.
WSAETIMEDOUT	Uma tentativa de conexão atingiu o tempo limite sem estabelecer uma conexão.
WSAEWOULDBLOCK	O soquete é marcado como não desbloqueio e a conexão não pode ser concluída imediatamente. É possível selecionar o soquete usando a função LPWSPSelect enquanto ele está se conectando usando a função WSPSelect para selecioná-lo para gravação.
WSAEACCES	Falha ao tentar conectar o soquete de datagrama ao endereço de difusão porque o SO_BROADCAST WSPSetSockOpt não está habilitado.

Comentários

Essa função é 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 também. 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 soquetes orientados à conexão (por exemplo, digite SOCK_STREAM), uma conexão ativa é iniciada com o host especificado usando o nome (um endereço no namespace do soquete. Para obter uma descrição detalhada, consulte LPWSPBind. Quando essa chamada for concluída com êxito, o soquete estará pronto para enviar e receber dados. Se o membro de endereço da estrutura de nomes for todos zeros, LPWSPConnect retornará o erro WSAEADDRNOTAVAIL. Qualquer tentativa de reconectar uma conexão ativa falhará com o código de erro WSAEISCONN.

Para soquetes orientados à conexão e sem bloqueio, geralmente não é possível concluir a conexão imediatamente. Nesse caso, essa função retorna com o erro WSAEWOULDBLOCK , mas 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 LPWSPSelect, o êxito será relatado no conjunto writefds e a falha será relatada no conjunto exceptfds . Se o cliente usar LPWSPAsyncSelect ou LPWSPEventSelect, 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, tipo SOCK_DGRAM), a operação executada por LPWSPConnect é estabelecer um endereço de destino padrão para que o soquete possa ser usado com operações de envio e recebimento subsequentes orientadas à conexão (LPWSPSend, LPWSPRecv). Todos os datagramas recebidos de um endereço diferente do endereço de destino especificado serão descartados. Se o membro de endereço da estrutura de nomes for todos zeros, o soquete será desconectado. O endereço remoto padrão será indeterminado, portanto, as chamadas LPWSPSend e LPWSPRecv retornarão o código de erro WSAENOTCONN. No entanto, LPWSPSendTo e LPWSPRecvFrom ainda podem ser usados. O destino padrão pode ser alterado simplesmente chamando LPWSPConnect novamente, mesmo que o soquete já esteja conectado. Todos os datagramas enfileirados para recibo serão descartados se o nome for diferente do LPWSPConnect 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 o SO_BROADCAST WSPSetSockOpt habilitado. Caso contrário, LPWSPConnect 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 cliente SPI do Winsock é responsável por alocar qualquer espaço de memória apontado direta ou indiretamente por qualquer um dos parâmetros especificados.

O lpCallerData é um parâmetro de valor que contém todos os dados de usuário a serem enviados junto com a solicitação de conexão. Se lpCallerData for nulo, nenhum dado do usuário será passado para o par. O lpCalleeData é um parâmetro de resultado que fará referência a todos os dados de usuário passados do par como parte do estabelecimento da conexão. O lpCalleeData-len> contém inicialmente o comprimento do buffer alocado pelo cliente WINSock SPI e apontado por lpCalleeData-buf.> O lpCalleeData-len> 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, será quando a função LPWSPConnect retornar. Para soquetes sem bloqueio, isso ocorrerá após a notificação de FD_CONNECT. Se lpCalleeData for nulo, 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 e/ou aos aplicativos envolvidos.

No momento da conexão, um cliente Winsock SPI pode usar o parâmetro lpSQOS para substituir qualquer especificação de QoS anterior feita para o soquete por meio de LPWSPIoctl com o opcode SIO_SET_QOS.

O lpSQOS especifica as especificações de fluxo para soquetes s, uma para cada direção, seguidas 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 honrar a solicitação de QoS, um erro será retornado conforme indicado abaixo. 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 fornecido, os membros buf e len de lpSQOS-ProviderSpecific>deverão ser definidos como nulo e zero, respectivamente. Um valor nulo para lpSQOS indica que nenhum aplicativo forneceu qualidade de serviço.

Observação

Quando os soquetes conectados quebram (ou seja, ficam fechados por qualquer motivo), eles devem ser descartados e recriados. É mais seguro supor que quando as coisas dão errado por qualquer motivo em um soquete conectado, o cliente SPI winsock deve descartar e recriar os soquetes necessários para retornar a um ponto estável.

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