Come connettersi a un gruppo di peer

Questo argomento illustra come un'applicazione si connette a un gruppo peer usando le API di raggruppamento peer.

Partecipazione a un gruppo di pari

Per partecipare a un gruppo peer, chiamare PeerGroupJoin, passando il nome di identità del peer e l'invito (e un nome cloud PNRP facoltativo, se il nome del cloud nell'invito è ambiguo).

In caso di esito positivo, PeerGroupJoin restituisce un handle al gruppo peer.

Se il peer ha aderito in precedenza al gruppo di peer e quindi ha chiuso l'handle, il gruppo di peer deve essere riaperto chiamando PeerGroupOpen e passando il nome del gruppo di peer. Questa chiamata restituisce un nuovo identificatore per il gruppo di pari.

Una volta che il gruppo peer è stato aggiunto correttamente, il peer può collegarsi direttamente al gruppo peer e iniziare a interagire chiamando PeerGroupConnect. Dopo la connessione, il peer viene considerato "online".

Se un'applicazione non interagisce con il gruppo al momento, può rimanere "offline". Se sceglie di partecipare direttamente al gruppo peer in un'istanza successiva, una chiamata successiva a PeerGroupConnect lo porterà online. Dopo che un peer è stato aggiunto al gruppo di pari, deve connettersi almeno una volta prima di poter pubblicare i record nel gruppo di pari.

Apertura di un gruppo di peer senza connessione (offline)

Spesso, potresti volere che un'applicazione si connetta a un gruppo peer ma senza partecipare direttamente, ricevendo e pubblicando aggiornamenti dei record ma non inviando o ricevendo messaggi di dati. Un'applicazione si trova in questo stato "offline" immediatamente dopo aver chiamato PeerGroupCrea, PeerGroupJoino PeerGroupOpen.

Un'applicazione offline può essere online in qualsiasi momento chiamando PeerGroupConnect. Dopo la connessione, un gruppo di peer non può andare offline fino a quando tutte le altre applicazioni associate a questa identità e che condividono questo gruppo non abbiano chiuso le connessioni.

Un gruppo di peer è una risorsa condivisa, con lo stesso gruppo di peer disponibile per più applicazioni. Se più applicazioni per la stessa identità e lo stesso utente di Windows usano lo stesso gruppo di peer, condividono anche lo stesso database e le stesse connessioni sottostanti (adiacente e diretto). Se una di queste applicazioni chiama PeerGroupConnect, tutte le altre applicazioni per questa identità/utente che partecipano al gruppo si connettono anche al gruppo. Se un record viene aggiunto da un'applicazione mentre il gruppo è offline, possono essere visualizzate anche altre applicazioni. Di conseguenza, un'applicazione deve essere pronta per essere online in qualsiasi momento.

Connessione a un gruppo di pari (online)

Per iniziare a partecipare a un gruppo, chiamare PeerGroupConnect dopo la creazione, l'aggiunta o l'apertura del gruppo. In questo stato, le connessioni dirette possono essere aperte con altri peer che partecipano allo stesso gruppo chiamando PeerGroupOpenDirectConnection.

Per rilevare se un tentativo di connessione non è riuscito, eseguire la registrazione per l'evento PEER_GROUP_EVENT_CONNECTION_FAILED. Questo evento viene generato se l'infrastruttura di raggruppamento non riesce a trovare un altro membro a cui connettersi o se la connessione non riesce prima della sincronizzazione del database del gruppo e non è possibile stabilire un'altra connessione.

Anche se più applicazioni in esecuzione sul peer e che partecipano allo stesso gruppo con la stessa identità peer possono essere offline, una chiamata a PeerGroupConnect da una qualsiasi delle applicazioni comporta che tutte le applicazioni diventino online.

Inoltre, se un'applicazione nel peer è connessa al gruppo, tutte le altre applicazioni che chiamano PeerGroupJoin o PeerGroupOpen vengono immediatamente connesse. Se un'applicazione chiama PeerGroupClose, l'handle viene chiuso solo per tale applicazione. Pertanto, una chiamata successiva a PeerGroupOpen dall'applicazione restituisce un nuovo handle di gruppo e l'applicazione viene portata online immediatamente se altre applicazioni che partecipano allo stesso gruppo sono ancora connesse.

Invio e ricezione di dati

Per inviare e ricevere dati tra nodi membro specifici nel gruppo, è necessario stabilire connessioni dirette con i membri con cui si intende interagire. Stabilire una connessione diretta è una chiamata asincrona alla funzione PeerGroupOpenDirectConnection, passando l'handle di un gruppo connesso e l'identità del peer nel gruppo al quale ci si vuole connettere. Questo metodo restituirà un ID connessione. Se la chiamata ha esito positivo, viene generato un evento PEER_GROUP_EVENT_DIRECT_CONNECTION nel peer, convalidando l'ID connessione.

Per ricevere connessioni dirette da altri peer online, registrarsi per l'evento PEER_GROUP_EVENT_DIRECT_CONNECTION con una chiamata a PeerGroupRegisterEvent.

Dopo aver stabilito correttamente una connessione diretta, l'applicazione può iniziare a inviare dati con chiamate a PeerGroupSendData, passando l'ID di connessione valido. L'ordinamento delle trasmissioni di dati multipart viene gestito da PeerGroupSendData. Tuttavia, le applicazioni devono implementare uno stack di protocolli appropriato per la gestione dei dati opachi restituiti da questa chiamata API.

Per ricevere dati tramite una connessione diretta, l'applicazione deve registrarsi per l'evento PEER_GROUP_EVENT_INCOMING_DATA con PeerGroupRegisterEvent. Il gestore eventi è responsabile di ottenere e ordinare i dati opachi e di passarli all'applicazione. Questi dati vengono ottenuti all'interno del gestore eventi chiamando PeerGroupGetEventData con l'handle per gli eventi registrati.

Una connessione diretta viene chiusa chiamando PeerGroupCloseDirectConnection e passando l'ID della connessione ottenuto da una chiamata precedente a PeerGroupOpenDirectConnection o ricevuto nei dati dell'evento per PEER_EVENT_GROUP_DIRECT_CONNECTION.