Infrastruktur Acara Serekan

Artikel
06/12/2023

Infrastruktur Serekan menggunakan peristiwa untuk memberi tahu aplikasi tentang perubahan yang telah terjadi dalam jaringan serekan, misalnya, simpul yang ditambahkan atau dihapus dari grafik. Infrastruktur Peer Graphing dan Peer Grouping menggunakan infrastruktur peristiwa serekan.

Menerima Pemberitahuan Peristiwa Serekan

Serekan dapat mendaftar untuk menerima pemberitahuan saat atribut grafik atau grup berubah, atau peristiwa serekan tertentu terjadi. Aplikasi peer memanggil fungsi PeerGraphRegisterEvent atau fungsi PeerGroupRegisterEvent, dan meneruskan handel peristiwa ke Infrastruktur Serekan, yang dibuat sebelumnya dengan panggilan ke CreateEvent. Infrastruktur Serekan menggunakan handel untuk memberi sinyal aplikasi bahwa peristiwa serekan telah terjadi.

Aplikasi ini juga meneruskan serangkaian struktur PEER_GRAPH_EVENT_REGISTRATION atau PEER_GROUP_EVENT_REGISTRATION yang menunjukkan kepada Infrastruktur Serekan peristiwa serekan tertentu tempat aplikasi meminta pemberitahuan. Aplikasi juga harus menentukan dengan tepat berapa banyak struktur yang diteruskan.

Peristiwa Grafik Serekan

Aplikasi Peer Graphing dapat mendaftar untuk menerima pemberitahuan untuk 9 peristiwa grafik serekan. Setiap nama peristiwa diawali dengan PEER_GRAPH_EVENT_, misalnya, PEER_GRAPH_STATUS_CHANGED. Kecuali dinyatakan lain, informasi tentang perubahan diambil dengan menggunakan PeerGraphGetEventData.

PEER_GRAPH_EVENT_STATUS_CHANGED menunjukkan bahwa status grafik diubah, misalnya, simpul telah disinkronkan dengan grafik.
PEER_GRAPH_EVENT_PROPERTY_CHANGED menunjukkan bahwa properti grafik atau grup diubah, misalnya, nama grafik yang mudah diingat telah berubah.

Nota

Aplikasi harus memanggilPeerGraphGetProperties untuk mendapatkan informasi yang diubah.
PEER_GRAPH_EVENT_RECORD_CHANGED menunjukkan bahwa rekaman diubah, misalnya, rekaman dihapus.
PEER_GRAPH_EVENT_DIRECT_CONNECTION menunjukkan bahwa koneksi langsung diubah, misalnya, simpul telah tersambung.
PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION menunjukkan bahwa koneksi ke simpul tetangga diubah, misalnya, simpul telah tersambung.
PEER_GRAPH_EVENT_INCOMING_DATA menunjukkan bahwa data telah diterima dari koneksi langsung atau tetangga.
PEER_GRAPH_EVENT_CONNECTION_REQUIRED menunjukkan bahwa Infrastruktur Grafik memerlukan koneksi baru.

Nota

Panggilan ke PeerGraphConnect tersambung ke simpul baru. Panggilan ke PeerGraphGetEventData tidak mengembalikan data.
PEER_GRAPH_EVENT_NODE_CHANGED menunjukkan bahwa informasi kehadiran simpul diubah, misalnya, alamat IP telah berubah.
PEER_GRAPH_EVENT_SYNCHRONIZED menunjukkan bahwa jenis rekaman tertentu disinkronkan.

Setelah aplikasi menerima pemberitahuan bahwa peristiwa peer telah terjadi, aplikasi memanggil PeerGraphGetEventData, dan meneruskan handel peristiwa serekan yang dikembalikan oleh PeerGraphRegisterEvent. Infrastruktur Serekan mengembalikan penunjuk ke struktur PEER_GRAPH_EVENT_DATA yang berisi data yang diminta. Fungsi ini harus dipanggil sampai PEER_S_NO_EVENT_DATA dikembalikan.

Setelah aplikasi tidak memerlukan pemberitahuan peristiwa serekan, aplikasi memanggil PeerGraphUnregisterEvent, dan meneruskan handel peristiwa serekan yang dikembalikan oleh PeerGraphRegisterEvent ketika aplikasi terdaftar.

Menangani Rujukan Koneksi Grafik

KetikapeerGraphConnectdipanggil, peer penghubung diberi tahu tentang keberhasilan atau kegagalan melalui peristiwa PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION asinkron. Jika koneksi gagal karena masalah jaringan tertentu (seperti firewall yang salah dikonfigurasi), peristiwa PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION dinaikkan, dengan status koneksi diatur ke PEER_CONNECTION_FAILED.

Namun, ketika serekan menerima rujukan ketika mencoba untuk terhubung ke simpul yang sibuk, PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION dinaikkan pada peer penghubung, dengan status koneksi diatur ke PEER_CONNECTION_FAILED. Peer penghubung dapat dirujuk ke simpul lain yang sibuk dan dapat mengirim rujukan, dan peristiwa dan status yang sama dinaikkan pada peer penghubung. Rantai rujukan ini yang mengakibatkan status peristiwa PEER_CONNECTION_FAILED dapat berlanjut hingga jumlah maksimum upaya koneksi telah habis. Rekan tidak memiliki mekanisme untuk menentukan perbedaan antara upaya koneksi penuh dan rujukan koneksi.

Untuk mengatasi masalah ini, pengembang harus mempertimbangkan untuk menggunakan peristiwa perubahan status grafik serekan untuk menentukan apakah upaya koneksi berhasil. Jika peristiwa tidak diterima dalam waktu tertentu, aplikasi dapat mengasumsikan bahwa peer penghubung sedang dirujuk dan bahwa aplikasi serekan harus mempertimbangkan upaya koneksi gagal.

Peristiwa Pengelompokan Serekan

Aplikasi Pengelompokan Serekan dapat mendaftar untuk menerima pemberitahuan untuk 8 peristiwa serekan. Setiap nama peristiwa diawali dengan PEER_GROUP_EVENT_; misalnya, PEER_GROUP_EVENT_STATUS_CHANGED. Kecuali dinyatakan lain, informasi tentang perubahan diambil dengan menggunakan PeerGroupGetEventData.

PEER_GROUP_EVENT_STATUS_CHANGED menunjukkan bahwa status grup telah berubah. Ada dua nilai status yang mungkin: PEER_GROUP_STATUS_LISTENING, yang menunjukkan bahwa grup tidak memiliki koneksi dan sedang menunggu anggota baru; dan PEER_GROUP_STATUS_HAS CONNECTIONS, yang menunjukkan bahwa grup memiliki setidaknya satu koneksi. Nilai status ini dapat diperoleh dengan memanggil PeerGroupGetStatus setelah peristiwa ini dinaikkan.
PEER_GROUP_EVENT_PROPERTY_CHANGED menunjukkan bahwa properti grup telah diubah atau diperbarui oleh pembuat grup.
PEER_GROUP_EVENT_RECORD_CHANGED menunjukkan bahwa operasi rekaman telah dilakukan. Kejadian ini dimunculkan saat serekan yang berpartisipasi dalam grup menerbitkan, memperbarui, atau menghapus rekaman. Misalnya, peristiwa ini dimunculkan saat aplikasi obrolan mengirim pesan obrolan.
PEER_GROUP_EVENT_MEMBER_CHANGED menunjukkan bahwa status anggota dalam grup telah berubah. Perubahan status meliputi:
- PEER_MEMBER_CONNECTED. Serekan telah tersambung ke grup.
- PEER_MEMBER_DISCONNECTED. Serekan telah terputus dari grup.
- PEER_MEMBER_JOINED. Informasi keanggotaan baru telah diterbitkan untuk serekan.
- PEER_MEMBER_UPDATED. Serekan telah diperbarui dengan informasi baru, seperti alamat IP baru.
PEER_GROUP_EVENT_NEIGHBOR_CONNECTION. Rekan-rekan yang akan berpartisipasi dalam koneksi tetangga dalam grup harus mendaftar untuk acara ini. Perhatikan bahwa mendaftar untuk peristiwa ini tidak memungkinkan rekan untuk menerima data; pendaftaran untuk peristiwa ini hanya memastikan pemberitahuan ketika permintaan koneksi tetangga diterima.
PEER_GROUP_EVENT_DIRECT_CONNECTION. Rekan-rekan yang akan berpartisipasi dalam koneksi langsung dalam grup harus mendaftar untuk acara ini. Perhatikan bahwa mendaftar untuk peristiwa ini tidak memungkinkan rekan untuk menerima data; pendaftaran untuk kejadian ini hanya memastikan pemberitahuan ketika permintaan koneksi langsung diterima.
PEER_GROUP_EVENT_INCOMING_DATA. Rekan-rekan yang akan menerima data melalui tetangga atau koneksi langsung harus mendaftar untuk acara ini. Ketika peristiwa ini dinaikkan, data buram yang dikirimkan oleh serekan lain yang berpartisipasi dapat diperoleh dengan memanggil PeerGroupGetEventData. Perhatikan bahwa untuk menerima acara ini, rekan sebelumnya harus mendaftar untuk PEER_GROUP_EVENT_DIRECT_CONNECTION atau PEER_GROUP_EVENT_NEIGHBOR_CONNECTION.
PEER_GROUP_EVENT_CONNECTION_FAILED. Koneksi gagal karena beberapa alasan. Tidak ada data yang disediakan ketika peristiwa ini dinaikkan, dan PeerGroupGetEventData tidak boleh dipanggil.

Setelah aplikasi menerima pemberitahuan bahwa peristiwa serekan telah terjadi (tidak termasuk PEER_GROUP_EVENT_CONNECTION_FAILED), aplikasi memanggil PeerGroupGetEventData, dan melewati handel peristiwa serekan yang dikembalikan oleh PeerGroupRegisterEvent. Infrastruktur Serekan mengembalikan penunjuk ke struktur PEER_GROUP_EVENT_DATA yang berisi data yang diminta. Fungsi ini harus dipanggil hingga PEER_S_NO_EVENT_DATA dikembalikan. Ketika aplikasi tidak lagi memerlukan pemberitahuan untuk peristiwa serekan, panggilan harus dilakukan untuk PeerGroupUnregisterEvent, melewati handel peristiwa serekan yang dikembalikan oleh PeerGroupRegisterEvent ketika aplikasi terdaftar untuk peristiwa tertentu.

Contoh Pendaftaran untuk Peristiwa Grafik Serekan

Sampel kode berikut menunjukkan kepada Anda cara mendaftar dengan peristiwa 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;
}

Bagikan melalui