Partilhar via

Como trabalhar com grupos

  • Artigo

O Agrupamento ponto a ponto é uma tecnologia que permite que um desenvolvedor crie uma rede de pares segura de forma rápida e eficaz. A lista a seguir identifica as principais considerações na criação de um aplicativo de agrupamento de pares.

Obtendo uma identidade de par

Antes de criar ou se conectar a um grupo, um par deve obter uma identidade de par, que é um nome usado para identificar exclusivamente um par para um grupo. Para obter uma lista enumerada de todas as identidades de pares definidas no par, chame PeerEnumIdentities, que retorna um identificador para a enumeração. Para obter as identidades de pares, chame PeerGetNextItem com o identificador de enumeração e o número de membros a serem recuperados. Continue chamando PeerGetNextItem até que o parâmetro pCount retorne um valor menor que o número de identidades de pares solicitadas.

Se uma identidade de par para o par não existir, ela poderá ser criada chamando PeerIdentityCreate. Depois de criar uma identidade de par, o par gera um blob XML de identidade que contém a chave pública atribuída a ele

As informações de identidade de par são obtidas chamando PeerIdentityGetXML. Essas informações de identidade de par são usadas pelo criador do grupo ou um administrador para emitir as credenciais necessárias para ingressar no grupo, como um blob XML de convite.

Para obter mais informações sobre identidades de pares, consulte a documentação da API do Identity Manager

Iniciando a infraestrutura de agrupamento de pares

Antes que qualquer função na API de Agrupamento de Pares seja chamada por um aplicativo, PeerGroupStartup deve ser chamado. Essa função inicializa a Infraestrutura de Agrupamento de Pares para o aplicativo e define a versão com suporte.

Obtendo um identificador de grupo

Para se conectar a um grupo e começar a participar, um identificador para um grupo de pares deve ser obtido. A lista a seguir identifica as três maneiras de se conectar a um grupo de pares:

  • Criando um grupo de pares chamando PeerGroupCreate, que inicializa um novo grupo de pares e retorna um identificador válido com o par como proprietário e único administrador.
  • Ingressar em um grupo de pares chamando PeerGroupJoin. Para ingressar em um grupo de pares, um par deve receber um convite de um administrador de grupo par. Para obter um convite, envie o blob XML de informações de identidade para o administrador que cria um convite e o envia por um mecanismo externo, como email ou FTP. O convite e a identidade de par são passados para PeerGroupJoin, que retorna um identificador válido para o grupo.
  • Abrindo um grupo de pares que um par ingressou anteriormente chamando PeerGroupOpen. Nessa situação, a obtenção de um convite não é necessária.

Depois de obter um identificador de grupo par válido de uma das funções acima, você pode se conectar a um grupo de pares chamando PeerGroupConnect com o novo identificador.

Observação

Se a conexão com um grupo par falhar, o evento PEER_GROUP_EVENT_CONNECTION_FAILED ocorrerá. O manipulador pode tentar restabelecer a conexão com o grupo de pares.

 

Registrando-se para eventos de agrupamento de pares

Antes que um par participe de um grupo de pares, o par deve se registrar para eventos de grupo par. Para se registrar em eventos par específicos, chame PeerGroupRegisterEvent e passe um ou mais dos tipos de evento par definidos em PEER_GROUP_EVENT_TYPE. Você deve se registrar para cada evento par que se aplica ao seu aplicativo; por exemplo, para receber dados em uma conexão direta, registre-se para os eventos PEER_GROUP_EVENT_DIRECT_CONNECTION e PEER_GROUP_EVENT_INCOMING_DATA. Cada chamada usa um identificador de evento e retorna um identificador HPEEREVENT para esse evento par.

Os manipuladores de eventos podem obter os dados associados a um evento par passando o identificador para eventos de pares registrados para PeerGroupGetEventData. Esses dados de evento par são retornados como uma união PEER_GROUP_EVENT_DATA. Se a fila de eventos par estiver vazia, essa função retornará PEER_S_NO_EVENT_DATA.

Você pode cancelar o registro de eventos de pares chamando PeerGroupUnregisterEvent e fornecendo o identificador para o evento par que deseja cancelar o registro. Depois que a função é chamada, os eventos de par associados ao identificador não são mais registrados.

Criando funções de administrador e membro

O par que cria o grupo de pares é conhecido como o criador do grupo de pares e tem a função de administrador por padrão. Somente o criador do grupo par pode definir as propriedades do grupo.

Os pares convidados para o grupo de pares podem ser um administrador ou um membro. Se eles receberem uma função de administrador pelo administrador que está emitindo o convite, eles poderão convidar novos membros para o grupo par e atribuir a função de administrador a outros membros.

As funções dos membros do grupo de pares são definidas nos convites que o administrador fornece a um membro. Para adicionar mais administradores, defina o valor do parâmetro pRoles de PeerGroupCreateInvitation como PEER_GROUP_ROLE_ADMIN ao criar um convite.

Os membros podem participar de um grupo de pares, mas não podem convidar e autorizar novos membros, definir propriedades de grupo ou atualizar ou excluir registros de grupo que eles não criam especificamente. Para atribuir status membro a um par participante, defina o valor do parâmetro pRoles de PeerGroupCreateInvitation como PEER_GROUP_ROLE_MEMBER quando você criar um convite para esse par.

Para alterar a função de um membro, novas credenciais que contêm a nova função devem ser emitidas para esse membro. Para fazer isso, obtenha a estrutura PEER_CREDENTIAL_INFO para esse membro da estrutura PEER_MEMBER retornada por PeerGroupEnumMembers. Altere o campo pRoles em PEER_CREDENTIAL_INFO para a nova função e passe a estrutura para PeerGroupIssueCredentials.

As novas credenciais não entrarão em vigor para o par até que elas se conectem ao grupo de pares. Se estiverem conectados no momento, eles deverão fechar o grupo e reconectar-se para obter as credenciais atualizadas.

Localizando um par

Para obter uma lista enumerada de todos os pares que participam do grupo par, chame PeerGroupEnumMembers com o identificador de grupo, que retorna um identificador para a enumeração. Para obter os membros, chame PeerGetNextItem com o identificador de enumeração e o número de membros a serem recuperados. Continue chamando PeerGetNextItem até que o parâmetro pCount retorne um valor menor que o número de membros solicitados. Observe que a lista completa de membros disponíveis pode não ser retornada.

Cada membro é representado como uma estrutura PEER_MEMBER , que contém a identidade do par, IDs de nó e endereços IP para pares ativos.

Quando terminar, feche a enumeração e libere a memória associada chamando PeerEndEnumeration.

Conectando-se diretamente a um par

Quando um par está conectado a um grupo de pares, as trocas diretas um para um com outros membros conectados são iniciadas chamando PeerGroupOpenDirectConnection e fornecendo a identidade do outro par. Essa chamada é assíncrona e retorna uma ID de conexão de 64 bits. Se a chamada for bem-sucedida, você receberá o evento par PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT para indicar que a conexão foi bem-sucedida. Se a conexão for bem-sucedida, a ID da conexão será válida e poderá ser usada para enviar e receber dados por meio da conexão direta.

Para poder receber conexões diretas, o outro par também deve ter se registrado anteriormente para o evento par PEER_GROUP_EVENT_DIRECT_CONNECTION.

Para enviar dados a um par, chame PeerGroupSendData com uma ID de conexão válida. Para receber dados, o outro par deve ser registrado para o evento par PEER_GROUP_EVENT_INCOMING_DATA. Da mesma forma, se o par de envio quiser receber dados por sua vez, ele também deverá ser registrado para o evento par PEER_GROUP_EVENT_INCOMING_DATA.

Para receber o conjunto total de conexões diretas ativas no momento com outros pares em um grupo, chame PeerGroupEnumConnections para abrir a enumeração e iterar por meio da lista de conexões usando PeerGetNextItem.

Para fechar uma conexão direta, chame PeerGroupCloseDirectConnection e passe a ID da conexão.

Fechando e desligando um grupo de pares

Para fechar uma conexão com um grupo de pares, chame PeerGroupClose, que invalida o identificador de grupo, mas não desliga a Infraestrutura de Agrupamento de Pares. Os dados de grupo ponto a ponto são excluídos chamando PeerGroupDelete.

Quando o aplicativo terminar de usar a Infraestrutura de Agrupamento de Pares, ele deverá chamar PeerGroupShutdown.