Jak nawiązać połączenie z grupą partnerską

W tym temacie omówiono sposób łączenia aplikacji z grupą równorzędną przy użyciu interfejsów API grupowania równorzędnego.

Dołączanie do grupy równorzędnej

Aby dołączyć do grupy równorzędnej, wywołaj PeerGroupJoin, przekazując nazwę tożsamości elementu równorzędnego i zaproszenie (oraz opcjonalną nazwę chmury PNRP, jeśli nazwa chmury w zaproszeniu jest niejednoznaczna).

Jeśli operacja powiedzie się, PeerGroupJoin zwraca uchwyt do grupy równorzędnej.

Jeśli element równorzędny wcześniej dołączył do grupy równorzędnej, a następnie zamknął dojście, należy ponownie otworzyć grupę równorzędną, wywołując PeerGroupOpen i podając nazwę grupy równorzędnej. To wywołanie zwraca nowy uchwyt grupy równorzędnej.

Po pomyślnym dołączeniu do grupy równorzędnej, równorzędny uczestnik może połączyć się bezpośrednio z grupą równorzędną i rozpocząć interakcję, wywołując PeerGroupConnect. Po nawiązaniu połączenia rówieśnik jest uznawany za "online".

Jeśli aplikacja nie będzie wchodzić w interakcje z grupą w tym czasie, może pozostać "w trybie offline". Jeśli zdecyduje się na bezpośrednie uczestnictwo w grupie równorzędnej w późniejszym czasie, kolejne wywołanie PeerGroupConnect spowoduje przełączenie go do trybu online. Po dołączeniu rówieśnika do grupy równorzędnej, musi on połączyć się z grupą przynajmniej raz, zanim będzie mógł publikować rekordy.

Otwieranie grupy współpracowników bez łączenia (w trybie offline)

Często możesz chcieć, aby aplikacja łączyła się z grupą równorzędną, ale nie bezpośrednio uczestniczyła w niej, odbierając i publikując aktualizacje rekordów, ale nie wysyłała ani nie odbierała komunikatów o danych. Aplikacja znajduje się w stanie "offline" natychmiast po wywołaniu PeerGroupCreate, PeerGroupJoinlub PeerGroupOpen.

Aplikacja w trybie offline może przejść do trybu online w dowolnym momencie, wywołując PeerGroupConnect. Po nawiązaniu połączenia grupa równorzędna nie może przejść do trybu offline, dopóki wszystkie inne aplikacje skojarzone z tą tożsamością i dzielące tę grupę również zamknęły połączenia z tą grupą.

Grupa rówieśnicza jest wspólnym zasobem, który jest dostępny dla wielu aplikacji. Jeśli więcej niż jedna aplikacja używająca tej samej tożsamości i użytkownika systemu Windows korzysta z tej samej grupy równorzędnej, to współużytkuje tę samą bazową bazę danych oraz połączenia (sąsiednie i bezpośrednie). Jeśli którakolwiek z tych aplikacji wywołuje PeerGroupConnect, wszystkie pozostałe aplikacje związane z daną tożsamością/użytkownikiem uczestniczącym w grupie również łączą się z grupą. Jeśli rekord jest dodawany przez jedną aplikację, gdy grupa jest w trybie offline, inne aplikacje również będą mogły je zobaczyć. W związku z tym aplikacja musi być gotowa do pracy w trybie online w dowolnym momencie.

Nawiązywanie połączenia z grupą równorzędną (online)

Aby rozpocząć uczestnictwo w grupie, wywołaj PeerGroupConnect po utworzeniu, dołączeniu lub otwarciu grupy. W tym stanie bezpośrednie połączenia można otwierać z innymi elementami równorzędnymi uczestniczącymi w tej samej grupie, wywołując PeerGroupOpenDirectConnection.

Aby wykryć, czy próba połączenia nie powiodła się, zarejestruj się na zdarzenie PEER_GROUP_EVENT_CONNECTION_FAILED. To zdarzenie jest zgłaszane, jeśli infrastruktura grupowania nie może odnaleźć innego elementu członkowskiego do nawiązania połączenia lub jeśli połączenie nie powiedzie się przed zsynchronizowaniem bazy danych grupy i nie można ustanowić innego połączenia.

Mimo że wiele aplikacji działających na urządzeniu równorzędnym i uczestniczących w tej samej grupie z tą samą tożsamością równorzędną może być offline, wywołanie PeerGroupConnect przez jedną z aplikacji powoduje, że wszystkie aplikacje stają się online.

Ponadto, jeśli jedna aplikacja na równorzędnym węźle połączyła się z grupą, wszystkie inne aplikacje, które wywołają PeerGroupJoin lub PeerGroupOpen, również są natychmiast połączone. Jeśli aplikacja wywołuje PeerGroupClose, dojście jest zamykane tylko dla tej aplikacji. W związku z tym kolejne wywołanie PeerGroupOpen przez aplikację zwraca nowy uchwyt grupy, a aplikacja zostanie przeniesiona w tryb online natychmiast, jeśli inne aplikacje uczestniczące w tej samej grupie będą nadal połączone.

Wysyłanie i odbieranie danych

Aby wysyłać i odbierać dane między określonymi węzłami członkowskimi w grupie, należy ustanowić bezpośrednie połączenia z tymi członkami, z którymi zamierzasz się komunikować. Ustanawianie połączenia bezpośredniego to asynchroniczne wywołanie funkcji PeerGroupOpenDirectConnection, przekazując dojście dla połączonej grupy, a także tożsamość węzła równorzędnego w grupie, z którym chcesz nawiązać połączenie. Ta metoda zwróci identyfikator połączenia. Jeśli wywołanie zakończy się pomyślnie, generowane jest zdarzenie PEER_GROUP_EVENT_DIRECT_CONNECTION na węźle, walidując identyfikator połączenia.

Aby odbierać bezpośrednie połączenia od innych użytkowników online, zarejestruj się na zdarzenie PEER_GROUP_EVENT_DIRECT_CONNECTION przez wywołanie PeerGroupRegisterEvent.

Po pomyślnym nawiązaniu bezpośredniego połączenia aplikacja może rozpocząć wysyłanie danych z wywołaniami do PeerGroupSendData, przekazując prawidłowy identyfikator połączenia. Kolejność wieloczęściowych transmisji danych jest obsługiwana przez PeerGroupSendData. Jednak aplikacje powinny zaimplementować prawidłowy stos protokołu do obsługi nieprzezroczystych danych zwracanych przez to wywołanie interfejsu API.

Aby odbierać dane za pośrednictwem połączenia bezpośredniego, aplikacja musi zarejestrować zdarzenie PEER_GROUP_EVENT_INCOMING_DATA za pomocą PeerGroupRegisterEvent. Obsługiwarka zdarzeń jest odpowiedzialna za uzyskiwanie i porządkowanie danych nieprzezroczystych oraz przekazywanie ich do aplikacji. Te dane są uzyskiwane w programie obsługi zdarzeń przez wywołanie PeerGroupGetEventData z dojściem do zarejestrowanych zdarzeń.

Bezpośrednie połączenie jest zamykane przez wywołanie PeerGroupCloseDirectConnection i przekazanie identyfikatora połączenia, który został uzyskany w wyniku wcześniejszego wywołania funkcji PeerGroupOpenDirectConnection lub otrzymany w danych zdarzenia dla PEER_EVENT_GROUP_DIRECT_CONNECTION.