Fungsi panggilan balik LPWSPASYNCSELECT (ws2spi.h)

Artikel
08/28/2023

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

Sintaksis

LPWSPASYNCSELECT Lpwspasyncselect;

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

Parameter

[in] s

Deskriptor yang mengidentifikasi soket tempat pemberitahuan peristiwa diperlukan.

[in] hWnd

Tangani mengidentifikasi jendela yang harus menerima pesan saat 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 BITWISE OR dengan salah satu nilai ini.

Nilai	Arti
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 (QoS) soket.
FD_GROUP_QOS	Dipesan.
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

Penunjuk ke kode kesalahan. Lihat bagian nilai Return untuk informasi selengkapnya.

Mengembalikan nilai

Nilai pengembalian 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	Arti
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	Panggilan Windows Sockets pemblokiran sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAENOTSOCK	Deskriptor bukan soket.

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

Komentar

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 s ke mode nonblocking, terlepas dari nilai lEvent. Lihat LPWSPIoctl tentang cara mengatur soket kembali ke mode pemblokiran.

Memanggil LPWSPAsyncSelect untuk soket membatalkan sebelumnya LPWSPAsyncSelect atau LPWSPEventSelect 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 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 LPWSPAsyncSelect peristiwa yang ditetapkan untuk soket mendengarkan berlaku untuk soket yang diterima. Misalnya, jika soket mendengarkan memiliki LPWSPAsyncSelect peristiwa 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 atau peristiwa wMsg yang berbeda diinginkan, maka klien Windows Sockets SPI harus memanggil LPWSPAsyncSelect, melewati soket yang diterima, dan informasi baru yang diinginkan.

Ketika salah satu peristiwa jaringan yang dicalonkan terjadi padasoket 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 lParam menentukan peristiwa jaringan yang telah terjadi. Kemungkinan kode peristiwa jaringan yang mungkin ditunjukkan adalah sebagai berikut.

Nilai	Arti
FD_READ	Soket s siap untuk dibaca
FD_WRITE	Soket s siap untuk ditulis
FD_OOB	Data di luar band siap untuk dibaca pada soket
FD_ACCEPT	Soket s siap untuk menerima koneksi masuk baru
FD_CONNECT	Koneksi yang dimulai pada soket s telah selesai
FD_CLOSE	Koneksi yang diidentifikasi oleh soket s telah ditutup
FD_QOS	Kualitas layanan yang terkait dengan soket s telah berubah
FD_GROUP_QOS	Dicadangkan untuk digunakan di masa mendatang dengan grup soket: Kualitas layanan yang terkait dengan grup soket tempat soket s 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 diekstrak 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	Arti
WSAEAFNOSUPPORT	Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini.
WSAECONNREFUSED	Upaya untuk menyambungkan 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 waktu habis tanpa membuat koneksi.

Peristiwa : FD_CLOSE

Kode Kesalahan	Arti
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	Arti
WSAENETDOWN	Subsistem jaringan gagal.

Peristiwa : FD_ROUTING_INTERFACE_CHANGE

Kode Kesalahan	Arti
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 tidak boleh 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.

Kejadian 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
FD_CLOSE	TIDAK
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, menghasilkan pengaktifan kembali posting pesan untuk peristiwa yang relevan.

Untuk peristiwa FD_READ, FD_OOB, dan FD_ACCEPT, posting pesan yang dipicu tingkat . Ini berarti bahwa jika rutinitas mengaktifkan 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 sebagaiyang 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 yang 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 karena IOCTL telah dikeluarkan.

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

Klien Windows Sockets SPI memanggil LPWSPListen.
Permintaan koneksi diterima, tetapi belum diterima.
Klien Windows Sockets SPI memanggil LPWSPAsyncSelect 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 saat 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 ketika soket dikonfigurasi untuk menerima data di luar band secara terpisah. Jika soket dikonfigurasi untuk menerima data out-of-band secara sebaris, maka data out-of-band (dipercepat) diperlakukan sebagai data normal, dan klien Windows Sockets SPI harus mendaftarkan minat pada peristiwa FD_READ, bukan FD_OOB peristiwa.

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 dari ujung jarak jauh melakukan LPWSPShutdown di sisi kirim atauLPWSPCloseSocket . Ini benar untuk FD_CLOSE diposting hanya setelah semua data dibaca dari soket.

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

Pesan FD_QOS atau FD_GROUP_QOS diposting ketika ada perubahan pada bidang apa pun dalam spesifikasi alur yang terkait dengan soket s, atau grup soket yang masing-masing milik. 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 dikeluarkan.

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

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.
Ketika data tiba, jika FD_READ belum diposting.
Setelah LPWSPRecv atau LPWSPRecvFrom dipanggil (dengan atau tanpa MSG_PEEK), jika data masih tersedia untuk diterima.

Saat SO_OOBINLINE LPWSPSetSockOpt 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, saat 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 valid saat SO_OOBINLINE LPWSPSetSockOpt dinonaktifkan (default))

Ketika LPWSPAsyncSelect dipanggil, jika saat ini ada data OOB yang 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.
Ketika 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 gagal segera).
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 terus berjalan. 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 valid pada soket berorientasi koneksi (misalnya, SOCK_STREAM))

Ketika LPWSPAsyncSelect dipanggil, jika koneksi soket telah ditutup.
Setelah sistem jarak jauh memulai penutupan yang anggun, 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 anggun, maka FD_CLOSE tidak dikirimkan sampai semua data yang tertunda telah dibaca).
Setelah sistem lokal memulai penutupan 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, RST TCP 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 QOS grup yang terkait dengan soket telah diubah.
Setelah LPWSPIoctl dengan SIO_GET_GROUP_QOS dipanggil, ketika QOS grup 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

Syarat	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

Bagikan melalui