Comment utiliser des groupes

Le regroupement d’homologues est une technologie qui permet aux développeurs de créer rapidement et efficacement un réseau d’homologues sécurisé. La liste suivante identifie les principales considérations à prendre en compte lors de la création d’une application de regroupement d’homologues.

• Obtention d’une identité d’homologue
• Démarrage d’un groupe d’homologues
• Inscription aux événements de regroupement
• Connexion à un groupe
• Création de rôles d’administrateur et de membre
• Recherche d’un homologue
• Connexion directe à un homologue
• Fermeture et arrêt d’un groupe

Obtention d’une identité d’homologue

Avant de créer ou de se connecter à un groupe, un homologue doit obtenir une identité d’homologue, qui est un nom utilisé pour identifier de manière unique un homologue à un groupe. Pour obtenir une liste énumérée de toutes les identités d’homologue définies sur l’homologue, appelez PeerEnumIdentities, qui retourne un handle à l’énumération. Pour obtenir les identités d’homologues, appelez PeerGetNextItem avec le handle d’énumération et le nombre de membres à récupérer. Continuez à appeler PeerGetNextItem jusqu’à ce que le paramètre pCount retourne une valeur inférieure au nombre d’identités d’homologues demandées.

Si une identité d’homologue n’existe pas, elle peut être créée en appelant PeerIdentityCreate. Après avoir créé une identité d’homologue, l’homologue génère un objet blob XML d’identité qui contient la clé publique qui lui est affectée.

Les informations d’identité d’homologue sont obtenues en appelant PeerIdentityGetXML. Ces informations d’identité d’homologue sont utilisées par le créateur du groupe ou un administrateur pour émettre les informations d’identification nécessaires pour rejoindre le groupe, en tant qu’objet blob XML d’invitation.

Pour plus d’informations sur les identités d’homologues, reportez-vous à la documentation de l’API Identity Manager .

Démarrage de l’infrastructure de regroupement d’homologues

Avant qu’une fonction de l’API de regroupement d’homologues soit appelée par une application, PeerGroupStartup doit être appelé. Cette fonction initialise l’infrastructure de regroupement d’homologues pour l’application et définit la version prise en charge.

Obtention d’un handle de groupe

Pour se connecter à un groupe et commencer à participer, un handle à un groupe d’homologues doit être obtenu. La liste suivante identifie les trois façons de se connecter à un groupe d’homologues :

• Création d’un groupe d’homologues en appelant PeerGroupCreate, qui initialise un nouveau groupe d’homologues et retourne un handle valide avec l’homologue en tant que propriétaire et administrateur unique.
• Rejoindre un groupe d’homologues en appelant PeerGroupJoin. Pour rejoindre un groupe d’homologues, un homologue doit recevoir une invitation d’un administrateur de groupe d’homologues. Pour obtenir une invitation, envoyez l’objet blob XML d’informations d’identité à l’administrateur qui crée une invitation et vous l’envoie par un mécanisme externe, tel que l’e-mail ou FTP. L’invitation et l’identité d’homologue sont transmises à PeerGroupJoin, qui retourne un handle valide au groupe.
• Ouverture d’un groupe d’homologues qu’un homologue a joint précédemment en appelant PeerGroupOpen. Dans ce cas, il n’est pas nécessaire d’obtenir une invitation.

Une fois que vous avez obtenu un handle de groupe d’homologues valide à partir de l’une des fonctions ci-dessus, vous pouvez vous connecter à un groupe d’homologues en appelant PeerGroupConnect avec le nouveau handle.

Inscription aux événements de regroupement d’homologues

Avant qu’un homologue ne participe à un groupe d’homologues, il doit s’inscrire aux événements de groupe d’homologues. Pour vous inscrire à des événements homologues spécifiques, appelez PeerGroupRegisterEvent et transmettez un ou plusieurs des types d’événements homologues définis dans PEER_GROUP_EVENT_TYPE. Vous devez vous inscrire à chaque événement d’homologue qui s’applique à votre application ; par exemple, pour recevoir des données via une connexion directe, inscrivez-vous aux événements PEER_GROUP_EVENT_DIRECT_CONNECTION et PEER_GROUP_EVENT_INCOMING_DATA. Chaque appel prend un handle d’événement et retourne un handle HPEEREVENT pour cet événement homologue.

Les gestionnaires d’événements peuvent obtenir les données associées à un événement d’homologue en transmettant le handle aux événements homologues inscrits à PeerGroupGetEventData. Ces données d’événement homologue sont retournées en tant qu’union PEER_GROUP_EVENT_DATA. Si la file d’attente d’événements d’homologue est vide, cette fonction retourne PEER_S_NO_EVENT_DATA.

Vous pouvez annuler l’inscription pour les événements d’homologues en appelant PeerGroupUnregisterEvent et en fournissant le handle pour l’événement d’homologue que vous souhaitez désinscrire. Une fois la fonction appelée, les événements homologues associés au handle ne sont plus inscrits.

Création de rôles d’administrateur et de membre

L’homologue qui crée le groupe d’homologues est appelé créateur du groupe d’homologues et a le rôle d’administrateur par défaut. Seul le créateur du groupe d’homologues peut définir les propriétés du groupe.

Les homologues invités au groupe d’homologues peuvent être un administrateur ou un membre. S’ils se voient attribuer un rôle d’administrateur par l’administrateur qui émet l’invitation, ils peuvent inviter de nouveaux membres au groupe d’homologues et également attribuer le rôle d’administrateur à d’autres membres.

Les rôles des membres du groupe d’homologues sont définis dans les invitations que l’administrateur donne à un membre. Pour ajouter d’autres administrateurs, définissez la valeur du paramètre pRoles de PeerGroupCreateInvitation sur PEER_GROUP_ROLE_ADMIN lors de la création d’une invitation.

Les membres peuvent participer à un groupe d’homologues, mais ne peuvent pas inviter et autoriser de nouveaux membres, définir des propriétés de groupe ou mettre à jour ou supprimer des enregistrements de groupe qu’ils ne créent pas spécifiquement. Pour affecter des status membres à un homologue participant, définissez la valeur du paramètre pRoles de PeerGroupCreateInvitation sur PEER_GROUP_ROLE_MEMBER lorsque vous créez une invitation pour cet homologue.

Pour modifier le rôle d’un membre, de nouvelles informations d’identification contenant le nouveau rôle doivent être émises à ce membre. Pour ce faire, obtenez la structure PEER_CREDENTIAL_INFO de ce membre à partir de la structure PEER_MEMBER retournée par PeerGroupEnumMembers. Remplacez le champ pRoles dans PEER_CREDENTIAL_INFO par le nouveau rôle, puis passez la structure à PeerGroupIssueCredentials.

Les nouvelles informations d’identification n’entreront pas en vigueur pour l’homologue tant qu’ils ne se connecteront pas au groupe d’homologues. S’ils sont actuellement connectés, ils doivent fermer le groupe et se reconnecter pour obtenir les informations d’identification mises à jour.

Recherche d’un homologue

Pour obtenir une liste énumérée de tous les homologues participant au groupe d’homologues, appelez PeerGroupEnumMembers avec le handle de groupe, qui retourne un handle à l’énumération. Pour obtenir les membres, appelez PeerGetNextItem avec le handle d’énumération et le nombre de membres à récupérer. Continuez à appeler PeerGetNextItem jusqu’à ce que le paramètre pCount retourne une valeur inférieure au nombre de membres demandés. Notez que la liste complète des membres disponibles peut ne pas être retournée.

Chaque membre est représenté sous la forme d’une structure PEER_MEMBER , qui contient l’identité de l’homologue, les ID de nœud et les adresses IP des homologues actifs.

Lorsque vous avez terminé, fermez l’énumération et libérez la mémoire associée en appelant PeerEndEnumeration.

Connexion directe à un homologue

Lorsqu’un homologue est connecté à un groupe d’homologues, les échanges directs un-à-un avec d’autres membres connectés sont initiés en appelant PeerGroupOpenDirectConnection et en fournissant l’identité de l’autre homologue. Cet appel est asynchrone et retourne un ID de connexion 64 bits. Si l’appel réussit, vous recevez l’événement d’homologue PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT pour indiquer que la connexion a réussi. Si la connexion réussit, l’ID de connexion est valide et peut être utilisé pour envoyer et recevoir des données via la connexion directe.

Pour pouvoir recevoir des connexions directes, l’autre homologue doit également s’être déjà inscrit pour l’événement homologue PEER_GROUP_EVENT_DIRECT_CONNECTION.

Pour envoyer des données à un homologue, appelez PeerGroupSendData avec un ID de connexion valide. Pour recevoir des données, l’autre homologue doit être inscrit pour l’événement d’homologue PEER_GROUP_EVENT_INCOMING_DATA. De même, si l’homologue d’envoi souhaite recevoir des données à son tour, il doit également être inscrit pour l’événement PEER_GROUP_EVENT_INCOMING_DATA pair.

Pour recevoir le nombre total de connexions directes actuellement actives avec d’autres homologues d’un groupe, appelez PeerGroupEnumConnections pour ouvrir l’énumération et itérer dans la liste des connexions à l’aide de PeerGetNextItem.

Pour fermer une connexion directe, appelez PeerGroupCloseDirectConnection et transmettez l’ID de connexion.

Fermeture et arrêt d’un groupe d’homologues

Pour fermer une connexion à un groupe d’homologues, appelez PeerGroupClose, ce qui invalide le handle de groupe, mais n’arrête pas l’infrastructure de regroupement d’homologues. Les données de groupe d’égal à égal sont supprimées en appelant PeerGroupDelete.

Lorsque l’application a terminé d’utiliser l’infrastructure de regroupement d’homologues, elle doit appeler PeerGroupShutdown.