Como trabalhar com grupos

O agrupamento peer-to-peer é uma tecnologia que permite a um programador criar uma rede peer 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 mesmo nível
• Formando um Grupo de Pares
• Registar-se para eventos de agrupamento
• Ligar-se a um grupo
• Criação de funções de administrador e membro
• Encontrar um colega
• Conectando-se diretamente a um de mesmo nível
• Fechar e encerrar um grupo

Obtendo uma identidade de mesmo nível

Antes de criar ou conectar-se a um grupo, um par deve obter uma identidade de par, que é um nome usado para identificar de forma única um par num 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 mesmo nível, chame PeerGetNextItem com o identificador de enumeração e o número de membros a serem recuperados. Continue a chamar PeerGetNextItem até que o parâmetro pCount retorne um valor menor do que o número de identidades de pares solicitadas.

Se uma identidade de mesmo nível 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 si.

As informações de identidade de mesmo nível são obtidas chamando PeerIdentityGetXML. Essas informações de identidade de mesmo nível são usadas pelo criador do grupo ou por 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 mesmo nível, consulte a documentação da API do Identity Manager

Iniciando a infraestrutura de agrupamento de pares

Antes de qualquer função na API de agrupamento de pares ser chamada por um aplicativo, PeerGroupStartup deve ser chamada. Esta função inicializa a infraestrutura de agrupamento de pares para o aplicativo e define a versão suportada.

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 administrador único.
• Entrar em um grupo de pares chamando PeerGroupJoin. Para ingressar em um grupo de pares, um colega deve receber um convite de um administrador de grupo de pares. Para obter um convite, envie o blob XML de informações de identidade para o administrador que cria um convite e o envia para você por um mecanismo externo, como e-mail ou FTP. O convite e a identidade de mesmo nível são passados para PeerGroupJoin, que retorna um identificador válido para o grupo.
• Abrir um grupo de pares ao qual um colega se juntou anteriormente chamando PeerGroupOpen. Nesta situação, não é necessário obter um convite.

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

Registrando-se em eventos de agrupamento de pares

Antes de um colega participar num grupo de pares, deve-se registar para os eventos do grupo. Para se inscrever em eventos de par específicos, chame PeerGroupRegisterEvente forneça um ou mais tipos de evento de par definidos em PEER_GROUP_EVENT_TYPE. Deve registar-se para cada evento de pares que se aplique à sua candidatura; Por exemplo, para receber dados através de uma ligação direta, registe-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 de HPEEREVENT para esse evento de mesmo nível.

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

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

Criação de 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 de pares pode definir as propriedades do grupo.

Os pares convidados para o grupo de pares podem ser um administrador ou um membro. Se lhes for atribuída uma função de administrador pelo administrador que emite o convite, podem convidar novos membros para o grupo de pares e, da mesma forma, 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 faz a um membro. Para adicionar mais administradores, defina o valor do parâmetro pRoles de PeerGroupCreateInvitation para 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 do grupo ou atualizar ou excluir registros de grupo que eles não criam especificamente. Para atribuir o estatuto de membro a um peer participante, defina o valor do parâmetro pRoles de PeerGroupCreateInvitation para PEER_GROUP_ROLE_MEMBER quando criar um convite para esse peer.

Para alterar a função de um membro, novas credenciais contendo a nova função devem ser emitidas para esse membro. Para concretizar este objetivo, obtenha a estrutura PEER_CREDENTIAL_INFO relativa a este membro a partir da estrutura PEER_MEMBER, que é 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 ele se conecte ao grupo de pares. Se eles estiverem conectados no momento, eles devem fechar o grupo e se reconectar para obter as credenciais atualizadas.

Encontrar um par

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

Cada membro é representado como uma estrutura de 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 de mesmo nível PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT para indicar que a conexão foi bem-sucedida. Se a conexão for bem-sucedida, o ID de conexão é válido e pode ser usado 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 previamente para o evento de pares PEER_GROUP_EVENT_DIRECT_CONNECTION.

Para enviar dados para um par, chame PeerGroupSendData com uma ID de conexão válida. Para receber dados, o outro par deve estar registado para o evento de par PEER_GROUP_EVENT_INCOMING_DATA. Da mesma forma, se o peer remetente quiser também receber dados, ele deve estar registado para o evento PEER_GROUP_EVENT_INCOMING_DATA do peer.

Para receber o conjunto total de ligações diretas atualmente ativas com outros pares num grupo, chame PeerGroupEnumConnections para abrir a enumeração e percorrer a lista de ligações usando PeerGetNextItem.

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

Fechando e encerrando 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 encerra a Infraestrutura de Agrupamento de Pares. Os dados do 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.