Infrastructuur voor peer-gebeurtenissen

Artikel
03/13/2025

De peer-infrastructuur maakt gebruik van gebeurtenissen om toepassingen op de hoogte te stellen van wijzigingen die zijn opgetreden in een peernetwerk, bijvoorbeeld een knooppunt dat wordt toegevoegd aan of verwijderd uit een grafiek. De Peer Graphing- en Peer Grouping Infrastructuren maken gebruik van de infrastructuur voor peer-gebeurtenissen.

Melding van peer-gebeurtenis ontvangen

Een peer kan zich registreren om een melding te ontvangen wanneer een kenmerk van een grafiek of groep verandert, of een specifieke peer-gebeurtenis plaatsvindt. Een peertoepassing roept de PeerGraphRegisterEvent- of PeerGroupRegisterEvent functie aan en geeft een gebeurtenisgreep door aan de peer-infrastructuur, die eerder is gemaakt door een aanroep naar CreateEvent. De Peer Infrastructure gebruikt de ingang om een toepassing aan te geven die een peergebeurtenis heeft plaatsgevonden.

De toepassing geeft ook een reeks PEER_GRAPH_EVENT_REGISTRATION- of PEER_GROUP_EVENT_REGISTRATION structuren door die aangeven aan de peer-infrastructuur welke specifieke peer-gebeurtenissen waarvoor de toepassing een melding aanvraagt. De toepassing moet ook precies opgeven hoeveel structuren worden doorgegeven.

Peer Graphing-gebeurtenissen

Een Peer Graphing-toepassing kan zich registreren voor het ontvangen van meldingen voor 9 peer graph-gebeurtenissen. Elke gebeurtenisnaam wordt voorafgegaan door PEER_GRAPH_EVENT_, bijvoorbeeld PEER_GRAPH_STATUS_CHANGED. Tenzij anders vermeld, wordt informatie over een wijziging opgehaald met behulp van PeerGraphGetEventData.

PEER_GRAPH_EVENT_STATUS_CHANGED geeft aan dat de status van een grafiek wordt gewijzigd, bijvoorbeeld dat een knooppunt is gesynchroniseerd met een grafiek.
PEER_GRAPH_EVENT_PROPERTY_CHANGED geeft aan dat een eigenschap van een grafiek of groep wordt gewijzigd, bijvoorbeeld de beschrijvende naam van een grafiek is gewijzigd.

Notitie

De toepassing moet PeerGraphGetProperties- aanroepen om de gewijzigde informatie te verkrijgen.
PEER_GRAPH_EVENT_RECORD_CHANGED geeft aan dat een record wordt gewijzigd, bijvoorbeeld een record wordt verwijderd.
PEER_GRAPH_EVENT_DIRECT_CONNECTION geeft aan dat er een directe verbinding is gewijzigd, bijvoorbeeld dat er een knooppunt is verbonden.
PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION geeft aan dat een verbinding met een buurknooppunt is gewijzigd, bijvoorbeeld dat er een knooppunt is verbonden.
PEER_GRAPH_EVENT_INCOMING_DATA geeft aan dat gegevens zijn ontvangen van een directe of naburige verbinding.
PEER_GRAPH_EVENT_CONNECTION_REQUIRED geeft aan dat voor de Graphing Infrastructure een nieuwe verbinding is vereist.

Notitie

Een aanroep van PeerGraphConnect maakt verbinding met een nieuw knooppunt. Een aanroep van PeerGraphGetEventData retourneert geen gegevens.
PEER_GRAPH_EVENT_NODE_CHANGED geeft aan dat aanwezigheidsgegevens voor knooppunten worden gewijzigd, bijvoorbeeld een IP-adres is gewijzigd.
PEER_GRAPH_EVENT_SYNCHRONIZED geeft aan dat een specifiek recordtype wordt gesynchroniseerd.

Nadat een toepassing een melding heeft ontvangen dat er een peergebeurtenis is opgetreden, roept de toepassing PeerGraphGetEventData-aan en geeft de peergebeurtenisgreep door die wordt geretourneerd door PeerGraphRegisterEvent-. De peer-infrastructuur retourneert een aanwijzer naar een PEER_GRAPH_EVENT_DATA structuur die de aangevraagde gegevens bevat. Deze functie moet worden aangeroepen totdat PEER_S_NO_EVENT_DATA wordt geretourneerd.

Nadat voor een toepassing geen peergebeurtenismelding is vereist, roept de toepassing PeerGraphUnregisterEvent-aan en geeft de peergebeurtenisgreep door die wordt geretourneerd door PeerGraphRegisterEvent wanneer de toepassing is geregistreerd.

Grafiekverbindingsverwijzingen verwerken

Wanneer PeerGraphConnect- wordt aangeroepen, wordt de verbindingspeer op de hoogte gesteld van geslaagd of mislukt via de asynchrone PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION gebeurtenis. Als de verbinding is mislukt vanwege een specifieke netwerkproblemen (zoals een onjuist geconfigureerde firewall), wordt de PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION gebeurtenis gegenereerd, waarbij de verbindingsstatus is ingesteld op PEER_CONNECTION_FAILED.

Wanneer een peer echter een verwijzing ontvangt wanneer deze verbinding probeert te maken met een bezet knooppunt, wordt de PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION gegenereerd op de verbindingspeer, waarbij de verbindingsstatus is ingesteld op PEER_CONNECTION_FAILED. De verbindingspeer kan worden verwezen naar een ander knooppunt dat bezet is en een verwijzing kan verzenden, en dezelfde gebeurtenis en status worden gegenereerd op de verbindingspeer. Deze keten van verwijzingen die resulteren in PEER_CONNECTION_FAILED gebeurtenisstatussen kunnen worden voortgezet totdat het maximum aantal verbindingspogingen is uitgeput. De peer heeft geen mechanisme om het verschil te bepalen tussen een volledige verbindingspoging en de verbindingsverwijzing.

Om dit probleem op te lossen, moeten ontwikkelaars overwegen om de wijzigingsgebeurtenissen van de peergrafiekstatus te gebruiken om te bepalen of de verbindingspoging is uitgevoerd. Als de gebeurtenis niet binnen een bepaalde tijd wordt ontvangen, kan de toepassing ervan uitgaan dat de verbindingspeering wordt verwezen en dat de peertoepassing rekening moet houden met de verbindingspoging.

Gebeurtenissen voor peergroepering

Een peergroeperingstoepassing kan zich registreren voor het ontvangen van meldingen voor 8 peer-gebeurtenissen. Elke gebeurtenisnaam wordt voorafgegaan door PEER_GROUP_EVENT_; bijvoorbeeld PEER_GROUP_EVENT_STATUS_CHANGED. Tenzij anders vermeld, wordt informatie over een wijziging opgehaald met behulp van PeerGroupGetEventData.

PEER_GROUP_EVENT_STATUS_CHANGED geeft aan dat de groepsstatus is gewijzigd. Er zijn twee statuswaarden mogelijk: PEER_GROUP_STATUS_LISTENING, wat aangeeft dat de groep geen verbindingen heeft en wacht op nieuwe leden; en PEER_GROUP_STATUS_HAS CONNECTIONS, wat aangeeft dat de groep ten minste één verbinding heeft. Deze statuswaarde kan worden verkregen door PeerGroupGetStatus aan te roepen nadat deze gebeurtenis is gegenereerd.
PEER_GROUP_EVENT_PROPERTY_CHANGED geeft aan dat de groepseigenschappen zijn gewijzigd of bijgewerkt door de maker van de groep.
PEER_GROUP_EVENT_RECORD_CHANGED geeft aan dat er een recordbewerking is uitgevoerd. Deze gebeurtenis wordt gegenereerd wanneer een peer die deelneemt aan de groep een record publiceert, bijwerken of verwijdert. Deze gebeurtenis wordt bijvoorbeeld gegenereerd wanneer een chattoepassing een chatbericht verzendt.
PEER_GROUP_EVENT_MEMBER_CHANGED geeft aan dat de status van een lid in de groep is gewijzigd. Statuswijzigingen zijn onder andere:
- PEER_MEMBER_CONNECTED. Een peer heeft verbinding gemaakt met de groep.
- PEER_MEMBER_DISCONNECTED. Een peer heeft de verbinding met de groep verbroken.
- PEER_MEMBER_JOINED. Er zijn nieuwe lidmaatschapsgegevens gepubliceerd voor een peer.
- PEER_MEMBER_UPDATED. Een peer is bijgewerkt met nieuwe informatie, zoals een nieuw IP-adres.
PEER_GROUP_EVENT_NEIGHBOR_CONNECTION. Peers die deelnemen aan naburige verbindingen binnen de groep, moeten zich registreren voor deze gebeurtenis. Houd er rekening mee dat het registreren voor deze gebeurtenis de peer niet in staat stelt om gegevens te ontvangen; registratie voor deze gebeurtenis zorgt alleen voor meldingen wanneer een aanvraag voor een buurverbinding wordt ontvangen.
PEER_GROUP_EVENT_DIRECT_CONNECTION. Peers die deelnemen aan directe verbindingen binnen de groep, moeten zich registreren voor deze gebeurtenis. Houd er rekening mee dat het registreren voor deze gebeurtenis de peer niet in staat stelt om gegevens te ontvangen; registratie voor deze gebeurtenis zorgt alleen voor meldingen wanneer een aanvraag voor een directe verbinding wordt ontvangen.
PEER_GROUP_EVENT_INCOMING_DATA. Peers die gegevens ontvangen via een buur of directe verbinding, moeten zich registreren voor deze gebeurtenis. Wanneer deze gebeurtenis wordt gegenereerd, kunnen de ondoorzichtige gegevens die door de andere deelnemende peer worden verzonden, worden verkregen door PeerGroupGetEventData-aan te roepen. Houd er rekening mee dat voor het ontvangen van deze gebeurtenis de peer eerder moet zijn geregistreerd voor PEER_GROUP_EVENT_DIRECT_CONNECTION of PEER_GROUP_EVENT_NEIGHBOR_CONNECTION.
PEER_GROUP_EVENT_CONNECTION_FAILED. Een verbinding is om een of andere reden mislukt. Er worden geen gegevens opgegeven wanneer deze gebeurtenis wordt gegenereerd en PeerGroupGetEventData niet mogen worden aangeroepen.

Nadat een toepassing een melding heeft ontvangen dat er een peergebeurtenis heeft plaatsgevonden (met uitzondering van PEER_GROUP_EVENT_CONNECTION_FAILED), worden de toepassingsaanroepen PeerGroupGetEventDataen wordt de peergebeurtenisgreep doorgegeven die wordt geretourneerd door PeerGroupRegisterEvent. De peer-infrastructuur retourneert een aanwijzer naar een PEER_GROUP_EVENT_DATA structuur die de aangevraagde gegevens bevat. Deze functie moet worden aangeroepen totdat PEER_S_NO_EVENT_DATA wordt geretourneerd. Wanneer een toepassing geen melding meer vereist voor een peergebeurtenis, moet er een aanroep worden gedaan naar PeerGroupUnregisterEvent, waarbij de peergebeurtenis wordt doorgegeven die wordt geretourneerd door PeerGroupRegisterEvent wanneer de toepassing is geregistreerd voor de specifieke gebeurtenis.

Voorbeeld van registreren voor Peer Graphing-gebeurtenissen

In het volgende codevoorbeeld ziet u hoe u zich registreert bij de Peer Graphing-gebeurtenissen.

//-----------------------------------------------------------------------------
// 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;
}

Delen via