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

Artigo
08/28/2023

A função WSPJoinLeaf une um nó folha em uma sessão de vários pontos, troca dados de conexão e especifica a qualidade necessária do serviço com base nas especificações de fluxo fornecidas.

Sintaxe

LPWSPJOINLEAF Lpwspjoinleaf;

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

Parâmetros

[in] s

Descritor que identifica um soquete de vários pontos.

[in] name

Nome do par ao qual o soquete na estrutura sockaddr deve ser unido.

[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 de sessão de vários pontos.

[out] lpCalleeData

Ponteiro para os dados do usuário que devem ser transferidos do par durante o estabelecimento da sessão de vários pontos.

[in] lpSQOS

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

[in] lpGQOS

Reservado.

[in] dwFlags

Sinalizadores para indicar que o soquete está agindo como um remetente, receptor ou ambos.

[out] lpErrno

Ponteiro para o código de erro.

Valor retornado

Se nenhum erro ocorrer, WSPJoinLeaf retornará um valor do tipo SOCKET que é um descritor para o soquete multiponto recém-criado. Caso contrário, um valor de INVALID_SOCKET é retornado e um código de erro específico está disponível no lpErrno.

Em um soquete de bloqueio, o valor retornado indica êxito ou falha da operação de junção.

Com um soquete não desbloqueado, o início bem-sucedido de uma operação de junção é indicado por um valor retornado de um descritor de soquete válido. Posteriormente, uma indicação de FD_CONNECT é fornecida quando a operação de junção é concluída com êxito ou de outra forma. O código de erro associado ao FD_CONNECT indica o êxito ou a falha do WSPJoinLeaf.

Além disso, até que a tentativa de junção de sessão de vários pontos conclua todas as chamadas subsequentes para WSPJoinLeaf no mesmo soquete falhará com o código de erro WSAEALREADY. Depois que o WSPJoinLeaf for concluído com êxito, uma tentativa subsequente geralmente falhará com o código de erro WSAEISCONN. Uma exceção à regra WSAEISCONN ocorre para um soquete c_root que permite junções iniciadas por raiz. Nesse caso, outra junção pode ser iniciada após a conclusão de um WSPJoinLeaf anterior.

Se o código de erro de retorno indicar que a tentativa de junção de sessão de vários pontos falhou (ou seja, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) o cliente SPI do Windows Sockets poderá chamar WSPJoinLeaf 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 o bind for para um endereço parcialmente cartão (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 WSPCancelBlockingCall.
WSAEINPROGRESS	O bloqueio da chamada do Windows Sockets está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEALREADY	A chamada WSPJoinLeaf não desbloqueada está em andamento no soquete especificado.
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	A tentativa de ingressar foi rejeitada com força.
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.
WSAEISCONN	Socket já é membro da sessão de vários pontos.
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 unido.
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 ingressar atingiu o tempo limite sem estabelecer uma sessão de vários pontos.

Comentários

Essa função é usada para unir um nó folha a uma sessão de vários pontos e para executar várias outras operações auxiliares que ocorrem no momento da junção da sessão também. Se o soquete, s, for desvinculado, os valores exclusivos serão atribuídos à associação local pelo sistema e o soquete será marcado como associado.

WSPJoinLeaf tem os mesmos parâmetros e semântica que LPWSPConnect , exceto que ele retorna um descritor de soquete (como em LPWSPAccept) e tem um parâmetro dwFlags adicional. Somente soquetes de vários pontos criados usando LPWSPSocket com o conjunto de sinalizadores de vários pontos apropriado podem ser usados para parâmetros de entrada nessa função. Se o soquete estiver no modo sem bloqueio, o descritor de soquete retornado não será utilizável até que uma indicação de FD_CONNECT correspondente no soquete original tenha sido recebida, exceto que closesocket pode ser invocado neste novo descritor de soquete para cancelar uma operação de junção pendente. Um nó raiz em uma sessão de vários pontos pode chamar WSPJoinLeaf uma ou mais vezes para adicionar um número de nós folha, no entanto, no máximo uma solicitação de conexão de vários pontos pode estar pendente por vez. Consulte Multicast independente de protocolo e multiponto no SPI para obter informações adicionais.

Para soquetes não desbloqueados, geralmente não é possível concluir a conexão imediatamente. Nesse caso, essa função retorna um descritor de soquete ainda inutilizável e a operação continua. Não há nenhum código de erro como WSAEWOULDBLOCK nesse caso, pois a função retornou efetivamente uma indicação de "início bem-sucedido". Quando o êxito ou a falha do resultado final se torna conhecido, ele pode ser relatado por meio de LPWSPAsyncSelect ou LPWSPEventSelect , dependendo de como o cliente se registra para notificação nos soquetes originais. Em ambos os casos, a notificação é anunciada com FD_CONNECT e o código de erro associado à FD_CONNECT indica êxito ou um motivo específico para falha. Observe que LPWSPSelect não pode ser usado para detectar a notificação de conclusão para WSPJoinLeaf.

O descritor de soquete retornado por WSPJoinLeaf é diferente dependendo se o descritor de soquete de entrada, s, é um c_root ou um c_leaf. Quando usado com um soquete c_root, o parâmetro name designa um nó folha específico a ser adicionado e o descritor de soquete retornado é um soquete c_leaf correspondente ao nó folha recém-adicionado. (Conforme descrito na seção Alocação de Descritor, quando novos descritores de soquete são alocados provedores IFS devem chamar WPUModifyIFSHandle e provedores não IFS devem chamar WPUCreateSocketHandle). O soquete recém-criado tem as mesmas propriedades que s , incluindo eventos assíncronos registrados com LPWSPAsyncSelect ou com LPWSPEventSelect. Ele não se destina a ser usado para troca de dados de vários pontos, mas é usado para receber indicações de evento de rede (por exemplo, FD_CLOSE) para a conexão que existe com o c_leaf específico. Algumas implementações de vários pontos também podem permitir que esse soquete seja usado para "chats laterais" entre a raiz e um nó folha individual. Uma indicação FD_CLOSE será recebida para esse soquete se o nó folha correspondente chamar LPWSPCloseSocket para sair da sessão de vários pontos. Simétricamente, invocar WSPCloseSocket no soquete c_leaf retornado do WSPJoinLeaf fará com que o soquete no nó folha correspondente receba FD_CLOSE notificação.

Quando WSPJoinLeaf é invocado com um soquete c_leaf, o parâmetro name contém o endereço do nó raiz (para um esquema de controle com raiz) ou uma sessão multiponto existente (esquema de controle não separado) e o descritor de soquete retornado é o mesmo que o descritor de soquete de entrada. Em outras palavras, um novo descritor de soquete não é alocado. Em um esquema de controle raiz, o aplicativo raiz colocaria seu soquete c_root no modo de escuta chamando LPWSPListen. A notificação de FD_ACCEPT padrão será entregue quando o nó folha solicitar a junção a si mesmo à sessão de vários pontos. O aplicativo raiz usa as funções LPWSPAccept usuais para admitir o novo nó folha. O valor retornado de WSPAccept também é um descritor de soquete c_leaf, assim como os retornados de WSPJoinLeaf. Para acomodar esquemas de vários pontos que permitem junções iniciadas por raiz e iniciadas por folha, é aceitável que um soquete c_root que já esteja no modo de escuta seja usado como uma entrada para WSPJoinLeaf.

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

O lpCallerData é um parâmetro de valor que contém todos os dados de usuário que devem ser enviados junto com a solicitação de junção de sessão de vários pontos. Se lpCallerData for NULL, nenhum dado do usuário será passado para o par. O lpCalleeData é um parâmetro de resultado que conterá todos os dados de usuário passados do par como parte do estabelecimento de sessão de vários pontos. lpCalleeData-len> inicialmente contém o comprimento do buffer alocado pelo cliente SPI do Windows Sockets e apontado por lpCalleeData-buf.> 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 junção de vários pontos for concluída. Para bloquear soquetes, isso será quando a função WSPJoinLeaf retornar. Para soquetes não desbloqueados, isso ocorrerá após a notificação de FD_CONNECT nos soquetes originais. 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 e/ou os aplicativos envolvidos.

No momento do estabelecimento da sessão de vários pontos, um cliente SPI do Windows Sockets pode usar os parâmetros 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, uma para cada direção, seguidas por 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 atender à 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 NULL e zero, respectivamente. Um valor NULL para lpSQOS indica que nenhum aplicativo forneceu qualidade de serviço.

O parâmetro dwFlags é usado para indicar se o soquete atuará apenas como um remetente (JL_SENDER_ONLY), apenas como um receptor (JL_RECEIVER_ONLY) ou ambos (JL_BOTH).

**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 do Windows Sockets deve descartar e recriar os soquetes necessários para retornar a um ponto estável.

Requisitos


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]
Plataforma de Destino	Windows
Cabeçalho	ws2spi.h