Fungsi panggilan balik LPWSPJOINLEAF (ws2spi.h)

Artikel
03/15/2023

Fungsi WSPJoinLeaf menggabungkan node daun ke dalam sesi multipoint, bertukar data koneksi, dan menentukan kualitas layanan yang diperlukan berdasarkan spesifikasi alur yang disediakan.

Sintaks

LPWSPJOINLEAF Lpwspjoinleaf;

SOCKET Lpwspjoinleaf(
  [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,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Deskriptor mengidentifikasi soket multipoint.

[in] name

Nama serekan tempat soket dalam struktur sockaddr 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

Arahkan ke spesifikasi alur untuk soket, satu untuk setiap arah.

[in] lpGQOS

Dicadangkan.

[in] dwFlags

Bendera untuk menunjukkan bahwa soket bertindak sebagai pengirim, penerima, atau keduanya.

[out] lpErrno

Arahkan ke kode kesalahan.

Nilai kembali

Jika tidak ada kesalahan yang terjadi, WSPJoinLeaf mengembalikan nilai jenis SOCKET yang merupakan deskriptor untuk soket multipoint yang baru dibuat. Jika tidak, nilai INVALID_SOCKET dikembalikan, dan kode kesalahan tertentu tersedia di lpErrno.

Pada soket pemblokiran, nilai pengembalian menunjukkan keberhasilan atau kegagalan operasi gabungan.

Dengan soket nonblocking, inisiasi operasi gabungan yang berhasil ditunjukkan oleh nilai yang dikembalikan dari deskriptor soket yang valid. Selanjutnya, indikasi FD_CONNECT diberikan ketika operasi gabungan selesai, baik berhasil atau sebaliknya. Kode kesalahan yang terkait dengan FD_CONNECT menunjukkan keberhasilan atau kegagalan WSPJoinLeaf.

Selain itu, sampai upaya gabungan sesi multipoint menyelesaikan semua panggilan berikutnya ke WSPJoinLeaf pada soket yang sama akan gagal dengan kode kesalahan WSAEALREADY. Setelah WSPJoinLeaf 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 WSPJoinLeaf sebelumnya selesai.

Jika kode kesalahan pengembalian menunjukkan upaya gabungan sesi multipoint gagal (yaitu, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) klien SPI Soket Windows dapat memanggil WSPJoinLeaf lagi untuk soket yang sama.

Kode kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAEADDRINUSE	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 bind adalah ke alamat wild-card sebagian (melibatkan ADDR_ANY) dan jika alamat tertentu perlu "diterapkan" pada saat fungsi ini.
WSAEINTR	(Pemblokiran) panggilan dibatalkan melalui WSPCancelBlockingCall.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEALREADY	Panggilan WSPJoinLeaf yang tidak diblokir sedang berlangsung pada soket yang ditentukan.
WSAEADDRNOTAVAIL	Alamat jarak jauh bukan alamat yang valid (misalnya, ADDR_ANY).
WSAEAFNOSUPPORT	Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini.
WSAECONNREFUSED	Upaya untuk bergabung ditolak secara paksa.
WSAEFAULT	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.
WSAEISCONN	Soket sudah menjadi anggota sesi multipoint.
WSAENETUNREACH	Jaringan tidak dapat dijangkau dari host ini saat ini.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia. Soket tidak dapat digabungkan.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Spesifikasi alur yang ditentukan dalam lpSQOS tidak dapat dipenuhi.
WSAEPROTONOSUPPORT	Augment lpCallerData tidak didukung oleh penyedia layanan.
WSAETIMEDOUT	Upaya untuk bergabung kehabisan waktu tanpa membuat sesi multipoint.

Keterangan

Fungsi ini digunakan untuk menggabungkan simpul daun ke sesi multi-titik, dan untuk melakukan sejumlah operasi tambahan lainnya yang terjadi pada waktu bergabung sesi juga. Jika soket, s, tidak terikat, nilai unik ditetapkan ke asosiasi lokal oleh sistem, dan soket ditandai sebagai terikat.

WSPJoinLeaf memiliki parameter dan semantik yang sama dengan LPWSPConnect kecuali bahwa ia mengembalikan deskriptor soket (seperti dalam LPWSPAccept), dan memiliki parameter dwFlags tambahan. Hanya soket multipoint yang dibuat menggunakan LPWSPSocket dengan set bendera multipoint yang sesuai yang dapat digunakan untuk parameter input s dalam fungsi ini. Jika soket berada dalam mode nonblocking, deskriptor soket yang dikembalikan tidak akan dapat digunakan sampai setelah indikasi FD_CONNECT yang sesuai pada soket asli telah diterima, kecuali bahwa closesocket dapat dipanggil pada deskriptor soket baru ini untuk membatalkan operasi gabungan yang tertunda. Simpul akar dalam sesi multipoint dapat memanggil WSPJoinLeaf satu atau beberapa kali untuk menambahkan sejumlah node daun, namun paling banyak satu permintaan koneksi multipoint dapat luar biasa pada satu waktu. Lihat Protocol-Independent Multicast dan Multipoint di SPI 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 "berhasil memulai". Ketika hasil akhir berhasil atau gagal diketahui, itu dapat dilaporkan melalui LPWSPAsyncSelect atau LPWSPEventSelect 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. Perhatikan bahwa LPWSPSelect tidak dapat digunakan untuk mendeteksi pemberitahuan penyelesaian untuk WSPJoinLeaf.

Deskriptor soket yang dikembalikan oleh WSPJoinLeaf 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. (Seperti yang dijelaskan di bagian Alokasi Deskriptor, ketika deskriptor soket baru dialokasikan penyedia IFS harus memanggil penyedia WPUModifyIFSHandle dan non-IFS harus memanggil WPUCreateSocketHandle). Soket yang baru dibuat memiliki properti yang sama dengan termasuk peristiwa asinkron yang terdaftar di LPWSPAsyncSelect atau dengan LPWSPEventSelect. 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 simpul daun yang sesuai memanggil LPWSPCloseSocket untuk keluar dari sesi multipoint. Secara simetris, memanggil WSPCloseSocket pada soket c_leaf yang dikembalikan dari WSPJoinLeaf akan menyebabkan soket di simpul daun yang sesuai mendapatkan pemberitahuan FD_CLOSE.

Ketika WSPJoinLeaf dipanggil dengan soket c_leaf, parameter nama berisi alamat simpul 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 LPWSPListen. Pemberitahuan FD_ACCEPT standar akan dikirimkan ketika node daun meminta untuk bergabung dengan dirinya sendiri ke sesi multipoint. Aplikasi root menggunakan fungsi LPWSPAccept biasa untuk mengakui simpul daun baru. Nilai yang dikembalikan dari WSPAccept juga merupakan deskriptor soket c_leaf seperti yang dikembalikan dari WSPJoinLeaf. 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 WSPJoinLeaf.

Klien Windows Sockets SPI 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 lpCallerData adalah 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. lpCalleeData-len> awalnya berisi panjang buffer yang dialokasikan oleh klien Windows Sockets SPI dan ditunjukkan oleh lpCalleeData-buf.> lpCalleeData-len> akan diatur ke nol jika tidak ada data pengguna yang diteruskan kembali. Informasi lpCalleeData akan valid ketika operasi gabungan multipoint selesai. Untuk memblokir soket, ini akan menjadi ketika fungsi WSPJoinLeaf kembali. Untuk soket nonblocking, ini akan terjadi setelah pemberitahuan FD_CONNECT terjadi pada soket asli. Jika lpCalleeData adalah NULL, tidak ada data pengguna yang akan diteruskan kembali. Format data pengguna yang tepat khusus untuk keluarga alamat tempat soket berada dan/atau aplikasi yang terlibat.

Pada waktu pembentukan sesi multi-titik, klien Windows Sockets SPI dapat menggunakan parameter lpSQOS untuk mengambil alih spesifikasi QoS sebelumnya yang dibuat untuk soket melalui LPWSPIoctl dengan opcode SIO_SET_QOS.

lpSQOS menentukan spesifikasi alur 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 permintaan QoS, kesalahan akan dikembalikan seperti yang ditunjukkan di bawah ini. Nilai spesifikasi alur pengiriman atau penerimaan akan diabaikan, masing-masing, untuk soket searah apa pun. Jika tidak ada parameter khusus penyedia yang disediakan, anggota buf dan len dari lpSQOS-ProviderSpecific masing-masing> harus diatur ke NULL dan nol. Nilai NULL untuk lpSQOS menunjukkan tidak ada kualitas layanan yang disediakan aplikasi.

Parameter dwFlags digunakan untuk menunjukkan apakah soket hanya akan bertindak sebagai pengirim (JL_SENDER_ONLY), hanya sebagai penerima (JL_RECEIVER_ONLY), atau keduanya (JL_BOTH).

**Catatan** Ketika soket yang terhubung putus (artinya, ditutup karena alasan apa pun), soket tersebut harus dibuang dan dibuat ulang. Paling aman untuk berasumsi bahwa ketika segala sesuatunya salah karena alasan apa pun pada soket yang terhubung, klien Windows Sockets SPI harus membuang dan membuat ulang soket yang diperlukan untuk kembali ke titik stabil.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ws2spi.h