Fungsi panggilan balik LPWSPASYNCSELECT (ws2spi.h)

Artikel
08/28/2023

Fungsi LPWSPAsyncSelect meminta pemberitahuan peristiwa berbasis pesan Windows dari peristiwa jaringan untuk soket.

Sintaks

LPWSPASYNCSELECT Lpwspasyncselect;

int Lpwspasyncselect(
  [in]  SOCKET s,
  [in]  HWND hWnd,
  [in]  unsigned int wMsg,
  [in]  long lEvent,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Deskriptor mengidentifikasi soket tempat pemberitahuan peristiwa diperlukan.

[in] hWnd

Menangani identifikasi jendela yang harus menerima pesan ketika peristiwa jaringan terjadi.

[in] wMsg

Pesan yang akan dikirim ketika peristiwa jaringan terjadi.

[in] lEvent

Bitmask yang menentukan kombinasi peristiwa jaringan di mana klien antarmuka penyedia layanan (SPI) Windows Sockets tertarik. Dibangun dengan menggunakan operator OR bitwise dengan salah satu nilai ini.

Nilai	Makna
FD_READ	Masalah pemberitahuan kesiapan untuk membaca.
FD_WRITE	Masalah pemberitahuan kesiapan untuk menulis.
FD_OOB	Masalah pemberitahuan kedatangan data OOB.
FD_ACCEPT	Pemberitahuan masalah koneksi masuk.
FD_CONNECT	Pemberitahuan masalah koneksi yang telah selesai.
FD_CLOSE	Masalah pemberitahuan penutupan soket.
FD_QOS	Masalah pemberitahuan perubahan kualitas layanan soket (QoS).
FD_GROUP_QOS	Dicadangkan.
FD_ROUTING_INTERFACE_CHANGE	Masalah pemberitahuan perubahan antarmuka perutean untuk tujuan yang ditentukan.
FD_ADDRESS_ LIST_CHANGE	Masalah pemberitahuan perubahan daftar alamat lokal untuk keluarga protokol soket.

[out] lpErrno

Arahkan ke kode kesalahan. Lihat bagian Nilai pengembalian untuk informasi selengkapnya.

Nilai kembali

Nilai yang dikembalikan adalah nol jika deklarasi minat klien Windows Sockets SPI dalam set peristiwa jaringan berhasil. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu tersedia di lpErrno.

Kode Kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAEINVAL	Menunjukkan bahwa salah satu parameter yang ditentukan tidak valid seperti handel jendela yang tidak merujuk ke jendela yang ada, atau soket yang ditentukan dalam status tidak valid.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAENOTSOCK	Deskriptor bukan soket.

Lihat Keterangan untuk info tentang kode kesalahan tambahan yang dapat diatur (dalam kata tinggi lParam dalam pesan) saat jendela aplikasi menerima pesan.

Keterangan

Fungsi ini digunakan untuk meminta penyedia layanan mengirim pesan Windows ke jendela klien hWnd setiap kali penyedia layanan mendeteksi salah satu peristiwa jaringan yang ditentukan oleh argumen lEvent . Penyedia layanan harus menggunakan fungsi WPUPostMessage untuk memposting pesan. Pesan yang akan dikirim ditentukan oleh parameter wMsg . Soket yang pemberitahuannya diperlukan diidentifikasi oleh s.

Fungsi ini secara otomatis mengatur soket ke mode nonblocking, terlepas dari nilai lEvent. Lihat LPWSPIoctl tentang cara mengatur soket kembali ke mode pemblokiran.

Memanggil LPWSPAsyncSelect untuk soket membatalkan LPWSPAsyncSelect atau LPWSPEventSelect sebelumnya untuk soket yang sama. Misalnya, untuk menerima pemberitahuan untuk membaca dan menulis, klien Windows Sockets SPI harus memanggil LPWSPAsyncSelect dengan FD_READ dan FD_WRITE, seperti ini.

rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);

Tidak dimungkinkan untuk menentukan pesan yang berbeda untuk peristiwa yang berbeda. Kode berikut tidak akan berfungsi; panggilan kedua membatalkan efek dari yang pertama, dan satu-satunya asosiasi adalah peristiwa FD_WRITE yang terkait dengan wMsg2.

// Incorrect example.
rc = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);

Untuk membatalkan semua pemberitahuan (yaitu, untuk menunjukkan bahwa penyedia layanan tidak boleh mengirim pesan lebih lanjut yang terkait dengan peristiwa jaringan pada soket), atur lEvent ke nol.

rc = WSPAsyncSelect(s, hWnd, 0, 0, &error);

Karena soket LPWSPAccept'ed memiliki properti yang sama dengan soket mendengarkan yang digunakan untuk menerimanya, setiap peristiwa LPWSPAsyncSelect yang ditetapkan untuk soket mendengarkan berlaku untuk soket yang diterima. Misalnya, jika soket mendengarkan memiliki peristiwa LPWSPAsyncSelect FD_ACCEPT, FD_READ, dan FD_WRITE, soket apa pun yang diterima pada soket mendengarkan tersebut juga akan memiliki peristiwa FD_ACCEPT, FD_READ, dan FD_WRITE dengan nilai wMsg yang sama yang digunakan untuk pesan. Jika wMsg atau peristiwa yang berbeda diinginkan, maka klien Windows Sockets SPI harus memanggil LPWSPAsyncSelect, meneruskan soket yang diterima, dan informasi baru yang diinginkan.

Ketika salah satu peristiwa jaringan yang dicalonkan terjadi pada soket yang ditentukan, penyedia layanan menggunakan WPUPostMessage untuk mengirim pesan wMsg ke jendela klien Windows Sockets SPI hWnd. Dalam pesan yang diposting, argumen wParam mengidentifikasi soket tempat peristiwa jaringan terjadi. Kata rendah dari lParam menentukan peristiwa jaringan yang telah terjadi. Kemungkinan kode peristiwa jaringan yang mungkin ditunjukkan adalah sebagai berikut.

Nilai	Makna
FD_READ	Soket siap dibaca
FD_WRITE	Soket siap untuk menulis
FD_OOB	Data di luar band siap dibaca di soket
FD_ACCEPT	Soket siap menerima koneksi masuk baru
FD_CONNECT	Koneksi yang dimulai pada soket telah selesai
FD_CLOSE	Koneksi yang diidentifikasi oleh soket telah ditutup
FD_QOS	Kualitas layanan yang terkait dengan soket telah berubah
FD_GROUP_QOS	Dicadangkan untuk penggunaan di masa mendatang dengan grup soket: Kualitas layanan yang terkait dengan grup soket tempat soket miliknya telah berubah
FD_ROUTING_INTERFACE_CHANGE	Antarmuka lokal yang harus digunakan untuk mengirim ke tujuan yang ditentukan telah berubah
FD_ADDRESS_LIST_CHANGE	Daftar alamat keluarga protokol soket tempat klien Windows Sockets SPI dapat mengikat telah berubah

Kata tinggi lParam berisi kode kesalahan apa pun (dapat diekstraksi dengan menggunakan makro WSAGETSELECTERROR ). Kode kesalahan adalah kesalahan apa pun seperti yang didefinisikan dalam ws2spi.h. Kemungkinan kode kesalahan untuk setiap peristiwa jaringan tercantum dalam tabel berikut.

Peristiwa: FD_CONNECT

Kode Kesalahan	Makna
WSAEAFNOSUPPORT	Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini.
WSAECONNREFUSED	Upaya untuk tersambung ditolak.
WSAENETUNREACH	Jaringan tidak dapat dijangkau dari host ini saat ini.
WSAEFAULT	Parameter namelen tidak valid.
WSAEINVAL	Soket sudah terikat ke alamat.
WSAEISCONN	Soket sudah tersambung.
WSAEMFILE	Tidak ada lagi deskriptor file yang tersedia.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia. Soket tidak dapat dihubungkan.
WSAENOTCONN	Soket tidak tersambung.
WSAETIMEDOUT	Coba sambungkan kehabisan waktu tanpa membuat koneksi.

Peristiwa: FD_CLOSE

Kode Kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAECONNRESET	Koneksi direset oleh sisi jarak jauh.
WSAECONNABORTED	Koneksi dihentikan karena waktu habis atau kegagalan lainnya.

Peristiwa...: FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE

Kode Kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.

Peristiwa: FD_ROUTING_INTERFACE_CHANGE

Kode Kesalahan	Makna
WSAENETUNREACH	Tujuan yang ditentukan tidak lagi dapat dijangkau.
WSAENETDOWN	Subsistem jaringan gagal.

Meskipun LPWSPAsyncSelect dapat dipanggil dengan minat pada beberapa peristiwa, penyedia layanan mengeluarkan pesan Windows yang sama untuk setiap peristiwa.

Penyedia Windows Sockets 2 seharusnya tidak terus membanjiri klien Windows Sockets SPI dengan pesan untuk peristiwa jaringan tertentu. Setelah berhasil memposting pemberitahuan peristiwa tertentu ke jendela klien Windows Sockets SPI, tidak ada pesan lebih lanjut untuk peristiwa jaringan tersebut yang akan diposting ke jendela klien Windows Sockets SPI hingga klien Windows Sockets SPI melakukan panggilan fungsi yang secara implisit mengaktifkan kembali pemberitahuan peristiwa jaringan tersebut.

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 perintah SIO_ADDRESS_LIST_CHANGE

Setiap panggilan ke rutinitas pengaktifan kembali, bahkan panggilan yang gagal, menghasilkan pengaktifan kembali posting pesan untuk peristiwa yang relevan.

Untuk peristiwa FD_READ, FD_OOB, dan FD_ACCEPT, pengiriman pesan dipicu tingkat. Ini berarti bahwa jika rutinitas pengaktifan kembali dipanggil dan kondisi yang relevan masih terpenuhi setelah panggilan, pesan LPWSPAsyncSelect diposting ke klien Windows Sockets SPI.

Peristiwa FD_QOS dan FD_GROUP_QOS dianggap dipicu tepi. Pesan akan diposting tepat sekali ketika perubahan QOS terjadi. Pesan lebih lanjut tidak akan datang sampai penyedia 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 secara sesuai. Pesan lebih lanjut tidak akan masuk sampai klien Windows Sockets SPI menerbitkan ulang IOCTL dan perubahan lain terdeteksi karena IOCTL telah diterbitkan.

Jika ada peristiwa yang telah terjadi ketika klien Windows Sockets SPI memanggil LPWSPAsyncSelect, atau ketika fungsi pengaktifan kembali dipanggil, maka pesan diposting sebagaimana mewajibkan. Misalnya, pertimbangkan urutan berikut.

Klien Windows Sockets SPI memanggil LPWSPListen.
Permintaan koneksi diterima, tetapi belum diterima.
Klien Windows Sockets SPI memanggil LPWSPAsyncSelect yang menentukan bahwa klien ingin menerima pesan FD_ACCEPT untuk soket. Karena kegigihan peristiwa, penyedia layanan WinSock segera memposting pesan FD_ACCEPT.

Peristiwa FD_WRITE ditangani sedikit berbeda. Pesan FD_WRITE diposting ketika soket pertama kali terhubung dengan LPWSPConnect (setelah FD_CONNECT, jika juga terdaftar) 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 pesan FD_WRITE pertama dan berlangsung hingga pengiriman mengembalikan WSAEWOULDBLOCK. Setelah kegagalan seperti itu, klien Windows Sockets SPI akan diberi tahu bahwa pengiriman kembali dimungkinkan dengan pesan FD_WRITE.

Peristiwa FD_OOB hanya digunakan saat soket dikonfigurasi untuk menerima data out-of-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 pada peristiwa FD_READ, bukan peristiwa FD_OOB.

Kode kesalahan dalam pesan 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.

Pesan FD_CLOSE diposting ketika indikasi dekat diterima untuk sirkuit virtual yang sesuai dengan soket. Dalam istilah TCP, ini berarti bahwa FD_CLOSE diposting ketika koneksi masuk ke status TIME WAIT atau CLOSE WAIT. Hasil ini dari akhir jarak jauh yang melakukan LPWSPShutdown di sisi kirim atau LPWSPCloseSocket. Benar bagi FD_CLOSE untuk diposting hanya setelah semua data dibaca dari soket.

Dalam kasus penutupan dengan baik, penyedia layanan harus mengirim pesan FD_CLOSE untuk menunjukkan penutupan sirkuit virtual hanya setelah semua data yang diterima dibaca. Seharusnya tidak mengirim pesan FD_READ untuk menunjukkan kondisi ini.

Pesan FD_QOS atau FD_GROUP_QOS diposting ketika telah ada perubahan pada bidang apa pun dalam spesifikasi alur yang terkait dengan soket , atau grup soket milik masing-masing. Penyedia layanan harus memperbarui informasi QOS yang tersedia untuk klien melalui LPWSPIoctl dengan SIO_GET_QOS dan/atau SIO_GET_GROUP_QOS.

Pesan FD_ROUTING_INTERFACE_CHANGE diposting ketika antarmuka lokal yang harus digunakan untuk mencapai tujuan yang ditentukan dalam LPWSPIoctl dengan perubahan SIO_ROUTING_INTERFACE_CHANGE setelah IOCTL tersebut diterbitkan.

Pesan FD_ADDRESS_LIST_CHANGE diposting ketika daftar alamat tempat klien Windows Sockets SPI dapat mengikat perubahan setelahLPWSPIoctl dengan SIO_ADDRESS_LIST_CHANGE diterbitkan.

Berikut adalah ringkasan peristiwa dan kondisi untuk setiap pesan pemberitahuan asinkron.

FD_READ

Ketika LPWSPAsyncSelect dipanggil, jika saat ini ada data yang tersedia untuk diterima.
Saat data tiba, jika FD_READ belum diposting.
Setelah LPWSPRecv atau LPWSPRecvFrom dipanggil (dengan atau tanpa MSG_PEEK), jika data masih tersedia untuk diterima.

Ketika LPWSPSetSockOpt SO_OOBINLINE diaktifkan, data menyertakan data normal dan data out-of-band (OOB) dalam instans yang disebutkan di atas.

FD_WRITE

Ketika LPWSPAsyncSelect dipanggil, jika LPWSPSend atau LPWSPSendTo dimungkinkan.
Setelah LPWSPConnect atau LPWSPAccept dipanggil, ketika koneksi dibuat.
Setelah LPWSPSend atau LPWSPSendTo gagal dengan WSAEWOULDBLOCK, ketika LPWSPSend atau LPWSPSendTo kemungkinan akan berhasil.
Setelah LPWSPBind pada soket tanpa koneksi. FD_WRITE mungkin atau mungkin tidak terjadi saat ini (tergantung implementasi). Bagaimanapun, soket tanpa koneksi selalu dapat ditulis segera setelah LPWSPBind.

FD_OOB (hanya berlaku saat SO_OOBINLINE LPWSPSetSockOpt dinonaktifkan (default))

Ketika LPWSPAsyncSelect dipanggil, jika ada data OOB yang saat ini tersedia untuk diterima dengan bendera MSG_OOB.
Ketika data OOB tiba, jika FD_OOB belum diposting.
Setelah LPWSPRecv atau LPWSPRecvFrom dipanggil dengan atau tanpa bendera MSG_OOB, jika data OOB masih tersedia untuk diterima.

FD_ACCEPT

Ketika LPWSPAsyncSelect dipanggil, jika saat ini ada permintaan koneksi yang tersedia untuk diterima.
Saat permintaan koneksi tiba, jika FD_ACCEPT belum diposting.
Setelah LPWSPAccept dipanggil, jika ada permintaan koneksi lain yang tersedia untuk diterima.

FD_CONNECT

Ketika LPWSPAsyncSelect dipanggil, jika saat ini ada koneksi yang dibuat.
Setelah LPWSPConnect dipanggil, ketika koneksi dibuat (bahkan ketika LPWSPConnect segera berhasil, seperti biasa dengan soket datagram), dan bahkan ketika segera gagal).
Setelah WSPJoinLeaf dipanggil, ketika operasi gabungan selesai.
Setelah menyambungkan, WSAConnect, atau WSPJoinLeaf dipanggil dengan soket yang tidak memblokir dan berorientasi koneksi. Operasi awal dikembalikan dengan kesalahan tertentu dari WSAEWOULDBLOCK, tetapi operasi jaringan dilanjutkan. Apakah operasi akhirnya berhasil atau tidak, ketika hasilnya telah ditentukan, FD_CONNECT terjadi. Klien harus memeriksa kode kesalahan untuk menentukan apakah hasilnya berhasil atau gagal.

FD_CLOSE (hanya berlaku pada soket berorientasi koneksi (misalnya, SOCK_STREAM))

Ketika LPWSPAsyncSelect dipanggil, jika koneksi soket telah ditutup.
Setelah sistem jarak jauh memulai penutupan yang lancar, ketika tidak ada data yang saat ini tersedia untuk diterima (jika data telah diterima dan menunggu untuk dibaca ketika sistem jarak jauh memulai penutupan yang lancar, maka FD_CLOSE tidak dikirimkan sampai semua data yang tertunda telah dibaca).
Setelah sistem lokal memulai penutupan dengan baik dengan LPWSPShutdown dan sistem jarak jauh telah merespons dengan pemberitahuan akhir data (seperti TCP FIN), ketika tidak ada data yang saat ini tersedia untuk diterima.
Ketika sistem jarak jauh membatalkan koneksi (misalnya, TCP RST yang dikirim), dan lParam akan berisi nilai kesalahan WSAECONNRESET.

FD_CLOSE tidak diposting setelah LPWSPCloseSocket dipanggil.

FD_QOS

Ketika LPWSPAsyncSelect dipanggil, jika QOS yang terkait dengan soket telah diubah.
Setelah LPWSPIoctl dengan SIO_GET_QOS dipanggil, ketika QOS diubah.

FD_GROUP_QOS

Dicadangkan untuk digunakan di masa mendatang dengan grup soket:

Ketika LPWSPAsyncSelect dipanggil, jika grup QOS yang terkait dengan soket telah diubah.
Setelah LPWSPIoctl dengan SIO_GET_GROUP_QOS dipanggil, ketika grup QOS diubah.

FD_ROUTING_INTERFACE_CHANGE

setelah LPWSPIoctl dengan SIO_ROUTING_INTERFACE_CHANGE dipanggil, ketika antarmuka lokal yang harus digunakan untuk mencapai tujuan yang ditentukan dalam perubahan IOCTL.

FD_ADDRESS_LIST_CHANGE

setelah LPWSPIoctl dengan SIO_ADDRESS_LIST_CHANGE dipanggil, ketika daftar alamat lokal tempat klien Windows Sockets SPI dapat mengikat perubahan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10 Build 20348
Server minimum yang didukung	Windows 10 Build 20348
Header	ws2spi.h

Lihat juga

Fungsi panggilan balik LPWSPAsyncSelect