Fungsi panggilan balik LPWSPEVENTSELECT (ws2spi.h)
Fungsi LPWSPEventSelect menentukan objek peristiwa yang akan dikaitkan dengan serangkaian peristiwa jaringan yang disediakan.
Sintaks
LPWSPEVENTSELECT Lpwspeventselect;
int Lpwspeventselect(
[in] SOCKET s,
[in] WSAEVENT hEventObject,
[in] long lNetworkEvents,
[out] LPINT lpErrno
)
{...}
Parameter
[in] s
Deskriptor yang mengidentifikasi soket.
[in] hEventObject
Handel yang mengidentifikasi objek peristiwa yang akan dikaitkan dengan serangkaian peristiwa jaringan yang disediakan.
[in] lNetworkEvents
Bitmask yang menentukan kombinasi peristiwa jaringan di mana klien Windows Sockets SPI memiliki minat. Dibangun dengan menggunakan operator OR bitwise dengan salah satu nilai ini.
| Nilai | Makna |
|---|---|
|
Masalah pemberitahuan kesiapan untuk membaca. |
|
Masalah pemberitahuan kesiapan untuk menulis. |
|
Masalah pemberitahuan kedatangan data OOB. |
|
Pemberitahuan masalah koneksi masuk. |
|
Pemberitahuan masalah koneksi yang telah selesai. |
|
Masalah pemberitahuan penutupan soket. |
|
Masalah pemberitahuan perubahan soket (QoS). |
|
Dicadangkan. |
|
Masalah pemberitahuan perubahan antarmuka perutean untuk tujuan yang ditentukan. |
|
Masalah pemberitahuan perubahan daftar alamat lokal untuk keluarga alamat soket. |
[out] lpErrno
Penunjuk ke kode kesalahan. Lihat bagian Nilai pengembalian untuk informasi selengkapnya.
Nilai kembali
Nilai yang dikembalikan adalah nol jika spesifikasi klien Windows Sockets SPI dari peristiwa jaringan dan objek peristiwa terkait berhasil. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan nomor kesalahan tertentu tersedia di lpErrno.
| Kode Kesalahan | Makna |
|---|---|
| Subsistem jaringan gagal. | |
| Menunjukkan bahwa salah satu parameter yang ditentukan tidak valid, atau soket yang ditentukan dalam status tidak valid. | |
| Pemblokiran panggilan Windows Sockets sedang berlangsung atau penyedia layanan masih memproses fungsi panggilan balik. | |
| Deskriptor bukan soket. |
Keterangan
Fungsi ini digunakan untuk menentukan objek peristiwa, hEventObject, untuk dikaitkan dengan peristiwa jaringan yang dipilih, lNetworkEvents. Soket tempat objek peristiwa ditentukan diidentifikasi oleh s. Objek peristiwa diatur ketika salah satu peristiwa jaringan yang dicalonkan terjadi.
LPWSPEventSelect beroperasi sangat mirip dengan LPWSPAsyncSelect, perbedaannya adalah dalam tindakan yang diambil ketika peristiwa jaringan yang dicalonkan terjadi. Sedangkan WSPAsyncSelect menyebabkan pesan Windows yang ditentukan klien Windows Sockets SPI diposting, LPWSPEventSelect mengatur objek peristiwa terkait dan merekam kejadian ini dalam rekaman peristiwa jaringan internal. Klien Windows Sockets SPI dapat menggunakan LPWSPEnumNetworkEvents untuk mengambil konten rekaman peristiwa jaringan internal, dan dengan demikian menentukan peristiwa jaringan mana yang dicalonkan telah terjadi.
LPWSPEventSelect adalah satu-satunya fungsi yang menyebabkan aktivitas dan kesalahan jaringan dicatat dan diambil melalui LPWSPEnumNetworkEvents. Lihat deskripsi LPWSPSelect dan LPWSPAsyncSelect untuk mengetahui bagaimana fungsi tersebut melaporkan aktivitas dan kesalahan jaringan.
Fungsi ini secara otomatis mengatur soket ke mode nonblocking, terlepas dari nilai lNetworkEvents.
Mengeluarkan LPWSPEventSelect untuk soket membatalkan LPWSPAsyncSelect atau LPWSPEventSelect sebelumnya untuk soket yang sama, dan menghapus rekaman peristiwa jaringan internal. Misalnya, untuk mengaitkan objek peristiwa dengan membaca dan menulis peristiwa jaringan, klien Windows Sockets SPI harus memanggil LPWSPEventSelect dengan FD_READ dan FD_WRITE, seperti ini.
rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);
Tidak dimungkinkan untuk menentukan objek peristiwa yang berbeda untuk peristiwa jaringan yang berbeda. Kode berikut tidak akan berfungsi; panggilan kedua membatalkan efek yang pertama, dan satu-satunya asosiasi adalah peristiwa jaringan FD_WRITE yang terkait dengan hEventObject2.
// Incorrect example.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE);
Untuk membatalkan asosiasi dan pemilihan peristiwa jaringan pada soket, Anda harus mengatur lNetworkEvents ke nol, dalam hal ini parameter hEventObject diabaikan.
rc = WSPEventSelect(s, hEventObject, 0);
Menutup soket dengan LPWSPCloseSocket juga membatalkan asosiasi dan pemilihan peristiwa jaringan yang ditentukan dalam LPWSPEventSelect untuk soket. Namun, klien Windows Sockets SPI masih harus memanggil WSACloseEvent untuk secara eksplisit menutup objek peristiwa, dan membebaskan sumber daya apa pun.
Karena soket LPWSPAccept'ed memiliki properti yang sama dengan soket mendengarkan yang digunakan untuk menerimanya, setiap asosiasi LPWSPEventSelect dan pemilihan peristiwa jaringan yang ditetapkan untuk soket mendengarkan berlaku untuk soket yang diterima. Misalnya, jika soket mendengarkan memiliki asosiasi LPWSPEventSelecthEventObject dengan FD_ACCEPT, FD_READ, dan FD_WRITE, maka soket apa pun yang diterima pada soket mendengarkan tersebut juga akan memiliki peristiwa jaringan FD_ACCEPT, FD_READ, dan FD_WRITE yang terkait dengan hEventObject yang sama. Jika hEventObject atau peristiwa jaringan yang berbeda diinginkan, maka klien Windows Sockets SPI harus memanggil LPWSPEventSelect, meneruskan soket yang diterima, dan informasi baru yang diinginkan.
Setelah berhasil merekam terjadinya peristiwa jaringan dan memberi sinyal objek peristiwa terkait, tidak ada tindakan lebih lanjut yang diambil untuk peristiwa jaringan tersebut sampai klien Windows Sockets SPI melakukan panggilan fungsi yang secara implisit mengaktifkan kembali pengaturan peristiwa jaringan tersebut dan sinyal objek peristiwa terkait.
| Peristiwa jaringan | Mengaktifkan kembali fungsi |
|---|---|
| FD_READ | LPWSPRecv atau LPWSPRecvFrom |
| FD_WRITE | LPWSPSend atau LPWSPSendTo |
| FD_OOB | LPWSPRecv atau LPWSPRecvFrom |
| FD_ACCEPT | LPWSPAccept, kecuali kode kesalahan yang dikembalikan WSATRY_AGAIN menunjukkan bahwa fungsi kondisi dikembalikan CF_DEFER |
| FD_CONNECT | TIDAK ADA |
| FD_CLOSE | TIDAK ADA |
| FD_QOS | LPWSPIoctl dengan SIO_GET_QOS |
| FD_GROUP_QOS | Dicadangkan untuk digunakan di masa mendatang dengan grup soket: LPWSPIoctl dengan SIO_GET_GROUP_QOS |
| FD_ROUTING_INTERFACE_CHANGE | LPWSPIoctl dengan perintah SIO_ROUTING_INTERFACE_CHANGE |
| FD_ADDRESS_LIST_CHANGE | LPWSPIoctl dengan SIO_ADDRESS_LIST_CHANGE perintah |
Setiap panggilan ke mengaktifkan kembali rutinitas, bahkan yang gagal, mengakibatkan pengaktifan kembali perekaman dan sinyal untuk peristiwa jaringan dan objek peristiwa yang relevan, masing-masing.
Untuk peristiwa jaringan FD_READ, FD_OOB, dan FD_ACCEPT, perekaman peristiwa jaringan dan sinyal objek peristiwa dipicu tingkat. Ini berarti bahwa jika rutinitas pengaktifan kembali dipanggil, dan kondisi jaringan yang relevan masih valid setelah panggilan, maka peristiwa jaringan direkam dan objek peristiwa terkait disinyalir. Ini memungkinkan klien Windows Sockets SPI untuk digerakkan oleh peristiwa sekaligus tidak peduli dengan jumlah data yang tiba kapan saja. Pertimbangkan urutan berikut ini.
- Penyedia layanan menerima 100 byte data pada soket, merekam peristiwa jaringan FD_READ, dan memberi sinyal objek peristiwa terkait.
- Klien Windows Sockets SPI bermasalah
WSPRecv(s, buffptr, 50, 0)untuk membaca 50 byte. - Penyedia layanan merekam peristiwa jaringan FD_READ, dan memberi sinyal objek peristiwa terkait lagi karena masih ada data yang akan dibaca.
Dengan semantik ini, klien Windows Sockets SPI tidak perlu membaca semua data yang tersedia sebagai respons terhadap peristiwa jaringan FD_READ. Sebaliknya, satu LPWSPRecv sebagai respons terhadap setiap peristiwa jaringan FD_READ sesuai.
Peristiwa FD_QOS dan FD_GROUP_QOS dianggap dipicu tepi. Pesan akan diposting tepat sekali ketika perubahan kualitas layanan (QOS) terjadi. Indikasi lebih lanjut tidak akan dikeluarkan sampai penyedia layanan mendeteksi perubahan lebih lanjut di QOS, atau klien Windows Sockets SPI menegosiasikan ulang QOS untuk soket.
Peristiwa FD_ROUTING_INTERFACE_CHANGE dan FD_ADDRESS_LIST_CHANGE juga dianggap dipicu tepi . Pesan akan diposting tepat sekali ketika perubahan terjadi setelah klien Windows Sockets SPI meminta pemberitahuan dengan mengeluarkan WSAIoctl dengan SIO_ROUTING_INTERFACE_CHANGE atau SIO_ADDRESS_LIST_CHANGE yang sesuai. Pesan lebih lanjut tidak akan masuk sampai klien Windows Sockets SPI menerbitkan kembali IOCTL dan perubahan lain terdeteksi sejak IOCTL dikeluarkan.
Jika peristiwa jaringan telah terjadi ketika klien Windows Sockets SPI memanggil LPWSPEventSelect, atau ketika fungsi pengaktifan kembali dipanggil, maka peristiwa jaringan direkam dan objek peristiwa terkait disinyalkan, sebagaimana merujuk. Misalnya, pertimbangkan urutan berikut.
- Klien Windows Sockets SPI memanggil LPWSPListen.
- Permintaan koneksi diterima, tetapi belum diterima.
- Klien Windows Sockets SPI memanggil LPWSPEventSelect yang menentukan bahwa klien tertarik pada peristiwa jaringan FD_ACCEPT untuk soket. Penyedia layanan merekam peristiwa jaringan FD_ACCEPT, dan segera memberi sinyal objek peristiwa terkait.
Peristiwa jaringan FD_WRITE ditangani sedikit berbeda. Peristiwa jaringan FD_WRITE direkam ketika soket pertama kali terhubung dengan LPWSPConnect atau diterima dengan LPWSPAccept, dan kemudian setelah LPWSPSend atau LPWSPSendTo gagal dengan WSAEWOULDBLOCK dan ruang buffer tersedia. Oleh karena itu, klien Windows Sockets SPI dapat mengasumsikan bahwa pengiriman dimungkinkan mulai dari pengaturan peristiwa jaringan FD_WRITE pertama, dan berlangsung hingga pengiriman mengembalikan WSAEWOULDBLOCK. Setelah kegagalan seperti itu, klien Windows Sockets SPI akan menemukan bahwa pengiriman kembali dimungkinkan ketika peristiwa jaringan FD_WRITE direkam dan objek peristiwa terkait disinyalkan.
Peristiwa jaringan FD_OOB hanya digunakan saat soket dikonfigurasi untuk menerima data di luar band secara terpisah. Jika soket dikonfigurasi untuk menerima data out-of-band sejajar, maka data out-of-band (dipercepat) diperlakukan sebagai data normal, dan klien Windows Sockets SPI harus mendaftarkan minat, dan akan mendapatkan, FD_READ peristiwa jaringan, bukan FD_OOB peristiwa jaringan. Klien Windows Sockets SPI dapat mengatur atau memeriksa cara di mana data out-of-band akan ditangani dengan menggunakan LPWSPSetSockOpt atau LPWSPGetSockOpt untuk opsi SO_OOBINLINE.
Kode kesalahan dalam peristiwa jaringan FD_CLOSE menunjukkan apakah penutupan soket anggun, atau abortif. Jika kode kesalahan adalah 0, maka penutupannya adalah anggun; jika kode kesalahan adalah WSAECONNRESET, maka sirkuit virtual soket diatur ulang. Ini hanya berlaku untuk soket berorientasi koneksi seperti SOCK_STREAM.
Peristiwa jaringan FD_CLOSE direkam ketika indikasi dekat diterima untuk sirkuit virtual yang sesuai dengan soket. Dalam istilah TCP, ini berarti bahwa FD_CLOSE direkam ketika koneksi masuk ke status FIN WAIT atau CLOSE WAIT. Hasil ini dari akhir jarak jauh yang melakukan LPWSPShutdown di sisi pengiriman, atau LPWSPCloseSocket.
Penyedia layanan hanya boleh merekam peristiwa jaringan FD_CLOSE untuk menunjukkan penutupan sirkuit virtual; seharusnya tidak merekam peristiwa jaringan FD_READ untuk menunjukkan kondisi tersebut.
Peristiwa jaringan FD_QOS atau FD_GROUP_QOS direkam ketika telah ada perubahan pada bidang apa pun dalam spesifikasi alur yang terkait dengan soket , atau grup soket milik masing-masing. Perubahan ini harus tersedia untuk klien Windows Sockets SPI melalui fungsi LPWSPIoctl dengan SIO_GET_QOS dan/atau SIO_GET_GROUP_QOS untuk mengambil QOS saat ini untuk soket , atau untuk grup soket milik masing-masing.
Peristiwa jaringan FD_ROUTING_INTERFACE_CHANGE direkam ketika antarmuka lokal yang harus digunakan untuk mencapai tujuan yang ditentukan di WSAIoctl dengan perubahan SIO_ROUTING_INTERFACE_CHANGE setelah IOCTL tersebut diterbitkan.
Peristiwa jaringan FD_ADDRESS_LIST_CHANGE direkam ketika daftar alamat keluarga protokol soket tempat klien Windows Sockets SPI dapat mengikat perubahan setelahWSAIoctl dengan SIO_ADDRESS_LIST_CHANGE diterbitkan.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 10 Build 20348 |
| Server minimum yang didukung | Windows 10 Build 20348 |
| Header | ws2spi.h |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk