Arbeiten mit Gruppen
Peer-zu-Peer-Gruppierung ist eine Technologie, mit der Entwickler schnell und effektiv ein sicheres Peernetzwerk erstellen können. In der folgenden Liste sind die wichtigsten Aspekte beim Erstellen einer Peergruppenanwendung aufgeführt.
- Abrufen einer Peeridentität
- Starten einer Peergruppe
- Registrieren für Gruppierungsereignisse
- Herstellen einer Verbindung mit einer Gruppe
- Erstellen von Administrator- und Mitgliedsrollen
- Suchen eines Peers
- Direktes Herstellen einer Verbindung mit einem Peer
- Schließen und Herunterfahren einer Gruppe
Abrufen einer Peeridentität
Vor dem Erstellen oder Herstellen einer Verbindung mit einer Gruppe muss ein Peer eine Peeridentität abrufen. Dies ist ein Name, der zum eindeutigen Identifizieren eines Peers mit einer Gruppe verwendet wird. Rufen Sie PeerEnumIdentitiesauf, um eine Aufzählungsliste aller Peeridentitäten zu erhalten, die auf dem Peer definiert sind, wodurch ein Handle an die Enumeration zurückgegeben wird. Um die Peeridentitäten abzurufen, rufen Sie PeerGetNextItem mit dem Enumerationshand handle und der Anzahl der abzurufenden Member auf. Setzen Sie den Aufruf von PeerGetNextItem fort, bis der pCount-Parameter einen Wert zurückgibt, der kleiner als die Anzahl der angeforderten Peeridentitäten ist.
Wenn keine Peeridentität für den Peer vorhanden ist, kann sie durch Aufrufen von PeerIdentityCreate erstellt werden. Nach dem Erstellen einer Peeridentität generiert der Peer ein XML-Identitätsblob, das den ihm zugewiesenen öffentlichen Schlüssel enthält.
Die Peeridentitätsinformationen werden durch Aufrufen von PeerIdentityGetXML erhalten. Diese Peeridentitätsinformationen werden vom Gruppenersteller oder einem Administrator verwendet, um die Anmeldeinformationen, die für den Beitritt zur Gruppe erforderlich sind, als Einladungs-XML-Blob auszugeben.
Weitere Informationen zu Peeridentitäten finden Sie in der Identity Manager-API-Dokumentation.
Starten der Peergruppeninfrastruktur
Bevor eine Funktion in der Peergruppierungs-API von einer Anwendung aufgerufen wird, muss PeerGroupStartup aufgerufen werden. Diese Funktion initialisiert die Peergruppeninfrastruktur für die Anwendung und legt die unterstützte Version fest.
Abrufen eines Gruppenhandpunkts
Um eine Verbindung mit einer Gruppe herzustellen und mit der Teilnahme zu beginnen, muss ein Handle für eine Peergruppe erhalten werden. In der folgenden Liste sind die drei Möglichkeiten zum Herstellen einer Verbindung mit einer Peergruppe aufgeführt:
- Erstellen einer Peergruppe durch Aufrufen von PeerGroupCreate,die eine neue Peergruppe initialisiert und ein gültiges Handle mit dem Peer als Besitzer und einzigem Administrator zurückgibt.
- Beitreten zu einer Peergruppe durch Aufrufen von PeerGroupJoin. Zum Beitreten zu einer Peergruppe muss ein Peer eine Einladung von einem Peergruppenadministrator erhalten. Um eine Einladung zu erhalten, senden Sie das XML-Blob für Identitätsinformationen an den Administrator, der eine Einladung erstellt und über einen externen Mechanismus wie E-Mail oder FTP an Sie sendet. Die Einladung und die Peeridentität werden an PeerGroupJoin übergeben, die ein gültiges Handle an die Gruppe zurückgibt.
- Öffnen sie eine Peergruppe, der ein Peer zuvor beigetreten ist, indem Sie PeerGroupOpen aufrufen. In diesem Fall ist das Abrufen einer Einladung nicht erforderlich.
Nachdem Sie von einer der oben genannten Funktionen ein gültiges Peergruppenhand handle erhalten haben, können Sie eine Verbindung mit einer Peergruppe herstellen, indem Sie PeerGroupConnect mit dem neuen Handle aufrufen.
Hinweis
Wenn die Verbindung mit einer Peergruppe fehlschlägt, tritt das Ereignis PEER _ GROUP EVENT CONNECTION FAILED _ _ _ auf. Der Handler kann versuchen, die Verbindung mit der Peergruppe wiederhergestellt zu haben.
Registrieren für Peergruppenereignisse
Bevor ein Peer an einer Peergruppe beteiligt ist, muss sich der Peer für Peergruppenereignisse registrieren. Um sich für bestimmte Peerereignisse zu registrieren, rufen Sie PeerGroupRegisterEvent auf,und übergeben Sie mindestens einen der Peerereignistypen, die in PEER _ GROUP EVENT TYPE definiert _ _ sind. Sie müssen sich für jedes Peerereignis registrieren, das für Ihre Anwendung gilt. Um beispielsweise Daten über eine direkte Verbindung zu empfangen, registrieren Sie sich für die Ereignisse PEER _ GROUP EVENT DIRECT CONNECTION und PEER GROUP EVENT INCOMING _ _ _ _ _ _ _ DATA. Jeder Aufruf übernimmt ein Ereignishand handle und gibt ein HPEEREVENT-Handle für dieses Peerereignis zurück.
Ereignishandler können die einem Peerereignis zugeordneten Daten abrufen, indem sie das Handle an registrierte Peerereignisse an PeerGroupGetEventData übergeben. Diese Peerereignisdaten werden als PEER _ GROUP _ EVENT _ DATA-Union zurückgegeben. Wenn die Peerereigniswarteschlange leer ist, gibt diese Funktion PEER _ S NO EVENT DATA _ _ _ zurück.
Sie können die Registrierung für Peerereignisse aufheben, indem Sie PeerGroupUnregisterEvent aufrufen und das Handle für das Peerereignis bereitstellen, das Sie aufheben möchten. Nachdem die Funktion aufgerufen wurde, werden die peer-Ereignisse, die dem Handle zugeordnet sind, nicht mehr registriert.
Erstellen von Administrator- und Mitgliedsrollen
Der Peer, der die Peergruppe erstellt, wird als Ersteller der Peergruppe bezeichnet und verfügt standardmäßig über die Administratorrolle. Nur der Ersteller der Peergruppe kann die Gruppeneigenschaften festlegen.
Peers, die in die Peergruppe eingeladen werden, können entweder ein Administrator oder ein Mitglied sein. Wenn ihnen vom Administrator, der die Einladung ausstellen, eine Administratorrolle zugewiesen wird, können sie neue Mitglieder zur Peergruppe einladen und die Administratorrolle auch anderen Mitgliedern zuweisen.
Die Rollen von Peergruppenmitgliedern werden in den Einladungen festgelegt, die der Administrator einem Mitglied erteilt. Um weitere Administratoren hinzuzufügen, legen Sie beim Erstellen einer Einladung den Wert des pRoles-Parameters von PeerGroupCreateInvitation auf PEER _ GROUP ROLE ADMIN _ _ fest.
Mitglieder können an einer Peergruppe teilnehmen, aber keine neuen Mitglieder einladen und autorisieren, Gruppeneigenschaften festlegen oder Gruppendatensätze aktualisieren oder löschen, die sie nicht speziell erstellen. Legen Sie zum Zuweisen des Mitgliedsstatus zu einem beteiligten Peer den Wert des pRoles-Parameters von PeerGroupCreateInvitation auf PEER GROUP ROLE MEMBER fest, wenn Sie eine Einladung für diesen Peer _ _ _ erstellen.
Um die Rolle eines Mitglieds zu ändern, müssen neue Anmeldeinformationen, die die neue Rolle enthalten, an dieses Mitglied ausgegeben werden. Um dies zu erreichen, erhalten Sie die PEER _ CREDENTIAL _ INFO-Struktur für diesen Member aus der PEER MEMBER-Struktur, die von _ PeerGroupEnumMembers zurückgegeben wird. Ändern Sie das Feld pRoles in PEER _ CREDENTIAL _ INFO in die neue Rolle, und übergeben Sie die Struktur an PeerGroupIssueCredentials.
Die neuen Anmeldeinformationen werden für den Peer erst wirksam, wenn sie eine Verbindung mit der Peergruppe herstellen. Wenn sie derzeit verbunden sind, müssen sie die Gruppe schließen und erneut eine Verbindung herstellen, um die aktualisierten Anmeldeinformationen zu erhalten.
Suchen eines Peers
Um eine Aufzählungsliste aller Peers zu erhalten, die an der Peergruppe teilnehmen, rufen Sie PeerGroupEnumMembers mit dem Gruppenhand handle auf, das ein Handle an die Enumeration zurückgibt. Rufen Sie PeerGetNextItem mit dem enum-Handle und der Anzahl der abzurufenden Member auf, um die Member abzurufen. Setzen Sie den Aufruf von PeerGetNextItem fort, bis der pCount-Parameter einen Wert zurückgibt, der kleiner als die Anzahl der angeforderten Member ist. Beachten Sie, dass die vollständige Liste der verfügbaren Member möglicherweise nicht zurückgegeben wird.
Jedes Mitglied wird als _ PEERMITGLIEDsstruktur dargestellt, die die Identität des Peers, der Knoten-IDs und der IP-Adressen für aktive Peers enthält.
Schließen Sie die Enumeration, und geben Sie den zugeordneten Arbeitsspeicher frei, indem Sie PeerEndEnumeration aufrufen.
Direktes Herstellen einer Verbindung mit einem Peer
Wenn ein Peer mit einer Peergruppe verbunden ist, werden direkte 1:1-Austausche mit anderen verbundenen Mitgliedern durch Aufrufen von PeerGroupOpenDirectConnection und Die Identität des anderen Peers wird initiiert. Dieser Aufruf ist asynchron und gibt eine 64-Bit-Verbindungs-ID zurück. Wenn der Aufruf erfolgreich ist, erhalten Sie das Peerereignis PEER GROUP EVENT DIRECT CONNECTION EVENT, um anzugeben, _ dass die Verbindung erfolgreich hergestellt _ _ _ _ wurde. Wenn die Verbindung erfolgreich hergestellt wurde, ist die Verbindungs-ID gültig und kann zum Senden und Empfangen von Daten über die direkte Verbindung verwendet werden.
Um direkte Verbindungen empfangen zu können, muss sich der andere Peer zuvor auch für das Peerereignis PEER _ GROUP EVENT DIRECT CONNECTION registriert _ _ _ haben.
Um Daten an einen Peer zu senden, rufen Sie PeerGroupSendData mit einer gültigen Verbindungs-ID auf. Zum Empfangen von Daten muss der andere Peer für das Peerereignis PEER _ GROUP EVENT INCOMING DATA registriert _ _ _ sein. Wenn der sendende Peer wiederum Daten empfangen möchte, muss er auch für das Peerereignis PEER _ GROUP EVENT INCOMING DATA registriert _ _ _ werden.
Um den Gesamtsatz der derzeit aktiven direkten Verbindungen mit anderen Peers in einer Gruppe zu erhalten, rufen Sie PeerGroupEnumConnections auf, um die Enumeration zu öffnen, und iterieren Sie die Liste der Verbindungen mit peerGetNextItem.
Um eine direkte Verbindung zu schließen, rufen Sie PeerGroupCloseDirectConnection auf, und übergeben Sie die Verbindungs-ID.
Schließen und Herunterfahren einer Peergruppe
Um eine Verbindung mit einer Peergruppe zu schließen, rufen Sie PeerGroupCloseauf, wodurch das Gruppenhandy ungültig wird, aber die Peergruppierungsinfrastruktur nicht heruntergefahren wird. Peer-zu-Peer-Gruppendaten werden durch Aufrufen von PeerGroupDelete gelöscht.
Wenn die Anwendung die Peergruppierungsinfrastruktur nicht mehr verwendet, muss sie PeerGroupShutdown aufrufen.