Comment se connecter à un groupe d’homologues

Cette rubrique explique comment une application se connecte à un groupe d’homologues à l’aide des API de regroupement d’homologues.

Jonction d’un groupe d’homologues

Pour rejoindre un groupe d’homologues, appelez PeerGroupJoin, en passant le nom d’identité de l’homologue et l’invitation (et un nom de cloud PNRP facultatif, si le nom du cloud dans l’invitation est ambigu).

En cas de réussite, PeerGroupJoin retourne un handle au groupe d’homologues.

Si l’homologue a précédemment rejoint le groupe d’homologues, puis fermé le handle, le groupe d’homologues doit être rouvert en appelant PeerGroupOpen et en transmettant le nom du groupe d’homologues. Cet appel retourne un nouveau handle de groupe d’homologues.

Une fois le groupe d’homologues correctement joint, il peut se connecter directement au groupe d’homologues et commencer à interagir en appelant PeerGroupConnect. Après la connexion, l’homologue est considéré comme « en ligne ».

Si une application n’interagit pas avec le groupe à ce moment-là, elle peut rester « hors connexion ». S’il choisit de participer directement au groupe d’homologues à un instance ultérieur, un appel ultérieur à PeerGroupConnect le mettra en ligne. Une fois qu’un homologue a rejoint le groupe d’homologues, il doit se connecter au moins une fois avant de pouvoir publier des enregistrements dans le groupe d’homologues.

Ouverture d’un groupe d’homologues sans connexion (hors connexion)

Souvent, vous souhaiterez peut-être qu’une application se connecte à un groupe d’homologues sans y participer directement, en recevant et en publiant des mises à jour d’enregistrements, mais pas en envoyant ou en recevant des messages de données. Une application est dans cet état « hors connexion » immédiatement après l’appel de PeerGroupCreate, PeerGroupJoin ou PeerGroupOpen .

Une application hors connexion peut être mise en ligne à tout moment en appelant PeerGroupConnect. Une fois connecté, un groupe d’homologues ne peut pas être déconnecté tant que toutes les autres applications associées à cette identité et au partage de ce groupe n’ont pas également des connexions fermées.

Un groupe d’homologues est une ressource partagée, avec le même groupe d’homologues disponible pour plusieurs applications. Si plusieurs applications pour la même identité et que l’utilisateur Windows utilise le même groupe d’homologues, ils partagent également la même base de données sous-jacente et les mêmes connexions (voisines et directes). Si l’une de ces applications appelle PeerGroupConnect, toutes les autres applications de cette identité/utilisateur participant au groupe se connectent également au groupe. Si un enregistrement est ajouté par une application alors que le groupe est hors connexion, d’autres applications peuvent également le voir. Par conséquent, une application doit être prête à être mise en ligne à tout moment.

Connexion à un groupe d’homologues (en ligne)

Pour commencer à participer à un groupe, appelez PeerGroupConnect après avoir créé, rejoint ou ouvert le groupe. Dans cet état, les connexions directes peuvent être ouvertes avec d’autres homologues participant au même groupe en appelant PeerGroupOpenDirectConnection.

Pour détecter si une tentative de connexion a échoué, inscrivez-vous à l’événement PEER_GROUP_EVENT_CONNECTION_FAILED. Cet événement est déclenché si l’infrastructure de regroupement ne trouve pas un autre membre auquel se connecter, ou si la connexion échoue avant la synchronisation de la base de données de groupe et qu’une autre connexion ne peut pas être établie.

Bien que plusieurs applications s’exécutant sur l’homologue et participant au même groupe avec la même identité d’homologue puissent être hors connexion, un appel à PeerGroupConnect par l’une des applications entraîne la mise en ligne de toutes les applications.

En outre, si une application sur l’homologue s’est connectée au groupe, toutes les autres applications qui appellent PeerGroupJoin ou PeerGroupOpen sont également immédiatement connectées. Si une application appelle PeerGroupClose, le handle est fermé uniquement pour cette application. Ainsi, un appel ultérieur à PeerGroupOpen par l’application retourne un nouveau handle de groupe, et l’application est mise en ligne immédiatement si d’autres applications participant au même groupe sont toujours connectées.

Envoi et réception de données

Pour envoyer et recevoir des données entre des nœuds membres spécifiques du groupe, des connexions directes doivent être établies avec les membres avec lesquels vous envisagez d’interagir. L’établissement d’une connexion directe est un appel asynchrone à PeerGroupOpenDirectConnection, en passant le handle d’un groupe connecté ainsi que l’identité de l’homologue au sein du groupe auquel vous souhaitez vous connecter. Cette méthode retourne un ID de connexion. Si l’appel réussit, un événement PEER_GROUP_EVENT_DIRECT_CONNECTION est déclenché sur l’homologue, validant l’ID de connexion.

Pour recevoir des connexions directes d’autres homologues en ligne, inscrivez-vous à l’événement PEER_GROUP_EVENT_DIRECT_CONNECTION avec un appel à PeerGroupRegisterEvent.

Une fois qu’une connexion directe a été établie, l’application peut commencer à envoyer des données avec des appels à PeerGroupSendData, en passant l’ID de connexion valide. L’ordre des transmissions de données en plusieurs parties est géré par PeerGroupSendData. Toutefois, les applications doivent implémenter une pile de protocoles appropriée pour gérer les données opaques retournées par cet appel d’API.

Pour recevoir des données via une connexion directe, l’application doit s’inscrire à l’événement PEER_GROUP_EVENT_INCOMING_DATA auprès de PeerGroupRegisterEvent. Le gestionnaire d’événements est responsable de l’obtention et de l’ordre des données opaques et de leur transmission à l’application. Ces données sont obtenues dans le gestionnaire d’événements en appelant PeerGroupGetEventData avec le handle aux événements inscrits.

Une connexion directe est fermée en appelant PeerGroupCloseDirectConnection et en transmettant l’ID de connexion obtenu par un appel précédent à PeerGroupOpenDirectConnection ou reçu dans les données d’événement pour PEER_EVENT_GROUP_DIRECT_CONNECTION.