Funzione WSAJoinLeaf (winsock2.h)

Articolo
03/13/2024

La funzione WSAJoinLeaf unisce un nodo foglia in una sessione multipoint, scambia i dati di connessione e specifica la qualità del servizio necessaria in base alle strutture FLOWSPEC specificate.

Sintassi

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
);

Parametri

[in] s

Descrittore che identifica un socket multipoint.

[in] name

Nome del peer a cui deve essere unito il socket.

[in] namelen

Lunghezza del nome, in byte.

[in] lpCallerData

Puntatore ai dati utente da trasferire al peer durante la creazione di sessioni multipoint.

[out] lpCalleeData

Puntatore ai dati utente che devono essere trasferiti dal peer durante la creazione di sessioni multipoint.

[in] lpSQOS

Puntatore alle strutture FLOWSPEC per socket s, una per ogni direzione.

[in] lpGQOS

Riservato per uso futuro con i gruppi di socket. Puntatore alle strutture FLOWSPEC per il gruppo di socket (se applicabile).

[in] dwFlags

Flag per indicare che il socket funge da mittente (JL_SENDER_ONLY), ricevitore (JL_RECEIVER_ONLY) o entrambi (JL_BOTH).

Valore restituito

Se non si verifica alcun errore, WSAJoinLeaf restituisce un valore di tipo SOCKET che è un descrittore per il socket multipoint appena creato. In caso contrario, viene restituito un valore di INVALID_SOCKET e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

In un socket di blocco, il valore restituito indica l'esito positivo o negativo dell'operazione di join.

Con un socket non bloccante, l'avvio riuscito di un'operazione di join è indicato da una restituzione di un descrittore socket valido. Successivamente, viene fornita un'indicazione FD_CONNECT sul socket originale quando l'operazione di join viene completata correttamente o in altro modo. L'applicazione deve usare WSAAsyncSelect o WSAEventSelect con interesse registrato per l'evento FD_CONNECT per determinare quando l'operazione di join è stata completata e controlla il codice di errore associato per determinare l'esito positivo o negativo dell'operazione. La funzione select non può essere utilizzata per determinare quando l'operazione di join viene completata.

Inoltre, finché il tentativo di join di sessione multipoint completa tutte le chiamate successive a WSAJoinLeaf nello stesso socket avrà esito negativo con il codice di errore WSAEALREADY. Al termine dell'operazione WSAJoinLeaf , un tentativo successivo avrà in genere esito negativo con il codice di errore WSAEISCONN. Si verifica un'eccezione alla regola WSAEISCONN per un socket c_root che consente join avviati dalla radice. In tal caso, un altro join può essere avviato dopo il completamento di un'operazione WSAJoinLeaf precedente.

Se il codice di errore restituito indica che il tentativo di join di sessione multipoint non è riuscito, ovvero WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT, l'applicazione può chiamare nuovamente WSAJoinLeaf per lo stesso socket.

Codice di errore	Significato
WSANOTINITIALISED	Prima di usare questa funzione, è necessario che venga eseguita una chiamata WSAStartup riuscita.
WSAEADDRINUSE	L'indirizzo locale del socket è già in uso e il socket non è stato contrassegnato per consentire il riutilizzo degli indirizzi con SO_REUSEADDR. Questo errore si verifica in genere al momento dell'associazione, ma potrebbe essere ritardato fino a quando questa funzione non è stata associata a un indirizzo con caratteri jolly parzialmente (che coinvolgono ADDR_ANY) e se è necessario eseguire il commit di un indirizzo specifico al momento di questa funzione.
WSAEADDRNOTAVAIL	L'indirizzo remoto non è un indirizzo valido, ad esempio ADDR_ANY.
WSAEAFNOSUPPORT	Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket.
WSAEALREADY	Una chiamata WSAJoinLeaf non bloccante è in corso sul socket specificato.
WSAECONNREFUSED	Il tentativo di join è stato rifiutato forzatamente.
WSAEFAULT	Il nome o il parametro namelen non è una parte valida dello spazio indirizzi utente, il parametro namelen è troppo piccolo, la lunghezza del buffer per lpCalleeData, lpSQOS e lpGQOS è troppo piccola o la lunghezza del buffer per lpCallerData è troppo grande.
WSAEINVAL	Una chiamata di funzione WSAJoinLeaf è stata eseguita su un socket UDP aperto senza impostare il relativo WSA_FLAG_MULTIPOINT_C_LEAF o WSA_FLAG_MULTIPOINT_D_LEAF flag multipoint.
WSAEISCONN	Il socket è già membro della sessione multipoint.
WSAEINTR	Una chiamata di Windows Socket 1.1 bloccata è stata annullata tramite WSACancelBlockingCall.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets 1.1 bloccante oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENETUNREACH	Impossibile raggiungere la rete da questo host in questo momento.
WSAENOBUFS	Nessuno spazio di buffer disponibile. Il socket non può essere unito.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	Le strutture FLOWSPEC specificate in lpSQOS e lpGQOS non possono essere soddisfatte.
WSAEPROTONOSUPPORT	L'aumento lpCallerData non è supportato dal provider di servizi.
WSAETIMEDOUT	Tentativo di join timeout senza stabilire una sessione multipunto.

Commenti

La funzione WSAJoinLeaf viene usata per unire un nodo foglia a una sessione multipunto e per eseguire anche diverse altre operazioni ausiliarie che si verificano anche in fase di join della sessione. Se il socket s non è associato, i valori univoci vengono assegnati all'associazione locale dal sistema e il socket viene contrassegnato come associato.

La funzione WSAJoinLeaf ha gli stessi parametri e semantica di WSAConnect , ad eccezione del fatto che restituisce un descrittore socket (come in WSAAccept) e ha un parametro dwFlags aggiuntivo. In questa funzione è possibile usare solo socket multipoint creati con WSASocket con flag multipoint appropriati. Il descrittore socket restituito non sarà utilizzabile fino al completamento dell'operazione di join. Ad esempio, se il socket è in modalità non bloccante dopo che è stata ricevuta un'indicazione di FD_CONNECT corrispondente da WSAAsyncSelect o WSAEventSelectnel socket originale, ad eccezione del fatto che closesocket può essere richiamato su questo nuovo descrittore socket per annullare un'operazione di join in sospeso. Un'applicazione radice in una sessione multipoint può chiamare WSAJoinLeaf una o più volte per aggiungere un numero di nodi foglia, ma al massimo una richiesta di connessione multipoint può essere in sospeso alla volta. Per altre informazioni, vedere Multipoint and Multicast Semantics (Semantica multipoint e Multicast ).

Per i socket non bloccanti, spesso non è possibile completare immediatamente la connessione. In questo caso, questa funzione restituisce un descrittore socket non ancora utilizzabile e l'operazione procede. In questo caso non è presente codice di errore, ad esempio WSAEWOULDBLOCK , poiché la funzione ha restituito un'indicazione di inizio corretta. Quando il risultato finale ha esito positivo o negativo, può essere segnalato tramite WSAAsyncSelect o WSAEventSelect a seconda del modo in cui il client esegue la registrazione per la notifica sul socket originale. In entrambi i casi, la notifica viene annunciata con FD_CONNECT e il codice di errore associato al FD_CONNECT indica l'esito positivo o un motivo specifico per l'errore. La funzione select non può essere usata per rilevare la notifica di completamento per WSAJoinLeaf.

Il descrittore di socket restituito da WSAJoinLeaf è diverso a seconda che il descrittore del socket di input, s, sia un c_root o un c_leaf. Se usato con un socket c_root, il parametro name designa un particolare nodo foglia da aggiungere e il descrittore socket restituito è un socket c_leaf corrispondente al nodo foglia appena aggiunto. Il socket appena creato ha le stesse proprietà di s, inclusi gli eventi asincroni registrati con WSAAsyncSelect o con WSAEventSelect. Non è destinato a essere utilizzato per lo scambio di dati multipunto, ma viene usato per ricevere le indicazioni degli eventi di rete (ad esempio, FD_CLOSE) per la connessione esistente al c_leaf specifico. Alcune implementazioni multipoint possono anche consentire l'uso di questo socket per le chat laterali tra la radice e un singolo nodo foglia. Verrà ricevuta un'indicazione FD_CLOSE per questo socket se il nodo foglia corrispondente chiama closesocket per uscire dalla sessione multipoint. In modo simmetrico, richiamando closesocket sul socket c_leaf restituito da WSAJoinLeaf , il socket nel nodo foglia corrispondente riceverà una notifica di FD_CLOSE.

Quando WSAJoinLeaf viene richiamato con un socket c_leaf, il parametro name contiene l'indirizzo dell'applicazione radice (per uno schema di controllo rooted) o una sessione multipoint esistente (schema di controllo non radice) e il descrittore socket restituito corrisponde al descrittore del socket di input. In altre parole, non viene allocato un nuovo descrittore socket. In uno schema di controllo rooted, l'applicazione radice inserisce il socket c_root in modalità di ascolto chiamando listen. La notifica standard FD_ACCEPT verrà recapitata quando il nodo foglia richiede di aggiungersi alla sessione multipoint. L'applicazione radice usa le normali funzioni accept o WSAAccept per ammettere il nuovo nodo foglia. Il valore restituito da accept o WSAAccept è anche un descrittore socket c_leaf proprio come quelli restituiti da WSAJoinLeaf. Per supportare schemi multipunto che consentono join avviati dalla radice e avviati dalla foglia, è accettabile per un socket c_root già in modalità di ascolto da usare come input per WSAJoinLeaf.

L'applicazione è responsabile dell'allocazione di qualsiasi spazio di memoria a cui punta direttamente o indirettamente uno qualsiasi dei parametri specificati.

lpCallerData è un parametro di valore che contiene tutti i dati utente da inviare insieme alla richiesta di join di sessione multipoint. Se lpCallerData è NULL, non verranno passati dati utente al peer. LpCalleeData è un parametro di risultato che conterrà tutti i dati utente passati dal peer come parte dell'istituzione della sessione multipoint. Il membro len della struttura WSABUF puntato al parametro lpCalleeData contiene inizialmente la lunghezza del buffer allocata dall'applicazione e punta al membro buf della struttura WSABUF . Il membro len della struttura WSABUF a cui fa riferimento il parametro lpCalleeData verrà impostato su zero se non sono stati passati dati utente. Le informazioni lpCalleeData saranno valide al termine dell'operazione di join multipoint.

Per i socket di blocco, questo sarà quando viene restituita la funzione WSAJoinLeaf . Per i socket non sbloccanti, questa operazione verrà completata dopo il completamento dell'operazione di join. Ad esempio, questo potrebbe verificarsi dopo FD_CONNECT notifica sul socket originale s). Se lpCalleeData è NULL, non verranno passati i dati utente. Il formato esatto dei dati utente è specifico della famiglia di indirizzi a cui appartiene il socket.

In fase di creazione di sessioni multipoint, un'applicazione può usare i parametri lpSQOS e/o lpGQOS per eseguire l'override di qualsiasi qualità precedente della specifica del servizio effettuata per il socket tramite WSAIoctl con il SIO_SET_QOS o SIO_SET_GROUP_QOS opcode.

Il parametro lpSQOS specifica le strutture FLOWPEC per socket s, una per ogni direzione, seguita da eventuali parametri specifici del provider aggiuntivi. Se il provider di trasporto associato in generale o il tipo specifico di socket in particolare non può rispettare la qualità della richiesta di servizio, verrà restituito un errore come indicato nel seguente. I rispettivi valori di specifica del flusso di invio o ricezione verranno ignorati per eventuali socket unidirectionali. Se non vengono specificati parametri specifici del provider, i membri buf e len della struttura WSABUF puntati dal parametro lpCalleeData devono essere impostati rispettivamente su NULL e zero. Un valore NULL per lpSQOS indica che non è disponibile alcuna qualità del servizio fornita dall'applicazione.

Riservato ai gruppi di socket futuri. Il parametro lpGQOS specifica le strutture FLOWPEC per il gruppo socket (se applicabile), una per ogni direzione, seguita da eventuali parametri specifici del provider aggiuntivi. Se non vengono specificati parametri specifici del provider, i membri buf e len della struttura WSABUF puntati dal parametro lpCalleeData devono essere impostati rispettivamente su NULL e zero. Un valore NULL per lpGQOS non indica la qualità del servizio fornita dall'applicazione. Questo parametro verrà ignorato se s non è l'autore del gruppo di socket.

Quando i socket connessi si interrompono (ovvero, diventano chiusi per qualsiasi motivo), devono essere eliminati e ricreati. È più sicuro presupporre che quando le cose vanno awry per qualsiasi motivo su un socket connesso, l'applicazione deve eliminare e ricreare i socket necessari per tornare a un punto stabile.

Nota Quando si emette una chiamata Winsock bloccante, ad esempio WSAJoinLeaf, Winsock potrebbe dover attendere un evento di rete prima che la chiamata possa completare. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di routine asincrona pianificata nello stesso thread. L'emissione di un'altra chiamata winsock bloccata all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread comporterà un comportamento non definito e non deve mai essere tentato dai client Winsock.

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll