Bagikan melalui

Cara Bekerja Dengan Grup

  • Artikel

Peer-to-peer Grouping adalah teknologi yang memungkinkan pengembang untuk membuat jaringan serekan yang aman dengan cepat dan efektif. Daftar berikut mengidentifikasi pertimbangan utama dalam membuat aplikasi pengelompokan serekan.

Mendapatkan Identitas Rekan

Sebelum membuat atau menyambungkan ke grup, rekan harus mendapatkan identitas rekan, yang merupakan nama yang digunakan untuk mengidentifikasi rekan dalam grup secara unik. Untuk mendapatkan daftar enumerasi dari semua identitas serekan yang ditentukan pada serekan, panggil PeerEnumIdentities, yang mengembalikan handel ke enumerasi. Untuk mendapatkan identitas rekan, panggil PeerGetNextItem dengan handle enumerasi dan jumlah anggota yang ingin diambil. Lanjutkan memanggil PeerGetNextItem hingga parameter pCount mengembalikan nilai yang kurang dari jumlah identitas rekan yang diminta.

Jika identitas untuk rekan tersebut tidak ada, identitas tersebut dapat dibuat dengan memanggil PeerIdentityCreate. Setelah membuat identitas rekan, peer menghasilkan identitas XML blob yang berisi kunci publik yang telah ditetapkan kepadanya.

Informasi identitas serekan diperoleh dengan memanggil PeerIdentityGetXML. Informasi identitas serekan ini digunakan oleh pembuat grup atau administrator untuk mengeluarkan kredensial yang diperlukan untuk bergabung dengan grup, sebagai blob XML undangan.

Untuk informasi selengkapnya tentang identitas rekan, lihat dokumentasi API Manajer Identitas.

Mengaktifkan Infrastruktur Kelompok Sebaya

Sebelum fungsi apa pun dalam PEER Grouping API dipanggil oleh aplikasi, PeerGroupStartup harus dipanggil. Fungsi ini menginisialisasi Infrastruktur Pengelompokan Peer untuk aplikasi dan mengatur versi yang didukung.

Mendapatkan Pegangan Kelompok

Untuk terhubung ke grup dan mulai berpartisipasi, tangkai ke grup sebaya harus diperoleh. Daftar berikut mengidentifikasi tiga cara untuk menyambungkan ke grup serekan:

  • Membuat grup rekan dengan memanggil PeerGroupCreate, yang menginisialisasi grup rekan baru dan mengembalikan handle yang valid dengan rekan sebagai pemilik dan administrator satu-satunya.
  • Bergabung dengan kelompok sebaya dengan menggunakan PeerGroupJoin. Untuk bergabung dengan grup serekan, rekan harus menerima undangan dari administrator grup serekan. Untuk mendapatkan undangan, kirim blob XML informasi identitas ke administrator yang membuat undangan dan mengirimkannya kepada Anda dengan mekanisme eksternal, seperti email atau FTP. Undangan dan identitas rekan diteruskan ke PeerGroupJoin, yang mengembalikan handle yang valid ke grup.
  • Membuka grup yang pernah diikuti oleh rekan dengan memanggil PeerGroupOpen. Dalam situasi ini, mendapatkan undangan tidak diperlukan.

Setelah Anda mendapatkan handle grup sebaya yang valid dari salah satu fungsi di atas, Anda dapat menghubungkan ke grup sebaya dengan memanggil PeerGroupConnect dengan handle baru.

Nota

Jika koneksi ke grup sebaya gagal, event PEER_GROUP_EVENT_CONNECTION_FAILED terjadi. Pengendali dapat mencoba membangun kembali koneksi ke grup rekan.

 

Mendaftar Acara Pengelompokan Sebaya

Sebelum serekan berpartisipasi dalam grup serekan, rekan harus mendaftar untuk acara grup serekan. Untuk mendaftar acara sebaya tertentu, panggil PeerGroupRegisterEvent, dan sisipkan satu atau beberapa jenis acara sebaya yang didefinisikan dalam PEER_GROUP_EVENT_TYPE. Anda harus mendaftar ke setiap acara peer yang sesuai untuk aplikasi Anda; misalnya, untuk menerima data melalui koneksi langsung, daftar ke acara PEER_GROUP_EVENT_DIRECT_CONNECTION dan PEER_GROUP_EVENT_INCOMING_DATA. Setiap panggilan mengambil handel peristiwa dan mengembalikan handel HPEEREVENT untuk peristiwa rekan tersebut.

Penangan acara dapat memperoleh data yang berhubungan dengan peristiwa peer dengan meneruskan handle ke peristiwa peer yang terdaftar ke PeerGroupGetEventData. Data peristiwa rekan ini dikembalikan sebagai union PEER_GROUP_EVENT_DATA. Jika antrean peristiwa rekan kosong, fungsi ini akan mengembalikan PEER_S_NO_EVENT_DATA.

Anda dapat membatalkan pendaftaran untuk acara peer dengan memanggil PeerGroupUnregisterEvent dan memberikan penanganan untuk acara peer yang ingin Anda batalkan. Setelah fungsi dipanggil, peristiwa sejawat yang terkait dengan handle tidak lagi terdaftar.

Membuat Peran Administrator dan Anggota

Rekan yang membuat grup serekan dikenal sebagai pembuat grup serekan, dan memiliki peran administrator secara default. Hanya pembuat kelompok sejawat yang dapat mengatur properti grup.

Rekan yang diundang ke grup rekan dapat menjadi administrator atau anggota. Jika mereka diberi peran administrator oleh administrator yang mengeluarkan undangan, mereka dapat mengundang anggota baru ke grup serekan, dan juga menetapkan peran administrator kepada anggota lain.

Peran anggota grup serekan diatur dalam undangan yang diberikan administrator kepada anggota. Untuk menambahkan lebih banyak administrator, atur nilai parameter pRoles dari PeerGroupCreateInvitation ke PEER_GROUP_ROLE_ADMIN saat membuat undangan.

Anggota dapat berpartisipasi dalam grup serekan, tetapi tidak dapat mengundang dan mengotorisasi anggota baru, mengatur properti grup, atau memperbarui atau menghapus rekaman grup yang tidak mereka buat secara khusus. Untuk menetapkan status anggota ke rekan yang berpartisipasi, atur nilai parameter pRolesPeerGroupCreateInvitation ke PEER_GROUP_ROLE_MEMBER saat Anda membuat undangan untuk rekan tersebut.

Untuk mengubah peran anggota, kredensial baru yang berisi peran baru harus dikeluarkan untuk anggota tersebut. Untuk mencapai hal ini, dapatkan struktur PEER_CREDENTIAL_INFO untuk anggota ini dari struktur PEER_MEMBER yang dikembalikan oleh PeerGroupEnumMembers. Ubah bidang pRoles di PEER_CREDENTIAL_INFO menjadi peran baru, dan berikan struktur tersebut ke PeerGroupIssueCredentials.

Kredensial baru tidak akan berlaku untuk mitra hingga mereka tersambung ke grup mitra. Jika saat ini tersambung, mereka harus menutup grup dan menyambungkan kembali untuk mendapatkan kredensial yang diperbarui.

Menemukan Rekan

Untuk mendapatkan daftar semua rekan yang berpartisipasi dalam grup rekan, panggil PeerGroupEnumMembers dengan handle grup, yang mengembalikan handle ke daftar enumerasi. Untuk mendapatkan anggota, panggil PeerGetNextItem dengan pegangan enum dan jumlah anggota yang ingin diambil. Lanjutkan panggilan PeerGetNextItem hingga parameter pCount mengembalikan nilai yang kurang dari jumlah anggota yang diminta. Perhatikan bahwa daftar lengkap anggota yang tersedia mungkin tidak dikembalikan.

Setiap anggota diwakili sebagai struktur PEER_MEMBER, yang berisi identitas rekan, ID node, dan alamat IP untuk rekan aktif.

Setelah selesai, tutup enumerasi dan lepaskan memori terkait dengan memanggil PeerEndEnumeration.

Menyambungkan Langsung dengan Rekan

Saat rekan terhubung ke grup rekan, pertukaran langsung satu-ke-satu dengan anggota lain yang terhubung dimulai dengan memanggil PeerGroupOpenDirectConnection dan menyediakan identitas rekan lainnya. Panggilan ini asinkron, dan mengembalikan ID koneksi 64-bit. Jika panggilan berhasil, Anda menerima peristiwa peer PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT yang menunjukkan bahwa koneksi berhasil. Jika koneksi berhasil, ID koneksi valid dan dapat digunakan untuk mengirim dan menerima data melalui koneksi langsung.

Agar dapat menerima koneksi langsung, rekan sejawat lain juga harus sudah terdaftar sebelumnya untuk acara PEER_GROUP_EVENT_DIRECT_CONNECTION.

Untuk mengirim data ke serekan, panggil PeerGroupSendData dengan ID koneksi yang valid. Untuk menerima data, rekan lainnya harus didaftarkan untuk acara rekan PEER_GROUP_EVENT_INCOMING_DATA. Demikian juga, jika peer pengirim ingin menerima data secara bergantian, itu juga harus didaftarkan untuk peristiwa serekan PEER_GROUP_EVENT_INCOMING_DATA.

Untuk menerima kumpulan total koneksi langsung yang saat ini aktif dengan rekan-rekan lain dalam grup, panggil PeerGroupEnumConnections untuk membuka enumerasi dan melakukan iterasi melalui daftar koneksi dengan menggunakan PeerGetNextItem.

Untuk menutup koneksi langsung, panggil PeerGroupCloseDirectConnection dan teruskan ID koneksi.

Menutup dan Mengakhiri Grup Sebaya

Untuk menutup koneksi ke kelompok sebaya, panggil PeerGroupClose, yang membatalkan pengendali grup, tetapi tidak mematikan Infrastruktur Pengelompokan Sebaya. Data grup peer-to-peer dihapus dengan memanggil PeerGroupDelete.

Ketika aplikasi selesai menggunakan Infrastruktur Pengelompokan Sebaya, aplikasi harus memanggil PeerGroupShutdown.