Arbeiten mit Gruppen

Peer-to-Peer-Gruppierung ist eine Technologie, mit der Entwickler schnell und effektiv ein sicheres Peernetzwerk erstellen können. In der folgenden Liste sind die wichtigsten Überlegungen beim Erstellen einer Peergruppierungsanwendung 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, bei der es sich um einen Namen handelt, der zum eindeutigen Identifizieren eines Peers zu einer Gruppe verwendet wird. Rufen Sie PeerEnumIdentities auf, um eine liste aller auf dem Peer definierten Peeridentitäten zu erhalten. Dadurch wird ein Handle für die Enumeration zurückgegeben. Um die Peeridentitäten abzurufen, rufen Sie PeerGetNextItem mit dem Enumerationshandle und der Anzahl der abzurufenden Member auf. Fahren Sie mit dem Aufrufen 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 abgerufen. Diese Peeridentitätsinformationen werden vom Ersteller der Gruppe oder einem Administrator verwendet, um die Anmeldeinformationen auszugeben, die für den Beitritt zur Gruppe als Einladungs-XML-Blob erforderlich sind.

Weitere Informationen zu Peeridentitäten finden Sie in der Dokumentation zur Identity Manager-API .

Starten der Peergruppierungsinfrastruktur

Bevor eine Funktion in der Peergruppierungs-API von einer Anwendung aufgerufen wird, muss PeerGroupStartup aufgerufen werden. Diese Funktion initialisiert die Peergruppierungsinfrastruktur für die Anwendung und legt die unterstützte Version fest.

Abrufen eines Gruppenhandles

Um eine Verbindung mit einer Gruppe herzustellen und mit der Teilnahme zu beginnen, muss ein Handle für eine Peergruppe abgerufen 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, wodurch eine neue Peergruppe initialisiert und ein gültiges Handle mit dem Peer als Besitzer und alleiniger Administrator zurückgegeben wird.
• Beitreten zu einer Peergruppe durch Aufrufen von PeerGroupJoin. Um einer Peergruppe beizutreten, muss ein Peer eine Einladung von einem Peergruppenadministrator erhalten. Um eine Einladung zu erhalten, senden Sie das XML-Identitätsinformationsblob an den Administrator, der eine Einladung erstellt, und sendet Sie sie über einen externen Mechanismus wie E-Mail oder FTP an Sie. 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 Einholen einer Einladung nicht erforderlich.

Nachdem Sie ein gültiges Peergruppenhandle von einer der oben genannten Funktionen erhalten haben, können Sie eine Verbindung mit einer Peergruppe herstellen, indem Sie PeerGroupConnect mit dem neuen Handle aufrufen.

Registrieren für Peergruppierungsereignisse

Bevor ein Peer an einer Peergruppe teilnimmt, muss er sich für Peergruppenereignisse registrieren. Um sich für bestimmte Peerereignisse zu registrieren, rufen Sie PeerGroupRegisterEvent auf, und übergeben Sie einen oder mehrere der in PEER_GROUP_EVENT_TYPE definierten Peerereignistypen. 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 PEER_GROUP_EVENT_DIRECT_CONNECTION und PEER_GROUP_EVENT_INCOMING_DATA Ereignisse. Jeder Aufruf nimmt ein Ereignishandle an 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 dem Handle zugeordneten Peerereignisse nicht mehr registriert.

Erstellen von Administrator- und Mitgliedsrollen

Der Peer, der die Peergruppe erstellt, wird als Ersteller der Peergruppe bezeichnet und hat standardmäßig die Administratorrolle. Nur der Ersteller der Peergruppe kann die Gruppeneigenschaften festlegen.

Peers, die zur Peergruppe eingeladen werden, können entweder ein Administrator oder ein Mitglied sein. Wenn ihnen vom Administrator, der die Einladung ausgibt, eine Administratorrolle zugewiesen wird, können sie neue Mitglieder zur Peergruppe einladen und die Administratorrolle ebenfalls 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 den Wert des pRoles-Parameters von PeerGroupCreateInvitation auf PEER_GROUP_ROLE_ADMIN fest, wenn Sie eine Einladung erstellen.

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. Um einem teilnehmenden Peer member status zuzuweisen, legen Sie 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 diesem Mitglied neue Anmeldeinformationen ausgestellt werden, die die neue Rolle enthalten. Um dies zu erreichen, rufen Sie die PEER_CREDENTIAL_INFO-Struktur für dieses Element aus der PEER_MEMBER-Struktur ab, 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 abzurufen.

Suchen eines Peers

Um eine aufgezählte Liste aller Peers abzurufen, die an der Peergruppe teilnehmen, rufen Sie PeerGroupEnumMembers mit dem Gruppenhandle auf, wodurch ein Handle für die Enumeration zurückgegeben wird. Um die Member abzurufen, rufen Sie PeerGetNextItem mit dem Enumerationshandle und der Anzahl der abzurufenden Member auf. Fahren Sie mit dem Aufrufen 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 Mitglieder möglicherweise nicht zurückgegeben wird.

Jedes Element wird als PEER_MEMBER-Struktur dargestellt, die die Identität des Peers, Knoten-IDs und IP-Adressen für aktive Peers enthält.

Wenn Sie fertig sind, 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 initiiert, indem PeerGroupOpenDirectConnection aufgerufen und die Identität des anderen Peers bereitgestellt wird. Dieser Aufruf ist asynchron und gibt eine 64-Bit-Verbindungs-ID zurück. Wenn der Aufruf erfolgreich ist, erhalten Sie das PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT Peerereignis, um anzugeben, dass die Verbindung erfolgreich war. 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 auch der andere Peer zuvor für das PEER_GROUP_EVENT_DIRECT_CONNECTION Peerereignis registriert sein.

Um Daten an einen Peer zu senden, rufen Sie PeerGroupSendData mit einer gültigen Verbindungs-ID auf. Um Daten zu empfangen, muss der andere Peer für das PEER_GROUP_EVENT_INCOMING_DATA Peerereignis registriert werden. Wenn der sendende Peer wiederum Daten empfangen möchte, muss er auch für das PEER_GROUP_EVENT_INCOMING_DATA Peerereignis registriert werden.

Um die Gesamtzahl der derzeit aktiven direkten Verbindungen mit anderen Peers in einer Gruppe zu erhalten, rufen Sie PeerGroupEnumConnections auf, um die Enumeration zu öffnen und die Liste der Verbindungen mithilfe von PeerGetNextItem zu durchlaufen.

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 PeerGroupClose auf. Dadurch wird das Gruppenhandle ungültig, aber die Peergruppierungsinfrastruktur nicht heruntergefahren. Peer-to-Peer-Gruppendaten werden durch Aufrufen von PeerGroupDelete gelöscht.

Wenn die Anwendung mit der Peergruppierungsinfrastruktur fertig ist, muss sie PeerGroupShutdown aufrufen.