Jak pracować z grupami

Grupowanie peer-to-peer to technologia umożliwiająca programiście szybkie i efektywne tworzenie bezpiecznej sieci peer-to-peer. Poniższa lista prezentuje główne kwestie związane z tworzeniem aplikacji do grupowania rówieśniczego.

• Uzyskiwanie tożsamości rówieśniczej
• Rozpoczęcie grupy rówieśniczej
• Rejestracja na wydarzenia grupowe
• Nawiązywanie połączenia z grupą
• Tworzenie Ról Administratora i Członków
• Znajdowanie rówieśnika
• Bezpośrednie połączenie z rówieśnikiem
• Zamykanie i likwidacja grupy

Uzyskiwanie tożsamości równorzędnej

Przed utworzeniem lub nawiązaniem połączenia z grupą element równorzędny musi uzyskać tożsamość elementu równorzędnego, która jest nazwą używaną do unikatowego identyfikowania elementu równorzędnego z grupą. Aby uzyskać wyliczoną listę wszystkich tożsamości rówieśników zdefiniowanych na rówieśniku, wywołaj metodę PeerEnumIdentities, która zwraca uchwyt do wyliczenia. Aby uzyskać identyfikatory równorzędnych, wywołaj metodę PeerGetNextItem z uchwytem wyliczania i liczbą członków do pobrania. Kontynuuj wywoływanie PeerGetNextItem, dopóki parametr pCount zwróci wartość mniejszą niż liczba żądanych tożsamości równorzędnych.

Jeśli tożsamość elementu równorzędnego dla elementu równorzędnego nie istnieje, można ją utworzyć, wywołując metodę PeerIdentityUtwórz. Po utworzeniu tożsamości równorzędnej element równorzędny generuje obiekt blob XML tożsamości zawierający przypisany do niego klucz publiczny

Informacje o tożsamości rówieśnika są uzyskiwane przez wywołanie PeerIdentityGetXML. Informacje o tożsamości uczestnika są używane przez twórcę grupy lub administratora do wydawania poświadczeń potrzebnych do dołączenia do grupy w postaci obiektu XML zaproszenia.

Aby uzyskać więcej informacji na temat tożsamości partnerów, proszę zapoznać się z dokumentacją interfejsu API usługi Identity Manager

Uruchamianie infrastruktury grupowania partnerskiego

Przed wywołaniem dowolnej funkcji w interfejsie API grupowania elementów równorzędnych przez aplikację należy wywołać PeerGroupStartup. Ta funkcja inicjuje infrastrukturę grupowania równorzędnego dla aplikacji i ustawia obsługiwaną wersję.

Uzyskiwanie dojścia grupy

Aby nawiązać połączenie z grupą i rozpocząć uczestnictwo, należy uzyskać dojście do grupy równorzędnej. Poniższa lista identyfikuje trzy sposoby nawiązywania połączenia z grupą równorzędną:

• Tworzenie grupy równorzędnej przez wywołanie PeerGroupCreate, który inicjuje nową grupę równorzędną i zwraca prawidłowy uchwyt, ustanawiając element równorzędny jako jej właściciela i jedynego administratora.
• Dołączanie do grupy równorzędnej przez wywołanie PeerGroupJoin. Aby dołączyć do grupy, uczestnik musi otrzymać zaproszenie od administratora grupy. Aby uzyskać zaproszenie, wyślij obiekt blob XML informacji o tożsamości do administratora, który tworzy zaproszenie i wysyła je do Ciebie za pomocą mechanizmu zewnętrznego, takiego jak poczta e-mail lub FTP. Tożsamość zaproszenia i elementu równorzędnego jest przekazywana do PeerGroupJoin, która zwraca prawidłowy uchwyt do grupy.
• Otwarcie grupy równorzędnej, do której wcześniej dołączył równorzędny, wywołując PeerGroupOpen. W takiej sytuacji uzyskanie zaproszenia nie jest konieczne.

Po uzyskaniu prawidłowego uchwytu grupy równorzędnej z jednej z powyższych funkcji można nawiązać połączenie z grupą równorzędną, wywołując PeerGroupConnect przy użyciu nowego uchwytu.

Rejestrowanie na wydarzenia grupowe

Zanim członek uczestniczy w grupie, musi zarejestrować się na wydarzenia grupowe. Aby zarejestrować się na konkretne wydarzenia peer-to-peer, wywołaj PeerGroupRegisterEventi przekaż co najmniej jeden z typów wydarzeń zdefiniowanych w PEER_GROUP_EVENT_TYPE. Musisz zarejestrować się dla każdego zdarzenia równorzędnego, które ma zastosowanie do aplikacji; na przykład aby odbierać dane za pośrednictwem połączenia bezpośredniego, zarejestruj się na potrzeby zdarzeń PEER_GROUP_EVENT_DIRECT_CONNECTION i PEER_GROUP_EVENT_INCOMING_DATA. Każde wywołanie przyjmuje dojście zdarzeń i zwraca dojścia HPEEREVENT dla tego zdarzenia równorzędnego.

Programy obsługi zdarzeń mogą uzyskać dane skojarzone ze zdarzeniem równorzędnym, przekazując dojście do zarejestrowanych zdarzeń równorzędnych do PeerGroupGetEventData. Te dane dotyczące zdarzenia równorzędnego są zwracane jako unia PEER_GROUP_EVENT_DATA. Jeśli kolejka zdarzeń równorzędnych jest pusta, ta funkcja zwraca PEER_S_NO_EVENT_DATA.

Możesz wyrejestrować zdarzenia równorzędne, wywołując PeerGroupUnregisterEvent i podając dojście dla zdarzenia elementu równorzędnego, które chcesz wyrejestrować. Po wywołaniu funkcji zdarzenia powiązane z uchwytem nie są już zarejestrowane.

Tworzenie ról administratorów i członków

Element równorzędny, który tworzy grupę równorzędną, jest znany jako twórca grupy równorzędnej i ma domyślnie rolę administratora. Tylko twórca grupy kolegów może ustawić właściwości grupy.

Równorzędni zaproszeni do grupy równorzędnej mogą być administratorem lub członkiem. Jeśli mają przypisaną rolę administratora przez administratora wystawiającego zaproszenie, mogą zapraszać nowych członków do grupy równorzędnej, a także przypisywać rolę administratora innym członkom.

Role członków grupy równorzędnej są ustawiane w zaproszeniach, które administrator daje członkowi. Aby dodać więcej administratorów, ustaw wartość parametru pRolesPeerGroupCreateInvitation na PEER_GROUP_ROLE_ADMIN podczas tworzenia zaproszenia.

Członkowie mogą uczestniczyć w grupie równorzędnej, ale nie mogą zapraszać i autoryzować nowych członków, ustawiać właściwości grupy lub aktualizować lub usuwać rekordy grupy, które nie są specjalnie tworzone. Aby przypisać status członka do uczestniczącego węzła, ustaw wartość parametru pRolesPeerGroupCreateInvitation na PEER_GROUP_ROLE_MEMBER podczas tworzenia zaproszenia dla tego węzła.

Aby zmienić rolę członka, nowe poświadczenia zawierające nową rolę muszą zostać wystawione dla tego członka. Aby to osiągnąć, uzyskaj strukturę PEER_CREDENTIAL_INFO dla tego członka ze struktury PEER_MEMBER zwróconej przez PeerGroupEnumMembers. Zmień pole pRoles w PEER_CREDENTIAL_INFO na nową rolę i przekaż strukturę do PeerGroupIssueCredentials.

Nowe poświadczenia nie zostaną wprowadzone dla elementu równorzędnego, dopóki nie połączą się z grupą równorzędną. Jeśli są one obecnie połączone, muszą zamknąć grupę i ponownie nawiązać połączenie, aby uzyskać zaktualizowane poświadczenia.

Znajdowanie rówieśnika

Aby uzyskać wyliczona lista wszystkich elementów równorzędnych uczestniczących w grupie równorzędnej, wywołaj metodę PeerGroupEnumMembers z uchwytem grupy, który zwraca dojście do wyliczenia. Aby uzyskać elementy członkowskie, wywołaj metodę PeerGetNextItem z uchwytem wyliczenia i liczbą elementów członkowskich do pobrania. Kontynuuj wywoływanie PeerGetNextItem, dopóki parametr pCount zwróci wartość mniejszą niż liczba żądanych elementów. Należy pamiętać, że pełna lista dostępnych członków może nie zostać zwrócona.

Każdy członek jest reprezentowany jako struktura PEER_MEMBER, która zawiera tożsamość elementu równorzędnego, identyfikatory węzłów i adresy IP dla aktywnych członków.

Po zakończeniu zamknij wyliczenie i zwolnij skojarzoną pamięć, wywołując PeerEndEnumeration.

Nawiązywanie połączenia bezpośrednio z rówieśnikiem

Gdy element równorzędny jest połączony z grupą równorzędną, bezpośrednie wymiany jeden do jednego z innymi połączonymi członkami są inicjowane przez wywołanie PeerGroupOpenDirectConnection i podanie tożsamości innego elementu równorzędnego. To wywołanie jest asynchroniczne i zwraca 64-bitowy identyfikator połączenia. Jeśli wywołanie jest udane, otrzymasz zdarzenie równorzędne PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT, aby wskazać, że doszło do połączenia. Jeśli połączenie zakończy się pomyślnie, identyfikator połączenia jest prawidłowy i może służyć do wysyłania i odbierania danych za pośrednictwem połączenia bezpośredniego.

Aby można było odbierać połączenia bezpośrednie, drugi równorzędny musi również być wcześniej zarejestrowany dla zdarzenia PEER_GROUP_EVENT_DIRECT_CONNECTION równorzędnego.

Aby wysłać dane do partnera, wywołaj PeerGroupSendData z prawidłowym identyfikatorem połączenia. Aby odbierać dane, inny element równorzędny musi być zarejestrowany dla zdarzenia PEER_GROUP_EVENT_INCOMING_DATA równorzędnego. Podobnie, jeśli wysyłający węzeł równorzędny chce z kolei odbierać dane, musi również być zarejestrowany na zdarzenie równorzędne PEER_GROUP_EVENT_INCOMING_DATA.

Aby otrzymać łączny zestaw aktualnie aktywnych połączeń bezpośrednich z innymi elementami równorzędnymi w grupie, wywołaj PeerGroupEnumConnections, aby otworzyć wyliczenie i iterować listę połączeń przy użyciu PeerGetNextItem.

Aby zamknąć połączenie bezpośrednie, wywołaj PeerGroupCloseDirectConnection i przekaż identyfikator połączenia.

Zamykanie i zamykanie grupy równorzędnej

Aby zamknąć połączenie z grupą równorzędną, wywołaj metodę PeerGroupClose, która unieważnia uchwyt grupy, ale nie zamyka infrastruktury grupowania elementów równorzędnych. Dane grupy równorzędnej są usuwane przez wywołanie metody PeerGroupDelete.

Po zakończeniu korzystania z infrastruktury grupowania równorzędnego aplikacja musi wywołać PeerGroupShutdown.