Função WSAJoinLeaf (winsock2.h)

Artigo
02/01/2024

A função WSAJoinLeaf une um nó folha em uma sessão de vários pontos, troca dados de conexão e especifica a qualidade de serviço necessária com base nas estruturas FLOWSPEC especificadas.

Sintaxe

SOCKET WSAAPI WSAJoinLeaf(
  [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
);

Parâmetros

[in] s

Descritor que identifica um soquete de vários pontos.

[in] name

Nome do par ao qual o soquete 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 estruturas FLOWSPEC para soquetes , uma 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).

[in] dwFlags

Sinalizadores para indicar que o soquete está agindo como um remetente (JL_SENDER_ONLY), receptor (JL_RECEIVER_ONLY) ou ambos (JL_BOTH).

Retornar valor

Se nenhum erro ocorrer, WSAJoinLeaf retornará um valor do tipo SOCKET que é um descritor para o soquete multipoint recém-criado. Caso contrário, um valor de INVALID_SOCKET é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError.

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 retorno de um descritor de soquete válido. Posteriormente, uma indicação de FD_CONNECT será fornecida no soquete original quando a operação de junção for concluída, seja com êxito ou de outra forma. O aplicativo deve usar WSAAsyncSelect ou WSAEventSelect com interesse registrado para o evento FD_CONNECT para determinar quando a operação de junção foi concluída e verifica o código de erro associado para determinar o êxito ou a falha da operação. A função select não pode ser usada para determinar quando a operação de junção é concluída.

Além disso, até que a tentativa de junção de sessão de vários pontos conclua todas as chamadas subsequentes para WSAJoinLeaf no mesmo soquete falhará com o código de erro WSAEALREADY. Depois que a operação WSAJoinLeaf for concluída 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 uma operação anterior do WSAJoinLeaf .

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 aplicativo poderá chamar WSAJoinLeaf novamente para o mesmo soquete.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
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 for para um endereço parcialmente curinga (envolvendo ADDR_ANY) e se um endereço específico precisar ser confirmado no momento dessa função.
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.
WSAEALREADY	Uma chamada WSAJoinLeaf não desbloqueada está em andamento no soquete especificado.
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.
WSAEINVAL	Uma chamada de função WSAJoinLeaf foi executada em um soquete UDP que foi aberto sem definir seu WSA_FLAG_MULTIPOINT_C_LEAF ou WSA_FLAG_MULTIPOINT_D_LEAF sinalizador de vários pontos.
WSAEISCONN	O soquete já é membro da sessão de vários pontos.
WSAEINTR	Uma chamada do Windows Socket 1.1 de bloqueio foi cancelada por meio de WSACancelBlockingCall.
WSAEINPROGRESS	Uma chamada do Windows Sockets 1.1 de bloqueio está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAENETDOWN	O subsistema de rede falhou.
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 estruturas FLOWSPEC especificadas em lpSQOS e lpGQOS não podem ser atendidas.
WSAEPROTONOSUPPORT	Não há suporte para o aumento de lpCallerData pelo provedor de serviços.
WSAETIMEDOUT	A tentativa de ingressar atingiu o tempo limite sem estabelecer uma sessão de vários pontos.

Comentários

A função WSAJoinLeaf é 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 tempo de junção da sessão também. Se o soquete s estiver desvinculado, os valores exclusivos serão atribuídos à associação local pelo sistema e o soquete será marcado como associado.

A função WSAJoinLeaf tem os mesmos parâmetros e semântica que WSAConnect , exceto que retorna um descritor de soquete (como no WSAAccept) e tem um parâmetro dwFlags adicional. Somente soquetes de vários pontos criados usando WSASocket com o conjunto de sinalizadores de vários pontos apropriado podem ser usados para parâmetros de entrada nessa função. O descritor de soquete retornado não será utilizável até que a operação de junção seja concluída. Por exemplo, se o soquete estiver no modo de desbloqueio após uma indicação de FD_CONNECT correspondente tiver sido recebida de WSAAsyncSelect ou WSAEventSelect nos soquetes originais, exceto que closesocket pode ser invocado neste novo descritor de soquete para cancelar uma operação de junção pendente. Um aplicativo raiz em uma sessão de vários pontos pode chamar WSAJoinLeaf uma ou mais vezes para adicionar vários nós folha, no entanto, no máximo uma solicitação de conexão de vários pontos pode estar pendente por vez. Consulte Multipoint e Multicast Semântica 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 , pois a função retornou efetivamente uma indicação de início bem-sucedida. Quando o êxito ou a falha do resultado final se torna conhecido, ele pode ser relatado por meio de WSAAsyncSelect ou WSAEventSelect , 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. A função select não pode ser usada para detectar a notificação de conclusão para WSAJoinLeaf.

O descritor de soquete retornado por WSAJoinLeaf é 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. O soquete recém-criado tem as mesmas propriedades que s, incluindo eventos assíncronos registrados com WSAAsyncSelect ou com WSAEventSelect. 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 closesocket para sair da sessão de vários pontos. Simétricamente, invocar closesocket no soquete c_leaf retornado de WSAJoinLeaf fará com que o soquete no nó folha correspondente receba uma notificação de FD_CLOSE.

Quando WSAJoinLeaf é invocado com um soquete c_leaf, o parâmetro name contém o endereço do aplicativo 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 listen. 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 usual accept ou WSAAccept para admitir o novo nó folha. O valor retornado de accept ou WSAAccept também é um descritor de soquete c_leaf, assim como os retornados de WSAJoinLeaf. 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 WSAJoinLeaf.

O aplicativo é 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 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 de usuário será passado para o par. O lpCalleeData é um parâmetro de resultado que conterá todos os dados de usuário passados de volta do par como parte do estabelecimento de sessão de vários pontos. O membro len da estrutura WSABUF apontado pelo parâmetro lpCalleeData inicialmente contém o comprimento do buffer alocado pelo aplicativo e apontado pelo 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 junção de vários pontos for concluída.

Para bloqueio de soquetes, será quando a função WSAJoinLeaf retornar. Para soquetes sem bloqueio, isso ocorrerá após a conclusão da operação de junção. Por exemplo, isso pode ocorrer após FD_CONNECT notificação 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.

No momento do estabelecimento da sessão de vários pontos, um aplicativo pode usar os parâmetros lpSQOS e/ou 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 opcodes.

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 respectivos valores de especificação de fluxo de envio ou recebimento serão ignorados 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 lpSQOS indica nenhuma qualidade de serviço fornecida pelo aplicativo.

Reservado para grupos de soquetes futuros. O parâmetro 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 os soquetes conectados quebram (ou seja, 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 WSAJoinLeaf, 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