Infrastructure des événements homologues

Article
06/13/2023

L’infrastructure d’homologue utilise des événements pour informer les applications des modifications qui se sont produites au sein d’un réseau homologue, par exemple, un nœud ajouté ou supprimé d’un graphique. Les infrastructures Peer Graphing et Peer Grouping utilisent l’infrastructure d’événements homologues.

Réception d’une notification d’événement d’homologue

Un homologue peut s’inscrire pour recevoir une notification lorsqu’un attribut d’un graphique ou d’un groupe change ou qu’un événement homologue spécifique se produit. Une application homologue appelle la fonction PeerGraphRegisterEvent ou PeerGroupRegisterEvent et transmet un handle d’événement à l’infrastructure d’homologue, qui est créée précédemment par un appel à CreateEvent. L’infrastructure d’homologue utilise le handle pour signaler à une application qu’un événement d’homologue s’est produit.

L’application transmet également une série de structures PEER_GRAPH_EVENT_REGISTRATION ou PEER_GROUP_EVENT_REGISTRATION qui indiquent à l’infrastructure d’homologue les événements homologues spécifiques pour lesquels l’application demande une notification. L’application doit également spécifier exactement le nombre de structures passées.

Événements de graphiques d’homologues

Une application Peer Graphing peut s’inscrire pour recevoir une notification pour 9 événements de graphique homologue. Chaque nom d’événement est préfacé avec PEER_GRAPH_EVENT_, par exemple , PEER_GRAPH_STATUS_CHANGED. Sauf indication contraire, les informations relatives à une modification sont récupérées à l’aide de PeerGraphGetEventData.

PEER_GRAPH_EVENT_STATUS_CHANGED indique que la status d’un graphique est modifiée, par exemple, un nœud a été synchronisé avec un graphe.
PEER_GRAPH_EVENT_PROPERTY_CHANGED indique qu’une propriété d’un graphique ou d’un groupe est modifiée, par exemple, le nom convivial d’un graphique a changé.

Notes

L’application doit appeler PeerGraphGetProperties pour obtenir les informations modifiées.
PEER_GRAPH_EVENT_RECORD_CHANGED indique qu’un enregistrement est modifié, par exemple, un enregistrement est supprimé.
PEER_GRAPH_EVENT_DIRECT_CONNECTION indique qu’une connexion directe est modifiée, par exemple, un nœud s’est connecté.
PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION indique qu’une connexion à un nœud voisin est modifiée, par exemple, un nœud s’est connecté.
PEER_GRAPH_EVENT_INCOMING_DATA indique que des données ont été reçues à partir d’une connexion directe ou voisine.
PEER_GRAPH_EVENT_CONNECTION_REQUIRED indique que l’infrastructure Graphing nécessite une nouvelle connexion.

Notes

Un appel à PeerGraphConnect se connecte à un nouveau nœud. Un appel à PeerGraphGetEventData ne retourne pas de données.
PEER_GRAPH_EVENT_NODE_CHANGED indique que les informations de présence du nœud sont modifiées, par exemple, une adresse IP a changé.
PEER_GRAPH_EVENT_SYNCHRONIZED indique qu’un type d’enregistrement spécifique est synchronisé.

Une fois qu’une application reçoit une notification indiquant qu’un événement d’homologue s’est produit, l’application appelle PeerGraphGetEventData et transmet le handle d’événement homologue retourné par PeerGraphRegisterEvent. L’infrastructure homologue retourne un pointeur vers une structure PEER_GRAPH_EVENT_DATA qui contient les données demandées. Cette fonction doit être appelée jusqu’à ce que PEER_S_NO_EVENT_DATA soit retourné.

Une fois qu’une application n’a pas besoin d’une notification d’événement d’homologue, l’application appelle PeerGraphUnregisterEvent et transmet le handle d’événement homologue retourné par PeerGraphRegisterEvent lors de l’inscription de l’application.

Gestion des références de connexion graph

Lorsque PeerGraphConnect est appelé, l’homologue de connexion est averti de la réussite ou de l’échec via l’événement PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION asynchrone. Si la connexion a échoué en raison d’un problème de mise en réseau spécifique (par exemple, un pare-feu mal configuré), l’événement PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION est déclenché, la status de connexion étant définie sur PEER_CONNECTION_FAILED.

Toutefois, lorsqu’un homologue reçoit une référence lorsqu’il tente de se connecter à un nœud occupé, le PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION est déclenché sur l’homologue de connexion, la status de connexion étant définie sur PEER_CONNECTION_FAILED. L’homologue de connexion peut être référencé vers un autre nœud qui est lui-même occupé et peut envoyer une référence, et le même événement et status sont déclenchés sur l’homologue de connexion. Cette chaîne de références qui aboutit à des états d’événement PEER_CONNECTION_FAILED peut se poursuivre jusqu’à ce que le nombre maximal de tentatives de connexion ait été épuisé. L’homologue ne dispose pas d’un mécanisme permettant de déterminer la différence entre une tentative de connexion complète et la référence de connexion.

Pour résoudre ce problème, les développeurs doivent envisager d’utiliser le graphe homologue status les événements de modification pour déterminer si la tentative de connexion a été effectuée. Si l’événement n’est pas reçu dans un délai spécifique, l’application peut supposer que l’homologue de connexion est référencé et que l’application homologue doit considérer la tentative de connexion comme un échec.

Événements de regroupement d’homologues

Une application de regroupement d’homologues peut s’inscrire pour recevoir une notification pour 8 événements homologues. Chaque nom d’événement est préfacé avec PEER_GROUP_EVENT_ ; par exemple, PEER_GROUP_EVENT_STATUS_CHANGED. Sauf indication contraire, les informations relatives à une modification sont récupérées à l’aide de PeerGroupGetEventData.

PEER_GROUP_EVENT_STATUS_CHANGED indique que le groupe status a changé. Il existe deux valeurs status possibles : PEER_GROUP_STATUS_LISTENING, qui indique que le groupe n’a pas de connexions et attend de nouveaux membres; et PEER_GROUP_STATUS_HAS CONNEXIONS, qui indique que le groupe dispose d’au moins une connexion. Cette valeur status peut être obtenue en appelant PeerGroupGetStatus une fois cet événement déclenché.
PEER_GROUP_EVENT_PROPERTY_CHANGED indique que les propriétés du groupe ont été modifiées ou mises à jour par le créateur du groupe.
PEER_GROUP_EVENT_RECORD_CHANGED indique qu’une opération d’enregistrement a été effectuée. Cet événement est déclenché lorsqu’un homologue participant au groupe publie, met à jour ou supprime un enregistrement. Par exemple, cet événement est déclenché lorsqu’une application de conversation envoie un message de conversation.
PEER_GROUP_EVENT_MEMBER_CHANGED indique que la status d’un membre au sein du groupe a changé. Les modifications d’état sont les suivantes :
- PEER_MEMBER_CONNECTED. Un homologue s’est connecté au groupe.
- PEER_MEMBER_DISCONNECTED. Un homologue s’est déconnecté du groupe.
- PEER_MEMBER_JOINED. De nouvelles informations d’appartenance ont été publiées pour un homologue.
- PEER_MEMBER_UPDATED. Un homologue a été mis à jour avec de nouvelles informations, telles qu’une nouvelle adresse IP.
PEER_GROUP_EVENT_NEIGHBOR_CONNECTION. Les pairs qui participeront aux connexions voisines au sein du groupe doivent s’inscrire à cet événement. Notez que l’inscription à cet événement ne permet pas à l’homologue de recevoir des données ; l’inscription pour cet événement garantit une notification uniquement lorsqu’une demande de connexion voisine est reçue.
PEER_GROUP_EVENT_DIRECT_CONNECTION. Les pairs qui participeront à des connexions directes au sein du groupe doivent s’inscrire à cet événement. Notez que l’inscription à cet événement ne permet pas à l’homologue de recevoir des données ; l’inscription pour cet événement garantit une notification uniquement lorsqu’une demande de connexion directe est reçue.
PEER_GROUP_EVENT_INCOMING_DATA. Les pairs qui recevront des données via une connexion directe ou voisine doivent s’inscrire à cet événement. Lorsque cet événement est déclenché, les données opaques transmises par l’autre homologue participant peuvent être obtenues en appelant PeerGroupGetEventData. Notez que pour recevoir cet événement, l’homologue doit s’être déjà inscrit pour PEER_GROUP_EVENT_DIRECT_CONNECTION ou PEER_GROUP_EVENT_NEIGHBOR_CONNECTION.
PEER_GROUP_EVENT_CONNECTION_FAILED. Une connexion a échoué pour une raison quelconque. Aucune donnée n’est fournie lorsque cet événement est déclenché et PeerGroupGetEventData ne doit pas être appelé.

Une fois qu’une application reçoit une notification indiquant qu’un événement d’homologue s’est produit (à l’exception de PEER_GROUP_EVENT_CONNECTION_FAILED), l’application appelle PeerGroupGetEventData et transmet le handle d’événement d’homologue retourné par PeerGroupRegisterEvent. L’infrastructure homologue retourne un pointeur vers une structure PEER_GROUP_EVENT_DATA qui contient les données demandées. Cette fonction doit être appelée jusqu’à ce que PEER_S_NO_EVENT_DATA soit retourné. Lorsqu’une application n’a plus besoin de notification pour un événement d’homologue, un appel doit être effectué à PeerGroupUnregisterEvent, en passant le handle d’événement d’homologue retourné par PeerGroupRegisterEvent lorsque l’application s’est inscrite pour l’événement particulier.

Exemple d’inscription pour des événements de graphes homologues

L’exemple de code suivant vous montre comment vous inscrire avec les événements Peer Graphing.

//-----------------------------------------------------------------------------
// Function: RegisterForEvents
//
// Purpose:  Registers the EventCallback function so it can be called for only
//           the events that are specified.
//
// Returns:  HRESULT
//
HRESULT RegisterForEvents()
{
    HPEEREVENT  g_hPeerEvent = NULL;        // The one PeerEvent handle
    HANDLE      g_hEvent = NULL;            // Handle signaled by Graphing when we have an event
    HRESULT hr = S_OK;
    PEER_GRAPH_EVENT_REGISTRATION regs[] = {
        { PEER_GRAPH_EVENT_RECORD_CHANGED, 0 },
        { PEER_GRAPH_EVENT_NODE_CHANGED,   0 },
        { PEER_GRAPH_EVENT_STATUS_CHANGED, 0 },
        { PEER_GRAPH_EVENT_DIRECT_CONNECTION, 0 },
        { PEER_GRAPH_EVENT_INCOMING_DATA, 0 },
    };

    g_hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
    if (g_hEvent == NULL)
    {
        wprintf(L"CreateEvent call failed.\n");
        hr = E_OUTOFMEMORY;
    }
    else
    {
        hr = PeerGraphRegisterEvent(g_hGraph, g_hEvent, celems(regs), regs,  &g_hPeerEvent);
        if (FAILED(hr))
        {
           wprintf(L"PeerGraphRegisterEvent call failed.\n");
            CloseHandle(g_hEvent);
            g_hEvent = NULL;
        }
    }

    if (SUCCEEDED(hr))
    {
        if (!RegisterWaitForSingleObject(&g_hWait, g_hEvent, EventCallback, NULL, INFINITE, WT_EXECUTEDEFAULT))
        {
            hr = HRESULT_FROM_WIN32(GetLastError());
            wprintf(L"Could not set up event callback.\n");
            CloseHandle(g_hEvent);
            g_hEvent = NULL;
        }
    }

    return hr;
}

Partager via