Поделиться через

Как работать с группами

  • Статья

Одноранговая группировка — это технология, которая позволяет разработчику быстро и эффективно создавать безопасную одноранговую сеть. В следующем списке приведены основные рекомендации по созданию однорангового приложения группирования.

Получение однорангового удостоверения

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

Если однорангового удостоверения для однорангового узла не существует, его можно создать, вызвав PeerIdentityCreate. После создания однорангового удостоверения одноранговый узел создает BLOB-объект ИДЕНТИФИКАТОРа XML, содержащий назначенный ему открытый ключ.

Сведения об удостоверении однорангового узла получаются путем вызова PeerIdentityGetXML. Эти сведения об удостоверениях одноранговых узлов используются создателем группы или администратором для выдачи учетных данных, необходимых для присоединения к группе, в качестве БОЛЬШОго двоичного объекта XML приглашения.

Дополнительные сведения об удостоверениях одноранговых узлов см. в документации по API Identity Manager .

Запуск инфраструктуры одноранговой группировки

Перед вызовом какой-либо функции в API одноранговой группировки приложением необходимо вызвать PeerGroupStartup . Эта функция инициализирует инфраструктуру одноранговой группировки для приложения и задает поддерживаемую версию.

Получение дескриптора группы

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

  • Создание одноранговой группы путем вызова PeerGroupCreate, который инициализирует новую одноранговую группу и возвращает допустимый дескриптор с одноранговым элементом в качестве владельца и единственного администратора.
  • Присоединение одноранговой группы путем вызова PeerGroupJoin. Чтобы присоединиться к одноранговой группе, одноранговый узел должен получить приглашение от администратора группы одноранговых узлов. Чтобы получить приглашение, отправьте БОЛЬШОЙ двоичный объект XML сведений об удостоверении администратору, который создает приглашение и отправляет его вам с помощью внешнего механизма, например электронной почты или FTP. Приглашение и удостоверение однорангового узла передаются в PeerGroupJoin, который возвращает допустимый дескриптор группе.
  • Открытие одноранговой группы, к которым ранее присоединился одноранговый узел, путем вызова PeerGroupOpen. В этом случае получение приглашения не требуется.

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

Примечание

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

 

Регистрация для событий одноранговой группировки

Прежде чем одноранговый узел примет участие в одноранговой группе, одноранговый узел должен зарегистрироваться для получения событий одноранговой группы. Чтобы зарегистрироваться для определенных одноранговых событий, вызовите PeerGroupRegisterEvent и передайте один или несколько типов одноранговых событий, определенных в PEER_GROUP_EVENT_TYPE. Необходимо зарегистрироваться для каждого однорангового события, которое применяется к вашему приложению; например, чтобы получить данные по прямому подключению, зарегистрируйтесь для PEER_GROUP_EVENT_DIRECT_CONNECTION и PEER_GROUP_EVENT_INCOMING_DATA событий. Каждый вызов принимает дескриптор события и возвращает дескриптор HPEEREVENT для этого однорангового события.

Обработчики событий могут получить данные, связанные с одноранговым событием, передав дескриптор зарегистрированным одноранговым событиям в PeerGroupGetEventData. Эти данные одноранговых событий возвращаются в виде PEER_GROUP_EVENT_DATA объединения. Если очередь одноранговых событий пуста, эта функция возвращает PEER_S_NO_EVENT_DATA.

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

Создание ролей администратора и участника

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

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

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

Участники могут участвовать в одноранговой группе, но не могут приглашать и авторизовать новых участников, задавать свойства группы, обновлять или удалять записи группы, которые они специально не создают. Чтобы назначить одноранговой системе статус участника, задайте для параметра pRolespeerGroupCreateInvitation значение PEER_GROUP_ROLE_MEMBER при создании приглашения для этого однорангового узла.

Чтобы изменить роль участника, ей должны быть выданы новые учетные данные, содержащие новую роль. Для этого получите структуру PEER_CREDENTIAL_INFO для этого элемента из структуры PEER_MEMBER, возвращаемой PeerGroupEnumMembers. Измените поле pRoles в PEER_CREDENTIAL_INFO на новую роль и передайте структуру в PeerGroupIssueCredentials.

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

Поиск однорангового узла

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

Каждый элемент представлен в виде структуры PEER_MEMBER , которая содержит удостоверения однорангового узла, идентификаторы узлов и IP-адреса активных одноранговых узлов.

По завершении закройте перечисление и освободите связанную память, вызвав PeerEndEnumeration.

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

Когда одноранговый узел подключен к одноранговой группе, прямой обмен данными "один к одному" с другими подключенными членами инициируется путем вызова PeerGroupOpenDirectConnection и предоставления удостоверения другого однорангового узла. Этот вызов является асинхронным и возвращает 64-разрядный идентификатор подключения. Если вызов выполнен успешно, вы получите событие однорангового узла PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT, указывающее на успешное подключение. Если подключение установлено успешно, идентификатор подключения является допустимым и может использоваться для отправки и получения данных через прямое подключение.

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

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

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

Чтобы закрыть прямое подключение, вызовите PeerGroupCloseDirectConnection и передайте идентификатор подключения.

Закрытие и завершение одноранговой группы

Чтобы закрыть подключение к одноранговой группе, вызовите PeerGroupClose, который делает дескриптор группы недействительным, но не завершает работу инфраструктуры одноранговой группировки. Одноранговые данные группы удаляются путем вызова PeerGroupDelete.

Когда приложение завершит работу с инфраструктурой одноранговой группировки, оно должно вызвать PeerGroupShutdown.