PFN_WSK_ACCEPT_EVENT fungsi panggilan balik (wsk.h)

Artikel
08/08/2023

Fungsi panggilan balik peristiwa WskAcceptEvent memberi tahu aplikasi WSK bahwa koneksi masuk pada soket mendengarkan telah diterima.

Sintaks

PFN_WSK_ACCEPT_EVENT PfnWskAcceptEvent;

NTSTATUS PfnWskAcceptEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in]           PSOCKADDR LocalAddress,
  [in]           PSOCKADDR RemoteAddress,
  [in, optional] PWSK_SOCKET AcceptSocket,
  [out]          PVOID *AcceptSocketContext,
  [out]          const WSK_CLIENT_CONNECTION_DISPATCH **AcceptSocketDispatch
)
{...}

Parameter

[in, optional] SocketContext

Penunjuk ke konteks soket untuk soket mendengarkan tempat koneksi masuk diterima. Aplikasi WSK menyediakan pointer ini ke subsistem WSK ketika disebut fungsi WskSocket untuk membuat soket mendengarkan.

[in] Flags

Nilai ULONG yang berisi bendera berikut, atau nol:

WSK_FLAG_AT_DISPATCH_LEVEL

Subsistem WSK yang disebut fungsi panggilan balik peristiwa WskAcceptEvent di IRQL = DISPATCH_LEVEL. Jika bendera ini tidak diatur, subsistem WSK mungkin telah memanggil fungsi panggilan balik peristiwa WskAcceptEvent di IRQL <= DISPATCH_LEVEL.

[in] LocalAddress

Penunjuk ke buffer yang berisi alamat transportasi lokal tempat koneksi masuk tiba. Buffer berisi jenis struktur SOCKADDR tertentu yang sesuai dengan keluarga alamat yang ditentukan aplikasi WSK saat membuat soket mendengarkan.

[in] RemoteAddress

Penunjuk ke buffer yang berisi alamat transportasi jarak jauh tempat koneksi masuk berasal. Buffer berisi jenis struktur SOCKADDR tertentu yang sesuai dengan keluarga alamat yang ditentukan aplikasi WSK saat membuat soket mendengarkan.

[in, optional] AcceptSocket

Penunjuk ke struktur WSK_SOCKET yang merupakan objek soket untuk soket yang diterima. Jika pointer ini NULL, soket mendengarkan tidak lagi berfungsi dan aplikasi WSK harus memanggil fungsi WskCloseSocket untuk menutup soket mendengarkan sesegera mungkin.

[out] AcceptSocketContext

Penunjuk ke variabel yang menerima penunjuk ke konteks yang disediakan aplikasi WSK untuk soket yang sedang diterima. Subsistem WSK meneruskan penunjuk ini ke fungsi panggilan balik peristiwa soket yang diterima. Informasi konteks buram ke subsistem WSK dan harus disimpan dalam memori non-halaman. Jika aplikasi WSK tidak akan mengaktifkan fungsi panggilan balik peristiwa apa pun pada soket yang diterima, aplikasi harus mengatur variabel yang diacu oleh parameter AcceptSocketContext ke NULL.

[out] AcceptSocketDispatch

Penunjuk ke variabel yang menerima penunjuk ke konstanta WSK_CLIENT_CONNECTION_DISPATCH struktur. Struktur ini adalah tabel pengiriman yang berisi pointer ke fungsi panggilan balik peristiwa untuk soket yang diterima. Jika aplikasi WSK tidak akan mengaktifkan semua fungsi panggilan balik peristiwa untuk soket yang diterima, aplikasi harus mengatur pointer dalam tabel pengiriman ke NULL untuk fungsi panggilan balik peristiwa yang tidak diaktifkan. Jika aplikasi WSK tidak akan mengaktifkan fungsi panggilan balik peristiwa apa pun pada soket yang diterima, aplikasi tersebut harus mengatur variabel yang diacu oleh parameter AcceptSocketDispatch ke NULL.

Nilai kembali

Fungsi panggilan balik peristiwa WskAcceptEvent aplikasi WSK dapat mengembalikan salah satu kode NTSTATUS berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Aplikasi WSK menerima koneksi masuk.
STATUS_REQUEST_NOT_ACCEPTED	Aplikasi WSK menolak koneksi masuk. Jika nilai ini dikembalikan, subsistem WSK akan menutup soket yang diterima atas nama aplikasi WSK.

Keterangan

Subsistem WSK memanggil fungsi panggilan balik peristiwa WSK aplikasi WSKAcceptEvent ketika koneksi masuk diterima pada soket mendengarkan hanya jika fungsi panggilan balik peristiwa sebelumnya diaktifkan dengan opsi soket SO_WSK_EVENT_CALLBACK . Untuk informasi selengkapnya tentang mengaktifkan fungsi panggilan balik peristiwa soket, lihat Mengaktifkan dan Menonaktifkan Fungsi Panggilan Balik Peristiwa.

Jika fungsi panggilan balik peristiwa WskAcceptEvent aplikasi WSK diaktifkan pada soket mendengarkan dan aplikasi memiliki panggilan tertunda ke fungsi WskAccept pada soket mendengarkan yang sama, maka, ketika koneksi masuk tiba, panggilan tertunda ke WskAccept lebih diutamakan daripada fungsi panggilan balik peristiwa WskAcceptEvent . Subsistem WSK memanggil fungsi panggilan balik peristiwa WskAcceptEvent aplikasi hanya jika tidak ada IRP yang diantrekan dari panggilan yang tertunda ke fungsi WskAccept . Namun, aplikasi WSK tidak boleh berasumsi bahwa subsistem WSK tidak akan memanggil fungsi panggilan balik peristiwa WskAcceptEvent aplikasi untuk soket mendengarkan yang memiliki panggilan tertunda ke fungsi WskAccept . Kondisi balapan ada di mana subsistem WSK masih dapat memanggil fungsi panggilan balik peristiwa WskAcceptEvent aplikasi WSK untuk soket. Satu-satunya cara bagi aplikasi WSK untuk memastikan bahwa subsistem WSK tidak akan memanggil fungsi panggilan balik peristiwa WskAcceptEvent aplikasi untuk soket mendengarkan adalah dengan menonaktifkan fungsi panggilan balik peristiwa WskAcceptEvent aplikasi pada soket.

Ketika subsistem WSK memanggil fungsi panggilan balik peristiwa WSK aplikasi WSKAcceptEvent , semua fungsi panggilan balik peristiwa pada soket yang diterima dinonaktifkan secara default. Jika aplikasi WSK memungkinkan salah satu fungsi panggilan balik peristiwa soket berorientasi koneksi pada soket mendengarkan, fungsi panggilan balik peristiwa tersebut akan diaktifkan secara default pada semua soket berorientasi koneksi yang diterima pada soket mendengarkan tersebut. Untuk informasi selengkapnya tentang mengaktifkan salah satu fungsi panggilan balik peristiwa soket yang diterima, lihat Mengaktifkan dan Menonaktifkan Fungsi Panggilan Balik Peristiwa.

Struktur SOCKADDR yang ditunjukkan oleh parameter LocalAddress dan RemoteAddress hanya berlaku selama durasi panggilan ke fungsi panggilan balik peristiwa WskAcceptEvent . Jika aplikasi WSK membutuhkan alamat transportasi ini di lain waktu, aplikasi ini dapat menyalin konten struktur ini ke struktur SOCKADDR sendiri sebelum kembali dari fungsi panggilan balik peristiwa WskAcceptEvent , atau nantinya dapat memanggil fungsi WskGetLocalAddress dan WskGetRemoteAddress pada soket yang diterima.

Subsistem WSK mengalokasikan memori untuk struktur objek soket ( WSK_SOCKET) untuk koneksi yang diterima atas nama aplikasi WSK. Subsistem WSK membatalkan alokasi memori ini ketika soket ditutup.

Subsistem WSK memanggil fungsi panggilan balik peristiwa WSK aplikasi WSKAcceptEvent di IRQL <= DISPATCH_LEVEL.

Fungsi panggilan balik peristiwa WSK aplikasi WSK tidak boleh menunggu penyelesaian permintaan WSK lainnya dalam konteks penyelesaian WSK atau fungsi panggilan balik peristiwa. Panggilan balik dapat memulai permintaan WSK lainnya (dengan asumsi bahwa panggilan balik tidak menghabiskan terlalu banyak waktu pada DISPATCH_LEVEL), tetapi tidak boleh menunggu penyelesaiannya bahkan ketika panggilan balik dipanggil di IRQL = PASSIVE_LEVEL.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows Vista dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Windows
Header	wsk.h (termasuk Wsk.h)
IRQL	<= DISPATCH_LEVEL