Gerenciando registros de grupo

Um registro de grupo são dados específicos publicados para todos os membros ativos de um grupo de pares, por exemplo, uma mensagem de chat ou uma atualização de status específica do aplicativo. Um registro é representado pela estrutura PEER_RECORD e contém as seguintes informações sobre um par:

• A ID do registro é um valor que identifica exclusivamente um registro no grupo de pares.
• Um GUID que especifica o tipo de registro. Os aplicativos podem dar suporte a diferentes tipos de registro. Um aplicativo interpreta o campo de dados de um registro com base no tipo de registro. Alguns GUIDs são reservados e a chamada à API retorna PEER_E_NOT_AUTHORIZED quando o aplicativo tenta usá-los.
• Um conjunto de atributos de registro descrito como uma cadeia de caracteres XML. Os atributos são usados ao pesquisar registros. Para obter mais informações sobre atributos, consulte Esquema de atributo de registro.
• A hora do par em que um registro é criado.
• A hora do par em que um registro expira.
• A hora do par em que um registro é modificado.
• O criador de um registro.
• O membro que modifica um registro.
• Uma estrutura PEER_DATA que contém a assinatura criptográfica para todos os campos nesta estrutura PEER_RECORD . Esse campo não pode ser atualizado ou alterado diretamente por um par.
• Uma estrutura PEER_DATA que contém os dados específicos do aplicativo associados a esse registro como uma matriz de bytes. O tipo de dados presente neste campo é determinado pelo tipo de registro definido pelo aplicativo.

Obtendo registros de grupo par

Registros individuais são obtidos chamando PeerGroupGetRecord com a ID do registro. Ao processar todos os registros de um tipo específico, o conjunto enumerado de todos os registros de grupo de pares atuais é obtido primeiro chamando PeerGroupEnumRecords para abrir a enumeração e, em seguida, chamando iterativamente PeerGetNextItem até que todos os registros sejam recuperados. Quando terminar, feche a enumeração e solte a memória associada a ela chamando PeerEndEnumeration.

Quando um registro é criado, excluído ou atualizado por um par, o registro afetado é publicado em todos os membros do grupo par por meio do evento PEER_GROUP_EVENT_RECORD_CHANGE . Observe que, se um par não estiver conectado ao grupo, ele receberá o registro atualizado e, na próxima vez, ele se conectará. É importante registrar-se para esse evento com PeerGroupRegisterEvent se o aplicativo mantiver ou gerenciar registros de alguma forma significativa. Como alternativa, o aplicativo pode consultar o banco de dados de registro sob demanda usando PeerGroupSearchRecords.

Quando o evento PEER_GROUP_EVENT_RECORD_CHANGE é gerado, a ID e o tipo de registro específicos, bem como o tipo de alteração (adicionar, atualizar, excluir) são recebidos como uma estrutura de PEER_EVENT_RECORD_CHANGE_DATA . Essa estrutura é obtida com uma chamada para PeerGroupGetEventData. Se a alteração for um suplemento ou uma atualização, você deverá usar PeerGroupGetRecord para obter o registro com a ID fornecida. O banco de dados de registro local para a infraestrutura é atualizado automaticamente.

Você também pode pesquisar registros específicos com base em atributos personalizados específicos fornecidos no campo pwzAttributes de PEER_RECORD, bem como quaisquer atributos predefinidos. Para fazer isso, use a função PeerGroupSearchRecords com uma consulta de pesquisa XML formatada conforme especificado no tópico Formato de Consulta de Pesquisa de Registros .

Para obter mais detalhes sobre como trabalhar com registros na Infraestrutura de Pares, consulte o tópico Registros em Usando a infraestrutura de pares.

Administração de registros de grupo par

Quando os convites iniciais são emitidos pelo criador do grupo de pares, ele pode especificar que determinados membros servem em uma função administrativa (PEER_GROUP_ROLE_ADMIN) sempre que ele emite novas credenciais para o usuário (por meio de PeerGroupCreateInvitation ou PeerGroupIssueCredentials). Um administrador tem a capacidade de adicionar, excluir e atualizar diretamente todos os registros de grupo par. Por outro lado, um membro de grupo par com sua função definida como PEER_GROUP_ROLE_MEMBER ou PEER_GROUP_ROLE_INVITING_MEMBER só pode adicionar, atualizar e excluir seus próprios registros.

O criador tem a função de administrador por padrão.

Para atualizar um registro, obtenha o registro com PeerGroupGetRecord ou PeerGroupEnumRecords, faça as alterações e passe o registro atualizado para PeerGroupUpdateRecord.

Para excluir um registro, passe a ID do registro a ser excluída para PeerGroupDeleteRecord.

Para adicionar um registro, crie uma nova estrutura PEER_RECORD e preencha os seguintes campos:

• dwSize. Esse campo contém o valor de sizeof(PEER_RECORD).
• ftExpiration. Esse campo contém a data e a hora de expiração desse registro, expressos em tempo de par como uma estrutura FILETIME .
• tipo. Esse campo contém um valor GUID que identifica o tipo de registro para o aplicativo. Se esse tipo for personalizado para sua infraestrutura de aplicativo, você também deverá preencher o campo de dados .

Os seguintes campos são preenchidos pela infraestrutura e serão ignorados se definidos pelo aplicativo:

• id
• pwzCreatorId
• pwzLastModifiedById
• ftCreation
• ftLastModified
• securityData

Os campos restantes são opcionais. Para adicionar esse novo registro ao grupo de pares, passe-o para PeerGroupAddRecord.

Importando e exportando registros

Os registros de grupo ponto a ponto são mantidos localmente como um banco de dados. Para salvar uma instantâneo atual do banco de dados de registro de grupo par em um arquivo local, chame PeerGroupExportDatabase e passe o identificador para o grupo de pares. Esse arquivo pode então ser transportado para um computador ou aplicativo diferente, que pode extrair e usar esse banco de dados de registro chamando PeerGroupImportDatabase.