Gestion des enregistrements de groupe

Un enregistrement de groupe est des données spécifiques publiées pour tous les membres actifs d’un groupe d’homologues, par exemple, un message de conversation ou une mise à jour status spécifique à l’application. Un enregistrement est représenté par la structure PEER_RECORD et contient les informations suivantes sur un homologue :

• L’ID d’enregistrement est une valeur qui identifie de manière unique un enregistrement dans le groupe d’homologues.
• GUID qui spécifie le type d’enregistrement. Les applications peuvent prendre en charge différents types d’enregistrements. Une application interprète le champ de données d’un enregistrement en fonction du type d’enregistrement. Certains GUID sont réservés et l’appel d’API retourne PEER_E_NOT_AUTHORIZED lorsque l’application tente de les utiliser.
• Ensemble d’attributs d’enregistrement décrits sous forme de chaîne XML. Les attributs sont utilisés lors de la recherche d’enregistrements. Pour plus d’informations sur les attributs, consultez Record Attribute Schema.
• Heure de création d’un enregistrement par l’homologue.
• Heure d’expiration d’un enregistrement par l’homologue.
• Heure de modification d’un enregistrement par l’homologue.
• Créateur d’un enregistrement.
• Membre qui modifie un enregistrement.
• Structure PEER_DATA qui contient la signature de chiffrement pour tous les champs de cette structure PEER_RECORD . Ce champ ne peut pas être directement mis à jour ou modifié par un homologue.
• Une structure PEER_DATA qui contient les données spécifiques à l’application associées à cet enregistrement sous forme d’un tableau d’octets. Le type de données présentes dans ce champ est déterminé par le type d’enregistrement défini par l’application.

Obtention d’enregistrements de groupe d’homologues

Les enregistrements individuels sont obtenus en appelant PeerGroupGetRecord avec l’ID de l’enregistrement. Lors du traitement de tous les enregistrements d’un type spécifique, l’ensemble énuméré de tous les enregistrements de groupe d’homologues actuels est obtenu en appelant d’abord PeerGroupEnumRecords pour ouvrir l’énumération, puis en appelant de manière itérative PeerGetNextItem jusqu’à ce que tous les enregistrements soient récupérés. Lorsque vous avez terminé, fermez l’énumération et libérez la mémoire qui lui est associée en appelant PeerEndEnumeration.

Lorsqu’un enregistrement est créé, supprimé ou mis à jour par un homologue, l’enregistrement affecté est publié sur tous les membres du groupe d’homologues par le biais de l’événement PEER_GROUP_EVENT_RECORD_CHANGE . Notez que si un homologue n’est pas connecté au groupe, il recevra l’enregistrement mis à jour, puis la prochaine fois qu’il se connectera. Il est important de s’inscrire à cet événement auprès de PeerGroupRegisterEvent si votre application conserve ou gère les enregistrements de manière significative. L’application peut également interroger la base de données d’enregistrements à la demande à l’aide de PeerGroupSearchRecords.

Lorsque l’événement PEER_GROUP_EVENT_RECORD_CHANGE est déclenché, l’ID et le type d’enregistrement spécifiques, ainsi que le type de modification (ajouter, mettre à jour, supprimer) sont reçus en tant que structure PEER_EVENT_RECORD_CHANGE_DATA . Cette structure est obtenue avec un appel à PeerGroupGetEventData. Si la modification est un ajout ou une mise à jour, vous devez utiliser PeerGroupGetRecord pour obtenir l’enregistrement avec l’ID fourni. La base de données d’enregistrements locale de l’infrastructure est mise à jour automatiquement.

Vous pouvez également rechercher des enregistrements spécifiques en fonction d’attributs personnalisés spécifiques fournis dans le champ pwzAttributes de PEER_RECORD, ainsi que d’attributs prédéfinis. Pour ce faire, utilisez la fonction PeerGroupSearchRecords avec une requête de recherche XML au format spécifié dans la rubrique Format de requête recherche d’enregistrements .

Pour plus d’informations sur l’utilisation des enregistrements dans l’infrastructure homologue, reportez-vous à la rubrique Enregistrements dans Utilisation de l’infrastructure d’homologue.

Administration des enregistrements de groupe d’homologues

Lorsque les invitations initiales sont émises par le créateur du groupe d’homologues, il peut spécifier que certains membres servent dans un rôle administratif (PEER_GROUP_ROLE_ADMIN) chaque fois qu’il émet de nouvelles informations d’identification à l’utilisateur (via PeerGroupCreateInvitation ou PeerGroupIssueCredentials). Un administrateur peut ajouter, supprimer et mettre à jour directement tous les enregistrements de groupe d’homologues. À l’inverse, un membre du groupe d’homologues dont le rôle est défini sur PEER_GROUP_ROLE_MEMBER ou PEER_GROUP_ROLE_INVITING_MEMBER peut uniquement ajouter, mettre à jour et supprimer ses propres enregistrements.

Le créateur a le rôle d’administrateur par défaut.

Pour mettre à jour un enregistrement, obtenez l’enregistrement avec PeerGroupGetRecord ou PeerGroupEnumRecords, apportez les modifications et transmettez l’enregistrement mis à jour à PeerGroupUpdateRecord.

Pour supprimer un enregistrement, passez l’ID d’enregistrement à supprimer à PeerGroupDeleteRecord.

Pour ajouter un enregistrement, créez une structure PEER_RECORD et renseignez les champs suivants :

• dwSize. Ce champ contient la valeur sizeof(PEER_RECORD).
• ftExpiration. Ce champ contient la date et l’heure d’expiration de cet enregistrement, exprimées en heure d’homologue sous forme de structure FILETIME.
• type. Ce champ contient une valeur GUID qui identifie le type d’enregistrement de l’application. Si ce type est personnalisé pour votre infrastructure d’application, vous devez également remplir le champ de données .

Les champs suivants sont renseignés par l’infrastructure et seront ignorés s’ils sont définis par l’application :

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

Les champs restants sont facultatifs. Pour ajouter ce nouvel enregistrement au groupe d’homologues, passez-le à PeerGroupAddRecord.

Importation et exportation d’enregistrements

Les enregistrements de groupe d’égal à égal sont conservés localement en tant que base de données. Pour enregistrer une instantané actuelle de la base de données d’enregistrements de groupe d’homologues dans un fichier local, appelez PeerGroupExportDatabase et passez-lui le handle au groupe d’homologues. Ce fichier peut ensuite être transporté vers un autre ordinateur ou une autre application, qui peut extraire et utiliser cette base de données d’enregistrements en appelant PeerGroupImportDatabase.