Társesemények infrastruktúrája

A társinfrastruktúra események használatával értesíti az alkalmazásokat a társhálózaton történt változásokról, például egy gráfból hozzáadott vagy eltávolított csomópontról. A társgráfolási és társcsoport-csoportosítási infrastruktúrák a társesemény-infrastruktúrát használják.

Társesemény-értesítés fogadása

A társ regisztrálhat, hogy értesítést kapjon, ha egy gráf vagy csoport attribútuma megváltozik, vagy egy adott társesemény történik. A társalkalmazás meghívja a PeerGraphRegisterEvent vagy PeerGroupRegisterEvent függvényt, és átad egy eseménykezelőt a társinfrastruktúra számára, amelyet korábban a CreateEventhívása hozott létre. A társinfrastruktúra a leíróval jelzi az alkalmazásnak, hogy társesemény történt.

Az alkalmazás több PEER_GRAPH_EVENT_REGISTRATION vagy PEER_GROUP_EVENT_REGISTRATION struktúrát is átad, amelyek jelzik a társinfrastruktúra számára azokat a társeseményeket, amelyekről az alkalmazás értesítést kér. Az alkalmazásnak azt is meg kell adnia, hogy pontosan hány struktúrát adnak át.

Társgráfozási események

A peer graphing alkalmazás regisztrálhat, hogy értesítést kapjon 9 társgráf-eseményről. Az egyes eseménynevek előtagja PEER_GRAPH_EVENT_, például PEER_GRAPH_STATUS_CHANGED. Ha másként nem jelezzük, a rendszer PeerGraphGetEventDatahasználatával kéri le a módosítással kapcsolatos információkat.

• PEER_GRAPH_EVENT_STATUS_CHANGED azt jelzi, hogy egy gráf állapota megváltozik, például egy csomópont szinkronizálva van egy gráfmal.

• PEER_GRAPH_EVENT_PROPERTY_CHANGED azt jelzi, hogy egy gráf vagy csoport tulajdonsága módosult, például a gráf rövid neve megváltozott.

  Jegyzet

  Az alkalmazásnak meg kell hívnia PeerGraphGetProperties a módosított információk beszerzéséhez.

   

• PEER_GRAPH_EVENT_RECORD_CHANGED azt jelzi, hogy egy rekord módosul, például egy rekord törlődik.

• PEER_GRAPH_EVENT_DIRECT_CONNECTION azt jelzi, hogy a közvetlen kapcsolat megváltozott, például egy csomópont csatlakozott.

• PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION azt jelzi, hogy a szomszédos csomóponthoz való kapcsolat megváltozott, például egy csomópont csatlakozott.

• PEER_GRAPH_EVENT_INCOMING_DATA azt jelzi, hogy az adatok közvetlen vagy szomszéd kapcsolatból érkeztek.

• PEER_GRAPH_EVENT_CONNECTION_REQUIRED azt jelzi, hogy a Graphing-infrastruktúra új kapcsolatot igényel.

  Jegyzet

  A PeerGraphConnecthívása egy új csomóponthoz csatlakozik. A PeerGraphGetEventData hívása nem ad vissza adatokat.

   

• PEER_GRAPH_EVENT_NODE_CHANGED azt jelzi, hogy a csomópont jelenléti adatai módosultak, például egy IP-cím módosult.

• PEER_GRAPH_EVENT_SYNCHRONIZED egy adott rekordtípus szinkronizálását jelzi.

Miután egy alkalmazás értesítést kap arról, hogy társesemény történt, az alkalmazás meghívja PeerGraphGetEventData, és átadja PeerGraphRegisterEventáltal visszaadott társesemény-leírót. A társinfrastruktúra a kért adatokat tartalmazó PEER_GRAPH_EVENT_DATA struktúrára mutató mutatót ad vissza. Ezt a függvényt addig kell meghívni, amíg PEER_S_NO_EVENT_DATA vissza nem ad.

Miután egy alkalmazás nem igényel társesemény-értesítést, az alkalmazás meghívja PeerGraphUnregisterEvent, és átadja PeerGraphRegisterEvent által visszaadott társesemény-leírót, amikor az alkalmazás regisztrálva van.

Gráfkapcsolattal kapcsolatos javaslatok kezelése

Ha PeerGraphConnect van meghívva, a csatlakozó társ az aszinkron PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION eseményen keresztül értesítést kap a sikerességről vagy a hibáról. Ha a kapcsolat egy adott hálózati probléma (például helytelenül konfigurált tűzfal) miatt meghiúsult, a PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION esemény létrejön, és a kapcsolat állapota PEER_CONNECTION_FAILED.

Ha azonban egy társ átirányítást kap, amikor egy forgalmas csomóponthoz próbál csatlakozni, a PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION a csatlakozó társon jön létre, és a kapcsolat állapota PEER_CONNECTION_FAILED. A csatlakozó társ egy másik csomópontra hivatkozhat, amely maga is foglalt, és javaslatot küldhet, és ugyanaz az esemény és állapot jelenik meg a csatlakozó társon. Ez az átirányítási lánc, amely PEER_CONNECTION_FAILED eseményállapotokat eredményez, mindaddig folytatódhat, amíg a csatlakozási kísérletek maximális száma ki nem merül. A társnak nincs mechanizmusa a teljes kapcsolati kísérlet és a kapcsolatátirányítás közötti különbség meghatározására.

A probléma megoldásához a fejlesztőknek érdemes megfontolni a társgráf állapotváltozási eseményeinek használatát annak megállapításához, hogy a kapcsolati kísérlet perelt-e. Ha az esemény nem érkezik meg meghatározott időn belül, az alkalmazás feltételezheti, hogy a csatlakozó társra hivatkozik, és hogy a társalkalmazásnak figyelembe kell vennie a csatlakozási kísérletet.

Társcsoportozási események

A társcsoportozási alkalmazások regisztrálhatnak, hogy értesítést kapjanak 8 társeseményről. Minden eseménynév előtaggal van elnevezett PEER_GROUP_EVENT_; például PEER_GROUP_EVENT_STATUS_CHANGED. Ha másként nem jelezzük, a rendszer PeerGroupGetEventDatahasználatával kéri le a módosítással kapcsolatos információkat.

• PEER_GROUP_EVENT_STATUS_CHANGED azt jelzi, hogy a csoport állapota megváltozott. Két állapotérték lehetséges: PEER_GROUP_STATUS_LISTENING, amely azt jelzi, hogy a csoportnak nincsenek kapcsolatai, és új tagokra vár; és PEER_GROUP_STATUS_HAS KAPCSOLATOK, amely azt jelzi, hogy a csoport legalább egy kapcsolattal rendelkezik. Ez az állapotérték PeerGroupGetStatus meghívásával szerezhető be az esemény bekövetkezése után.
• PEER_GROUP_EVENT_PROPERTY_CHANGED azt jelzi, hogy a csoport tulajdonságait a csoport létrehozója módosította vagy frissítette.
• PEER_GROUP_EVENT_RECORD_CHANGED azt jelzi, hogy rekordműveletet hajtottak végre. Ez az esemény akkor jön létre, ha a csoportban részt vevő társ közzétesz, frissít vagy töröl egy rekordot. Ez az esemény például akkor jön létre, amikor egy csevegőalkalmazás csevegőüzenetet küld.
• PEER_GROUP_EVENT_MEMBER_CHANGED azt jelzi, hogy egy tag állapota megváltozott a csoportban. Az állapotváltozások a következők:
  • PEER_MEMBER_CONNECTED. Egy társ csatlakozott a csoporthoz.
  • PEER_MEMBER_DISCONNECTED. Egy társ leválasztott a csoportról.
  • PEER_MEMBER_JOINED. Új tagsági adatok jelentek meg egy társ számára.
  • PEER_MEMBER_UPDATED. A társ új információkkal, például új IP-címmel frissült.
• PEER_GROUP_EVENT_NEIGHBOR_CONNECTION. Azoknak a társtársaknak, akik részt vesznek a csoporton belüli szomszéd kapcsolatokban, regisztrálniuk kell erre az eseményre. Vegye figyelembe, hogy az esemény regisztrációja nem teszi lehetővé a társ számára az adatok fogadását; az esemény regisztrációja csak akkor biztosít értesítést, ha egy szomszéd kapcsolatra vonatkozó kérés érkezik.
• PEER_GROUP_EVENT_DIRECT_CONNECTION. A csoporton belüli közvetlen kapcsolatokban részt vevő partnereknek regisztrálniuk kell erre az eseményre. Vegye figyelembe, hogy az esemény regisztrációja nem teszi lehetővé a társ számára az adatok fogadását; az esemény regisztrálása csak akkor biztosít értesítést, ha közvetlen kapcsolatra vonatkozó kérés érkezik.
• PEER_GROUP_EVENT_INCOMING_DATA. A szomszéd vagy közvetlen kapcsolaton keresztül adatokat fogadó társtársaknak regisztrálniuk kell erre az eseményre. Az esemény bekövetkezésekor a másik résztvevő társ által továbbított átlátszatlan adatok PeerGroupGetEventDatameghívásával kérhetők le. Vegye figyelembe, hogy az esemény fogadásához a társnak korábban regisztrálnia kell PEER_GROUP_EVENT_DIRECT_CONNECTION vagy PEER_GROUP_EVENT_NEIGHBOR_CONNECTION.
• PEER_GROUP_EVENT_CONNECTION_FAILED. A kapcsolat valamilyen okból meghiúsult. Az esemény bekövetkezésekor nincs adat megadva, és PeerGroupGetEventData nem hívható meg.

Miután egy alkalmazás értesítést kapott arról, hogy társesemény történt (a PEER_GROUP_EVENT_CONNECTION_FAILEDkivételével), az alkalmazás meghívja PeerGroupGetEventData, és átadja PeerGroupRegisterEventáltal visszaadott társesemény-leírót. A társinfrastruktúra a kért adatokat tartalmazó PEER_GROUP_EVENT_DATA struktúrára mutató mutatót ad vissza. Ezt a függvényt addig kell meghívni, amíg PEER_S_NO_EVENT_DATA vissza nem ad. Ha egy alkalmazás már nem igényel értesítést egy társeseményről, hívást kell kezdeményezni PeerGroupUnregisterEvent, amely átadja PeerGroupRegisterEvent által visszaadott társesemény-leírót, amikor az alkalmazás regisztrálva van az adott eseményre.

Példa a társgráfozási események regisztrálására

Az alábbi kódminta bemutatja, hogyan regisztrálhat a társgráfozási eseményekre.

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