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.

Aggiunta a un gruppo di peer

Per partecipare a un gruppo peer, chiamare PeerGroupJoin, passando il nome dell'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 è stato aggiunto in precedenza al gruppo di peer e quindi ha chiuso l'handle, il gruppo peer deve essere riaperto chiamando PeerGroupOpen e passando il nome del gruppo peer. Questa chiamata restituisce un nuovo handle di gruppo peer.

Dopo che il gruppo di peer è stato aggiunto correttamente, il peer può connettersi direttamente al gruppo di 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 di peer in un'istanza successiva, una chiamata successiva a PeerGroupConnect lo porterà online. Dopo che un peer è stato aggiunto al gruppo peer, deve connettersi almeno una volta prima di poter pubblicare i record nel gruppo peer.

Apertura di un gruppo di peer senza connessione (offline)

Spesso, è possibile che un'applicazione si connetta a un gruppo peer, ma non direttamente partecipa, riceva e pubblica gli aggiornamenti dei record, ma non invii o riceva messaggi di dati. Un'applicazione si trova in questo stato "offline" immediatamente dopo la chiamata di PeerGroupCreate, PeerGroupJoin o PeerGroupOpen .

Un'applicazione offline può essere online in qualsiasi momento chiamando PeerGroupConnect. Dopo la connessione, un gruppo di peer non può essere offline finché tutte le altre applicazioni associate a questa identità e la condivisione di questo gruppo non hanno chiuso le connessioni.

Un gruppo peer è una risorsa condivisa, con lo stesso gruppo di peer disponibile per più applicazioni. Se più applicazioni per la stessa identità e l'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 l'identità o l'utente che partecipano al gruppo si connettono anche al gruppo. Se un record viene aggiunto da un'applicazione mentre il gruppo è offline, anche altre applicazioni possono visualizzarlo. Di conseguenza, un'applicazione deve essere pronta per essere online in qualsiasi momento.

Connessione a un gruppo di peer (online)

Per iniziare a partecipare a un gruppo, chiamare PeerGroupConnect dopo aver creato, aggiunto o aperto il 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, registrarsi 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 che il database del gruppo venga sincronizzato e non sia possibile stabilire un'altra connessione.

Anche se più applicazioni in esecuzione nel peer e che partecipano allo stesso gruppo con la stessa identità peer possono essere offline, una chiamata a PeerGroupConnect da una 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 a PeerGroupOpenDirectConnection, passando l'handle per un gruppo connesso e l'identità del peer all'interno del gruppo a cui ci si vuole connettere. Questo metodo restituirà un ID di 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 passarlo 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 connessione ottenuto da una chiamata precedente a PeerGroupOpenDirectConnection o ricevuti nei dati dell'evento per PEER_EVENT_GROUP_DIRECT_CONNECTION.