Fungsi WSAJoinLeaf (winsock2.h)
Fungsi WSAJoinLeaf menggabungkan simpul daun ke dalam sesi multipoint, bertukar data koneksi, dan menentukan kualitas layanan yang diperlukan berdasarkan struktur FLOWSPEC yang ditentukan.
Sintaks
SOCKET WSAAPI WSAJoinLeaf(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[in] DWORD dwFlags
);
Parameter
[in] s
Deskriptor mengidentifikasi soket multipoint.
[in] name
Nama serekan tempat soket akan digabungkan.
[in] namelen
Panjang nama, dalam byte.
[in] lpCallerData
Arahkan ke data pengguna yang akan ditransfer ke serekan selama pembentukan sesi multipoint.
[out] lpCalleeData
Arahkan ke data pengguna yang akan ditransfer kembali dari peer selama pembentukan sesi multipoint.
[in] lpSQOS
Penunjuk ke struktur FLOWSPEC untuk soket, satu untuk setiap arah.
[in] lpGQOS
Dicadangkan untuk digunakan di masa mendatang dengan grup soket. Penunjuk ke struktur FLOWSPEC untuk grup soket (jika berlaku).
[in] dwFlags
Bendera untuk menunjukkan bahwa soket bertindak sebagai pengirim (JL_SENDER_ONLY), penerima (JL_RECEIVER_ONLY), atau keduanya (JL_BOTH).
Mengembalikan nilai
Jika tidak ada kesalahan yang terjadi, WSAJoinLeaf mengembalikan nilai jenis SOCKET yang merupakan deskriptor untuk soket multipoint yang baru dibuat. Jika tidak, nilai INVALID_SOCKET dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.
Pada soket pemblokiran, nilai pengembalian menunjukkan keberhasilan atau kegagalan operasi gabungan.
Dengan soket nonblocking, inisiasi operasi gabungan yang berhasil ditunjukkan oleh pengembalian deskriptor soket yang valid. Selanjutnya, indikasi FD_CONNECT akan diberikan pada soket asli ketika operasi gabungan selesai, baik berhasil atau sebaliknya. Aplikasi harus menggunakan WSAAsyncSelect atau WSAEventSelect dengan minat yang terdaftar untuk peristiwa FD_CONNECT untuk menentukan kapan operasi gabungan telah selesai dan memeriksa kode kesalahan terkait untuk menentukan keberhasilan atau kegagalan operasi. Fungsi pilih tidak dapat digunakan untuk menentukan kapan operasi gabungan selesai.
Selain itu, sampai upaya gabungan sesi multipoint menyelesaikan semua panggilan berikutnya ke WSAJoinLeaf pada soket yang sama akan gagal dengan kode kesalahan WSAEALREADY. Setelah operasi WSAJoinLeaf berhasil diselesaikan, upaya berikutnya biasanya akan gagal dengan kode kesalahan WSAEISCONN. Pengecualian untuk aturan WSAEISCONN terjadi untuk soket c_root yang memungkinkan gabungan yang dimulai root. Dalam kasus seperti itu, gabungan lain dapat dimulai setelah operasi WSAJoinLeaf sebelumnya selesai.
Jika kode kesalahan pengembalian menunjukkan upaya gabungan sesi multipoint gagal (yaitu, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) aplikasi dapat memanggil WSAJoinLeaf lagi untuk soket yang sama.
| Kode kesalahan | Makna |
|---|---|
| Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini. | |
| Alamat lokal soket sudah digunakan dan soket tidak ditandai untuk memungkinkan penggunaan kembali alamat dengan SO_REUSEADDR. Kesalahan ini biasanya terjadi pada saat pengikatan, tetapi dapat ditunda sampai fungsi ini jika ikatannya adalah ke alamat wildcard sebagian (melibatkan ADDR_ANY) dan jika alamat tertentu perlu dilakukan pada saat fungsi ini. | |
| Alamat jarak jauh bukan alamat yang valid (seperti ADDR_ANY). | |
| Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini. | |
| Panggilan WSAJoinLeaf yang tidak diblokir sedang berlangsung pada soket yang ditentukan. | |
| Upaya untuk bergabung ditolak secara paksa. | |
| Nama atau parameter namelen bukan bagian yang valid dari ruang alamat pengguna, parameter namelen terlalu kecil, panjang buffer untuk lpCalleeData, lpSQOS, dan lpGQOS terlalu kecil, atau panjang buffer untuk lpCallerData terlalu besar. | |
| Panggilan fungsi WSAJoinLeaf dilakukan pada soket UDP yang dibuka tanpa mengatur bendera multipoint WSA_FLAG_MULTIPOINT_C_LEAF atau WSA_FLAG_MULTIPOINT_D_LEAF. | |
| Soket sudah menjadi anggota sesi multipoint. | |
| Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall. | |
| Panggilan Windows Sockets 1.1 yang diblokir sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik. | |
| Subsistem jaringan gagal. | |
| Jaringan tidak dapat dijangkau dari host ini saat ini. | |
| Tidak ada ruang buffer yang tersedia. Soket tidak dapat digabungkan. | |
| Deskriptor bukan soket. | |
| Struktur FLOWSPEC yang ditentukan dalam lpSQOS dan lpGQOS tidak dapat dipenuhi. | |
| Augment lpCallerData tidak didukung oleh penyedia layanan. | |
| Upaya untuk bergabung kehabisan waktu tanpa membuat sesi multipoint. |
Keterangan
Fungsi WSAJoinLeaf digunakan untuk menggabungkan node daun ke sesi multipoint, dan untuk melakukan sejumlah operasi tambahan lainnya yang terjadi pada waktu bergabung sesi juga. Jika soket tidak terikat, nilai unik ditetapkan ke asosiasi lokal oleh sistem, dan soket ditandai sebagai terikat.
Fungsi WSAJoinLeaf memiliki parameter dan semantik yang sama dengan WSAConnect kecuali bahwa ia mengembalikan deskriptor soket (seperti dalam WSAAccept), dan memiliki parameter dwFlags tambahan. Hanya soket multipoint yang dibuat menggunakan WSASocket dengan set bendera multipoint yang sesuai yang dapat digunakan untuk parameter input dalam fungsi ini. Deskriptor soket yang dikembalikan tidak akan dapat digunakan sampai setelah operasi gabungan selesai. Misalnya, jika soket berada dalam mode nonblocking setelah indikasi FD_CONNECT yang sesuai telah diterima dari WSAAsyncSelect atau WSAEventSelect pada soket asli, kecuali bahwa closesocket dapat dipanggil pada deskriptor soket baru ini untuk membatalkan operasi gabungan yang tertunda. Aplikasi root dalam sesi multipoint dapat memanggil WSAJoinLeaf satu atau beberapa kali untuk menambahkan sejumlah node daun, namun paling banyak satu permintaan koneksi multipoint mungkin luar biasa pada satu waktu. Lihat Multipoint dan Multicast Semantics untuk informasi tambahan.
Untuk soket yang tidak diblokir, seringkali tidak mungkin untuk segera menyelesaikan koneksi. Dalam kasus seperti itu, fungsi ini mengembalikan deskriptor soket yang belum dapat digunakan dan operasi berlanjut. Tidak ada kode kesalahan seperti WSAEWOULDBLOCK dalam hal ini, karena fungsi telah secara efektif mengembalikan indikasi mulai yang berhasil. Ketika hasil akhir berhasil atau gagal diketahui, itu dapat dilaporkan melalui WSAAsyncSelect atau WSAEventSelect tergantung pada bagaimana klien mendaftar untuk pemberitahuan pada soket asli. Dalam kedua kasus, pemberitahuan diumumkan dengan FD_CONNECT dan kode kesalahan yang terkait dengan FD_CONNECT menunjukkan keberhasilan atau alasan tertentu untuk kegagalan. Fungsi pilih tidak dapat digunakan untuk mendeteksi pemberitahuan penyelesaian untuk WSAJoinLeaf.
Deskriptor soket yang dikembalikan oleh WSAJoinLeaf berbeda tergantung pada apakah deskriptor soket input, s, adalah c_root atau c_leaf. Ketika digunakan dengan soket c_root, parameter nama menunjuk simpul daun tertentu untuk ditambahkan dan deskriptor soket yang dikembalikan adalah soket c_leaf yang sesuai dengan simpul daun yang baru ditambahkan. Soket yang baru dibuat memiliki properti yang sama dengan, termasuk peristiwa asinkron yang terdaftar di WSAAsyncSelect atau dengan WSAEventSelect. Ini tidak dimaksudkan untuk digunakan untuk pertukaran data multipoint, melainkan digunakan untuk menerima indikasi peristiwa jaringan (misalnya, FD_CLOSE) untuk koneksi yang ada ke c_leaf tertentu. Beberapa implementasi multipoint juga dapat memungkinkan soket ini digunakan untuk obrolan samping antara root dan node daun individu. Indikasi FD_CLOSE akan diterima untuk soket ini jika node daun yang sesuai memanggil closesocket untuk keluar dari sesi multipoint. Secara simetris, memanggil closesocket pada soket c_leaf yang dikembalikan dari WSAJoinLeaf akan menyebabkan soket di simpul daun yang sesuai mendapatkan pemberitahuan FD_CLOSE.
Ketika WSAJoinLeaf dipanggil dengan soket c_leaf, parameter nama berisi alamat aplikasi akar (untuk skema kontrol berakar) atau sesi multipoint yang ada (skema kontrol yang tidak dirutekan), dan deskriptor soket yang dikembalikan sama dengan deskriptor soket input. Dengan kata lain, deskriptor soket baru tidak dialokasikan. Dalam skema kontrol berakar, aplikasi root akan menempatkan soket c_root dalam mode mendengarkan dengan memanggil mendengarkan. Pemberitahuan FD_ACCEPT standar akan dikirimkan ketika node daun meminta untuk bergabung dengan dirinya sendiri ke sesi multipoint. Aplikasi root menggunakan fungsi terima biasa atau WSAAccept untuk mengakui simpul daun baru. Nilai yang dikembalikan dari terima atau WSAAccept juga merupakan deskriptor soket c_leaf seperti yang dikembalikan dari WSAJoinLeaf. Untuk mengakomodasi skema multipoint yang memungkinkan gabungan yang dimulai akar dan dimulai daun, dapat diterima untuk soket c_root yang sudah dalam mode mendengarkan untuk digunakan sebagai input ke WSAJoinLeaf.
Aplikasi ini bertanggung jawab untuk mengalokasikan ruang memori apa pun yang diarahkan ke secara langsung atau tidak langsung oleh salah satu parameter yang ditentukannya.
lpCallerData adalah parameter nilai yang berisi data pengguna apa pun yang akan dikirim bersama dengan permintaan gabungan sesi multipoint. Jika lpCallerDataADALAH NULL, tidak ada data pengguna yang akan diteruskan ke peer. lpCalleeData adalah parameter hasil yang akan berisi data pengguna apa pun yang diteruskan kembali dari peer sebagai bagian dari pembentukan sesi multipoint. Anggota lensa struktur WSABUF yang diarahkan oleh parameter lpCalleeData awalnya berisi panjang buffer yang dialokasikan oleh aplikasi dan ditunjukkan oleh anggota buf struktur WSABUF . Anggota len dari struktur WSABUF yang diarahkan oleh parameter lpCalleeData akan diatur ke nol jika tidak ada data pengguna yang diteruskan kembali. Informasi lpCalleeData akan valid ketika operasi gabungan multi-titik selesai.
Untuk memblokir soket, ini akan menjadi ketika fungsi WSAJoinLeaf kembali. Untuk soket yang tidak memblokir, ini akan terjadi setelah operasi gabungan selesai. Misalnya, ini dapat terjadi setelah FD_CONNECT pemberitahuan pada soket asli). Jika lpCalleeDataADALAH NULL, tidak ada data pengguna yang akan diteruskan kembali. Format data pengguna yang tepat khusus untuk keluarga alamat tempat soket berada.
Pada waktu pembentukan sesi multipoint, aplikasi dapat menggunakan parameter lpSQOS dan/atau lpGQOS untuk mengambil alih kualitas spesifikasi layanan sebelumnya yang dibuat untuk soket melalui WSAIoctl dengan opcode SIO_SET_QOS atau SIO_SET_GROUP_QOS.
Parameter lpSQOS menentukan struktur FLOWSPEC untuk soket, satu untuk setiap arah, diikuti oleh parameter khusus penyedia tambahan. Jika penyedia transportasi terkait secara umum atau jenis soket tertentu khususnya tidak dapat mematuhi kualitas permintaan layanan, kesalahan akan dikembalikan seperti yang ditunjukkan dalam hal berikut. Nilai spesifikasi alur pengiriman atau penerimaan masing-masing akan diabaikan untuk soket satu arah. Jika tidak ada parameter khusus penyedia yang ditentukan, anggota buf dan len dari struktur WSABUF yang ditunjukkan oleh parameter lpCalleeData masing-masing harus diatur ke NULL dan nol. Nilai NULL untuk lpSQOS tidak menunjukkan kualitas layanan yang disediakan aplikasi.
Dicadangkan untuk grup soket di masa mendatang. Parameter lpGQOS menentukan struktur FLOWSPEC untuk grup soket (jika berlaku), satu untuk setiap arah, diikuti oleh parameter khusus penyedia tambahan. Jika tidak ada parameter khusus penyedia yang ditentukan, anggota buf dan len dari struktur WSABUF yang ditunjukkan oleh parameter lpCalleeData harus diatur ke harus diatur ke NULL dan nol. Nilai NULL untuk lpGQOS menunjukkan tidak ada kualitas layanan grup yang disediakan aplikasi. Parameter ini akan diabaikan jika s bukan pembuat grup soket.
Ketika soket yang terhubung berhenti (yaitu, ditutup karena alasan apa pun), soket tersebut harus dibuang dan dibuat ulang. Paling aman untuk berasumsi bahwa ketika semuanya menjadi salah karena alasan apa pun pada soket yang terhubung, aplikasi harus membuang dan membuat ulang soket yang diperlukan untuk kembali ke titik yang stabil.
Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winsock2.h |
| Pustaka | Ws2_32.lib |
| DLL | Ws2_32.dll |