Funzione di callback LPWSPJOINLEAF (ws2spi.h)

Articolo
03/15/2023

La funzione WSPJoinLeaf unisce un nodo foglia in una sessione multipoint, scambia i dati di connessione e specifica la qualità del servizio necessaria in base alle specifiche del flusso fornite.

Sintassi

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
)
{...}

Parametri

[in] s

Descrittore che identifica un socket multipoint.

[in] name

Nome del peer a cui deve essere unito il socket nella struttura sockaddr .

[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 specifiche del flusso per socket s, una per ogni direzione.

[in] lpGQOS

Riservato.

[in] dwFlags

Flag per indicare che il socket funge da mittente, ricevitore o entrambi.

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore, WSPJoinLeaf 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 in lpErrno è disponibile un codice di errore specifico.

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 corretto di un'operazione di join è indicato da un valore restituito di un descrittore socket valido. Successivamente, viene fornita un'indicazione FD_CONNECT quando l'operazione di join viene completata correttamente o in caso contrario. Il codice di errore associato alla FD_CONNECT indica l'esito positivo o negativo di WSPJoinLeaf.

Inoltre, finché il tentativo di join di sessione multipoint completa tutte le chiamate successive a WSPJoinLeaf nello stesso socket avrà esito negativo con il codice di errore WSAEALREADY. Al termine di un tentativo successivo, WSPJoinLeaf avrà 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 questo caso un altro join può essere avviato dopo il completamento di un WSPJoinLeaf precedente.

Se il codice di errore restituito indica che il tentativo di join di sessione multipoint non è riuscito, ovvero WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT, il client SPI di Windows Sockets può chiamare di nuovo WSPJoinLeaf per lo stesso socket.

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
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 la funzione bind è stata impostata su 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.
WSAEINTR	(Blocco) la chiamata è stata annullata tramite WSPCancelBlockingCall.
WSAEINPROGRESS	Il blocco della chiamata a Windows Sockets è in corso oppure il provider di servizi sta ancora elaborando una funzione di callback.
WSAEALREADY	La chiamata WSPJoinLeaf non bloccante è in corso sul socket specificato.
WSAEADDRNOTAVAIL	L'indirizzo remoto non è un indirizzo valido, ad esempio ADDR_ANY.
WSAEAFNOSUPPORT	Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket.
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.
WSAEISCONN	Socket è già membro della sessione multipoint.
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 specifiche del flusso specificate in lpSQOS 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

Questa funzione viene usata per unire un nodo foglia a una sessione multipunto e per eseguire anche diverse altre operazioni ausiliarie che si verificano 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.

WSPJoinLeaf ha gli stessi parametri e semantica di LPWSPConnect , ad eccezione del fatto che restituisce un descrittore socket (come in LPWSPAccept) e ha un parametro dwFlags aggiuntivo. In questa funzione è possibile usare solo socket multipoint creati usando LPWSPSocket con flag multipoint appropriati. Se il socket è in modalità non bloccante, il descrittore socket restituito non sarà utilizzabile fino a quando non viene ricevuta un'indicazione di FD_CONNECT corrispondente sul 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 nodo radice in una sessione multipoint può chiamare WSPJoinLeaf 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 Protocol-Independent Multicast e Multipoint in SPI .

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 "avvio riuscito". Quando il risultato finale ha esito positivo o negativo, può essere segnalato tramite LPWSPAsyncSelect o LPWSPEventSelect 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. Si noti che LPWSPSelect non può essere usato per rilevare la notifica di completamento per WSPJoinLeaf.

Il descrittore di socket restituito da WSPJoinLeaf è 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. Come descritto nella sezione Allocazione descrittore, quando i nuovi descrittori socket vengono allocati i provider IFS devono chiamare WPUModifyIFSHandle e provider non IFS devono chiamare WPUCreateSocketHandle. Il socket appena creato ha le stesse proprietà degli eventi asincroni registrati con LPWSPAsyncSelect o con LPWSPEventSelect. 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 LPWSPCloseSocket per uscire dalla sessione multipoint. Simmetricamente, la chiamata di WSPCloseSocket sul socket c_leaf restituito da WSPJoinLeaf causerà la ricezione della notifica FD_CLOSE del socket nel nodo foglia corrispondente.

Quando WSPJoinLeaf viene richiamato con un socket c_leaf, il parametro name contiene l'indirizzo del nodo radice (per uno schema di controllo rooted) o una sessione multipoint esistente (schema di controllo non radice) e il descrittore socket restituito è lo stesso del 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 nella modalità di ascolto chiamando LPWSPListen. La notifica standard FD_ACCEPT verrà recapitata quando il nodo foglia richiede di aggiungersi alla sessione multipoint. L'applicazione radice usa le normali funzioni LPWSPAccept per ammettere il nuovo nodo foglia. Il valore restituito da WSPAccept è anche un descrittore socket c_leaf proprio come quelli restituiti da WSPJoinLeaf. Per supportare schemi multipunto che consentono join avviati dalla radice e avviati da foglia, è accettabile che un socket c_root già in modalità di ascolto venga usato come input per WSPJoinLeaf.

Il client SPI Windows Sockets è responsabile dell'allocazione di qualsiasi spazio di memoria a cui punta direttamente o indirettamente da 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, al peer non verranno passati dati utente. LpCalleeData è un parametro di risultato che conterrà tutti i dati utente passati dal peer come parte della creazione di sessioni multipoint. lpCalleeData-len> inizialmente contiene la lunghezza del buffer allocato dal client SPI Windows Sockets e punta a lpCalleeData-buf.> lpCalleeData-len> 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, si verifica quando viene restituita la funzione WSPJoinLeaf . Per i socket non bloccanti, questo si verifica dopo che la notifica di FD_CONNECT si è verificata nel socket originale. Se lpCalleeData è NULL, non verranno restituiti dati utente. Il formato esatto dei dati utente è specifico per la famiglia di indirizzi a cui appartiene il socket e/o le applicazioni coinvolte.

Al momento della creazione di sessioni multipoint, un client SPI Di Windows Sockets può usare i parametri lpSQOS per eseguire l'override di qualsiasi specifica QoS precedente eseguita per il socket tramite LPWSPIoctl con il codice operativo SIO_SET_QOS.

lpSQOS specifica le specifiche del flusso per socket s, una per ogni direzione, seguita da eventuali parametri aggiuntivi specifici del provider. Se il provider di trasporto associato in generale o il tipo specifico di socket in particolare non può rispettare la richiesta QoS, verrà restituito un errore come indicato di seguito. I valori di specifica del flusso di invio o ricezione verranno ignorati, rispettivamente, per qualsiasi socket unidirezionale. Se non vengono forniti parametri specifici del provider, i membri buf e len di lpSQOS-ProviderSpecific> devono essere impostati rispettivamente su NULL e zero. Un valore NULL per lpSQOS indica che non viene fornita alcuna qualità del servizio fornita dall'applicazione.

Il parametro dwFlags viene usato per indicare se il socket fungerà solo da mittente (JL_SENDER_ONLY), solo come ricevitore (JL_RECEIVER_ONLY) o entrambi (JL_BOTH).

**Nota** 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, il client SPI Di Windows Sockets deve eliminare e ricreare i socket necessari per tornare a un punto stabile.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ws2spi.h