Condividi tramite

Come usare i gruppi

  • Articolo

Il raggruppamento peer-to-peer è una tecnologia che consente a uno sviluppatore di creare una rete peer sicura in modo rapido ed efficace. L'elenco seguente identifica le considerazioni principali per la creazione di un'applicazione di raggruppamento peer.

Acquisizione di un'identità peer

Prima di creare o connettersi a un gruppo, un peer deve ottenere un'identità peer, ovvero un nome usato per identificare in modo univoco un peer a un gruppo. Per ottenere un elenco enumerato di tutte le identità peer definite nel peer, chiamare PeerEnumIdentities, che restituisce un handle all'enumerazione . Per ottenere le identità peer, chiamare PeerGetNextItem con l'handle di enumerazione e il numero di membri da recuperare. Continuare a chiamare PeerGetNextItem finché il parametro pCount restituisce un valore minore del numero di identità peer richieste.

Se non esiste un'identità peer per il peer, può essere creata chiamando PeerIdentityCreate. Dopo aver creato un'identità peer, il peer genera un BLOB XML di identità contenente la chiave pubblica assegnata.

Le informazioni sull'identità peer vengono ottenute chiamando PeerIdentityGetXML. Queste informazioni sull'identità peer vengono usate dall'autore del gruppo o da un amministratore per rilasciare le credenziali necessarie per partecipare al gruppo, come BLOB XML di invito.

Per altre informazioni sulle identità peer, vedere la documentazione dell'API di Identity Manager

Avvio dell'infrastruttura di peer grouping

Prima che qualsiasi funzione nell'API Peer Grouping venga chiamata da un'applicazione, è necessario chiamare PeerGroupStartup . Questa funzione inizializza l'infrastruttura di raggruppamento peer per l'applicazione e imposta la versione supportata.

Recupero di un handle di gruppo

Per connettersi a un gruppo e iniziare a partecipare, è necessario ottenere un handle per un gruppo peer. L'elenco seguente identifica i tre modi per connettersi a un gruppo di peer:

  • Creazione di un gruppo peer chiamando PeerGroupCreate, che inizializza un nuovo gruppo di peer e restituisce un handle valido con il peer come proprietario e amministratore unico.
  • Partecipare a un gruppo peer chiamando PeerGroupJoin. Per partecipare a un gruppo peer, un peer deve ricevere un invito da un amministratore del gruppo peer. Per ottenere un invito, inviare il BLOB XML delle informazioni sull'identità all'amministratore che crea un invito e lo invia tramite un meccanismo esterno, ad esempio posta elettronica o FTP. L'identità di invito e peer viene passata a PeerGroupJoin, che restituisce un handle valido al gruppo.
  • Apertura di un gruppo peer aggiunto in precedenza da un peer chiamando PeerGroupOpen. In questo caso, l'acquisizione di un invito non è necessaria.

Dopo aver ottenuto un handle di gruppo peer valido da una delle funzioni precedenti, è possibile connettersi a un gruppo peer chiamando PeerGroupConnect con il nuovo handle.

Nota

Se la connessione a un gruppo peer ha esito negativo, si verifica l'evento PEER_GROUP_EVENT_CONNECTION_FAILED. Il gestore può tentare di ristabilire la connessione al gruppo peer.

 

Registrazione per gli eventi di peer grouping

Prima che un peer partecipi a un gruppo peer, il peer deve registrarsi per gli eventi del gruppo peer. Per eseguire la registrazione per eventi peer specifici, chiamare PeerGroupRegisterEvent e passare uno o più tipi di eventi peer definiti in PEER_GROUP_EVENT_TYPE. È necessario registrarsi per ogni evento peer applicabile all'applicazione; Ad esempio, per ricevere dati tramite una connessione diretta, registrarsi per gli eventi PEER_GROUP_EVENT_DIRECT_CONNECTION e PEER_GROUP_EVENT_INCOMING_DATA. Ogni chiamata accetta un handle di evento e restituisce un handle HPEEREVENT per tale evento peer.

I gestori eventi possono ottenere i dati associati a un evento peer passando l'handle agli eventi peer registrati a PeerGroupGetEventData. Questi dati dell'evento peer vengono restituiti come unione PEER_GROUP_EVENT_DATA. Se la coda di eventi peer è vuota, questa funzione restituisce PEER_S_NO_EVENT_DATA.

È possibile annullare la registrazione per gli eventi peer chiamando PeerGroupUnregisterEvent e fornendo l'handle per l'evento peer che si vuole annullare la registrazione. Dopo aver chiamato la funzione, gli eventi peer associati all'handle non vengono più registrati.

Creazione di ruoli amministratore e membro

Il peer che crea il gruppo di peer è noto come autore del gruppo di peer e ha il ruolo di amministratore per impostazione predefinita. Solo l'autore del gruppo peer può impostare le proprietà del gruppo.

I peer invitati al gruppo peer possono essere un amministratore o un membro. Se viene assegnato un ruolo di amministratore dall'amministratore che emette l'invito, può invitare nuovi membri al gruppo peer e assegnare in modo analogo il ruolo di amministratore ad altri membri.

I ruoli dei membri del gruppo peer vengono impostati negli inviti che l'amministratore assegna a un membro. Per aggiungere altri amministratori, impostare il valore del parametro pRoles di PeerGroupCreateInvitation su PEER_GROUP_ROLE_ADMIN durante la creazione di un invito.

I membri possono partecipare a un gruppo peer, ma non possono invitare e autorizzare nuovi membri, impostare le proprietà del gruppo o aggiornare o eliminare record di gruppo che non creano in modo specifico. Per assegnare lo stato del membro a un peer partecipante, impostare il valore del parametro pRoles di PeerGroupCreateInvitation su PEER_GROUP_ROLE_MEMBER quando si crea un invito per tale peer.

Per modificare il ruolo di un membro, è necessario emettere nuove credenziali contenenti il nuovo ruolo a tale membro. A tale scopo, ottenere la struttura PEER_CREDENTIAL_INFO per questo membro dalla struttura PEER_MEMBER restituita da PeerGroupEnumMembers. Modificare il campo pRoles in PEER_CREDENTIAL_INFO al nuovo ruolo e passare la struttura a PeerGroupIssueCredentials.

Le nuove credenziali non verranno applicate per il peer fino a quando non si connettono al gruppo peer. Se sono attualmente connessi, è necessario chiudere il gruppo e riconnettersi per ottenere le credenziali aggiornate.

Ricerca di un peer

Per ottenere un elenco enumerato di tutti i peer che partecipano al gruppo peer, chiamare PeerGroupEnumMembers con l'handle di gruppo, che restituisce un handle all'enumerazione . Per ottenere i membri, chiamare PeerGetNextItem con l'handle di enumerazione e il numero di membri da recuperare. Continuare a chiamare PeerGetNextItem finché il parametro pCount restituisce un valore minore del numero di membri richiesti. Si noti che l'elenco completo dei membri disponibili potrebbe non essere restituito.

Ogni membro è rappresentato come struttura PEER_MEMBER , che contiene l'identità del peer, degli ID nodo e degli indirizzi IP per i peer attivi.

Al termine, chiudere l'enumerazione e rilasciare la memoria associata chiamando PeerEndEnumeration.

Connessione diretta a un peer

Quando un peer è connesso a un gruppo peer, gli scambi uno-a-uno diretti con altri membri connessi vengono avviati chiamando PeerGroupOpenDirectConnection e fornendo l'identità dell'altro peer. Questa chiamata è asincrona e restituisce un ID di connessione a 64 bit. Se la chiamata ha esito positivo, si riceve l'evento peer PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT per indicare che la connessione ha esito positivo. Se la connessione ha esito positivo, l'ID connessione è valido e può essere usato per inviare e ricevere dati tramite la connessione diretta.

Per poter ricevere connessioni dirette, l'altro peer deve essere registrato in precedenza per l'evento peer PEER_GROUP_EVENT_DIRECT_CONNECTION.

Per inviare dati a un peer, chiamare PeerGroupSendData con un ID di connessione valido. Per ricevere i dati, l'altro peer deve essere registrato per l'evento peer PEER_GROUP_EVENT_INCOMING_DATA. Analogamente, se il peer di invio vuole ricevere i dati a sua volta, deve anche essere registrato per l'evento peer PEER_GROUP_EVENT_INCOMING_DATA.

Per ricevere il set totale di connessioni dirette attualmente attive con altri peer in un gruppo, chiamare PeerGroupEnumConnections per aprire l'enumerazione e scorrere l'elenco di connessioni usando PeerGetNextItem.

Per chiudere una connessione diretta, chiamare PeerGroupCloseDirectConnection e passare l'ID connessione.

Chiusura e chiusura di un gruppo di peer

Per chiudere una connessione a un gruppo peer, chiamare PeerGroupClose, che invalida l'handle di gruppo, ma non arresta l'infrastruttura di raggruppamento peer. I dati del gruppo peer-to-peer vengono eliminati chiamando PeerGroupDelete.

Al termine dell'applicazione che usa l'infrastruttura di raggruppamento peer, deve chiamare PeerGroupShutdown.