Подключение к одноранговой группе

В этом разделе описывается, как приложение подключается к одноранговой группе с помощью API одноранговой группировки.

Присоединение к одноранговой группе

Чтобы присоединиться к одноранговой группе, вызовите PeerGroupJoin, передавая имя однорангового узла и приглашение, а также необязательное имя облака PNRP, если имя облака в приглашении неоднозначно.

В случае успешного выполнения PeerGroupJoin возвращает дескриптор одноранговой группы.

Если одноранговый узел ранее присоединился к группе одноранговых узлов, а затем закрыл дескриптор, группа однорангового узла должна быть повторно открыта путем вызова PeerGroupOpen и передачи имени группы одноранговых узлов. Этот вызов возвращает новый идентификатор одноранговой сети.

После успешного присоединения к группе одноранговых узлов одноранговый узел может подключиться непосредственно к группе одноранговых узлов и начать взаимодействие с помощью вызова PeerGroupConnect. После подключения одноранговый узел считается "в сети".

Если приложение не будет взаимодействовать с группой в то время, оно может оставаться автономным. Если она решит позже участвовать непосредственно в одноранговой группе, последующий вызов PeerGroupConnect подключит её к сети. После того как одноранговый узел присоединился к группе одноранговых узлов, он должен подключиться по крайней мере один раз, прежде чем он сможет публиковать записи в одноранговую группу.

Открытие одноранговой группы без подключения (в автономном режиме)

Часто может потребоваться подключение приложения к одноранговой группе, но не участвовать непосредственно в ней — получать и публиковать обновления записей, но не отправлять или получать сообщения с данными. Приложение находится в этом состоянии "вне сети" сразу после вызова PeerGroupCreate, PeerGroupJoinили PeerGroupOpen.

Автономное приложение может перейти в онлайн в любое время с помощью вызова PeerGroupConnect. После подключения одноранговая группа не сможет перейти в автономный режим, пока все остальные приложения, связанные с этим удостоверением и использующие эту группу, не закроют подключения к ней.

Одноранговая группа — это общий ресурс, та же одноранговая группа доступна для нескольких приложений. Если более одного приложения для одной и той же учетной записи и пользователя Windows используют одну и ту же одноранговую группу, они также делят одну и ту же базовую базу данных и подключения (соседние и прямые). Если одно из этих приложений вызывает PeerGroupConnect, все остальные приложения для этого удостоверения или пользователя, участвующие в группе, также подключаются к группе. Если запись добавляется одним приложением во время автономной работы группы, другие приложения также смогут видеть его. В результате приложение должно быть готово к работе в Интернете в любое время.

Подключение к одноранговой группе (в Сети)

Чтобы начать участие в группе, вызовите PeerGroupConnect после создания, присоединения или открытия группы. В этом состоянии прямые подключения можно открывать с другими одноранговыми узлами, участвующими в той же группе, путем вызова PeerGroupOpenDirectConnection.

Чтобы определить, не удалось ли выполнить попытку подключения, зарегистрируйтесь для события PEER_GROUP_EVENT_CONNECTION_FAILED. Это событие возникает, если инфраструктура группирования не может найти другого члена для подключения, или если подключение завершается сбоем до синхронизации базы данных группы, а другое подключение невозможно установить.

Хотя несколько приложений, выполняемых на одноранговом узле и участвующих в одной группе с одним и тем же удостоверением однорангового узла, могут находиться в автономном режиме, вызов PeerGroupConnect любым из приложений приводит к тому, что все приложения становятся активными.

Кроме того, если одно приложение на одноранговом узле подключено к группе, все другие приложения, которые вызывают PeerGroupJoin или PeerGroupOpen также подключены. Если приложение вызывает PeerGroupClose, дескриптор закрывается только для этого приложения. Таким образом, последующий вызов PeerGroupOpen приложением возвращает новый дескриптор группы, и приложение подключается к сети немедленно, если любое другое приложение, участвующее в той же группе, всё ещё подключено.

Отправка и получение данных

Для отправки и получения данных между определенными узлами-членами в группе необходимо установить прямые подключения с этими участниками, с которыми вы планируете взаимодействовать. Установка прямого подключения — это асинхронный вызов PeerGroupOpenDirectConnection, передача дескриптора для подключенной группы, а также идентификатора однорангового узла в группе, к которой вы хотите подключиться. Этот метод вернет идентификатор подключения. Если вызов выполнен успешно, событие PEER_GROUP_EVENT_DIRECT_CONNECTION вызывается на одноранговом узле, проверяя идентификатор подключения.

Чтобы получить прямые подключения от других сетевых одноранговых узлов, зарегистрируйтесь для события PEER_GROUP_EVENT_DIRECT_CONNECTION с вызовом PeerGroupRegisterEvent.

После успешного установления прямого подключения приложение может начать вызывать PeerGroupSendDataдля отправки данных, используя действительный идентификатор подключения. Порядок передачи многокомпонентных данных обрабатывается PeerGroupSendData. Однако приложения должны реализовать правильный стек протоколов для обработки непрозрачных данных, возвращаемых этим вызовом API.

Чтобы получить данные через прямое подключение, приложение должно зарегистрировать событие PEER_GROUP_EVENT_INCOMING_DATA с помощью PeerGroupRegisterEvent. Обработчик событий отвечает за получение и упорядочивание непрозрачных данных и передачу его приложению. Эти данные получаются в обработчике событий путем вызова PeerGroupGetEventData с дескриптором зарегистрированных событий.

Прямое подключение закрывается путем вызова PeerGroupCloseDirectConnection и передачи идентификатора подключения, который был получен в результате предыдущего вызова PeerGroupOpenDirectConnection или из данных события для PEER_EVENT_GROUP_DIRECT_CONNECTION.