PFN_WSK_RECEIVE_EVENT fungsi panggilan balik (wsk.h)

Artikel
03/05/2024

Fungsi panggilan balik peristiwa WskReceiveEvent memberi tahu aplikasi WSK bahwa data telah diterima pada soket berorientasi koneksi.

Sintaks

PFN_WSK_RECEIVE_EVENT PfnWskReceiveEvent;

NTSTATUS PfnWskReceiveEvent(
  [in, optional] PVOID SocketContext,
  [in]           ULONG Flags,
  [in, optional] PWSK_DATA_INDICATION DataIndication,
  [in]           SIZE_T BytesIndicated,
  [in, out]      SIZE_T *BytesAccepted
)
{...}

Parameter

[in, optional] SocketContext

Penunjuk ke konteks soket untuk soket berorientasi koneksi yang telah menerima data. Aplikasi WSK menyediakan pointer ini ke subsistem WSK dengan salah satu cara berikut:

Ini disebut fungsi WskSocket untuk membuat soket.
Ini disebut fungsi WskSocketConnect untuk membuat soket.
Ini memanggil fungsi WskAccept untuk menerima soket sebagai koneksi masuk.
Fungsi panggilan balik peristiwa WskAcceptEvent dipanggil untuk menerima soket sebagai koneksi masuk.

[in] Flags

Nilai ULONG yang berisi bitwise OR dari kombinasi bendera berikut:

Nilai	Makna
WSK_FLAG_RELEASE_ASAP	Buffer data yang berisi data yang diterima tidak boleh disimpan oleh aplikasi WSK jika memungkinkan. Jika aplikasi WSK mempertahankan buffer, aplikasi tersebut harus melepaskannya sesegera mungkin dengan memanggil fungsi WskRelease .
WSK_FLAG_ENTIRE_MESSAGE	Buffer data berisi seluruh pesan atau bagian akhir pesan. Interpretasi dari apa yang merupakan seluruh pesan adalah protokol transportasi khusus. Untuk TCP, bendera ini menunjukkan bahwa bit pendorongan diatur untuk satu atau beberapa segmen TCP yang merupakan data dalam buffer data.
WSK_FLAG_AT_DISPATCH_LEVEL	Subsistem WSK yang disebut fungsi panggilan balik peristiwa WskReceiveEvent di IRQL = DISPATCH_LEVEL. Jika bendera ini tidak diatur, subsistem WSK mungkin telah memanggil fungsi panggilan balik peristiwa WskReceiveEvent di

[in, optional] DataIndication

Penunjuk ke daftar tertaut struktur WSK_DATA_INDICATION yang menjelaskan data yang diterima. Jika parameter ini NULL, soket tidak lagi berfungsi dan aplikasi WSK harus memanggil fungsi WskCloseSocket untuk menutup soket sesegera mungkin.

[in] BytesIndicated

Jumlah byte data yang diterima yang dijelaskan oleh daftar tertaut struktur WSK_DATA_INDICATION .

[in, out] BytesAccepted

Penunjuk ke variabel SIZE_T-ketik yang menerima jumlah byte data yang diterima oleh aplikasi WSK. Variabel ini perlu diatur hanya jika aplikasi WSK menerima sebagian dari jumlah total byte data yang diterima. Jika aplikasi WSK menerima semua data yang diterima, aplikasi WSK tidak perlu mengatur variabel ini. Jika fungsi panggilan balik peristiwa WskReceiveEvent mengembalikan status selain STATUS_SUCCESS, subsistem WSK mengabaikan nilai variabel ini.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Aplikasi WSK menerima setidaknya beberapa data yang diterima. Jika aplikasi WSK menerima semua data yang diterima, subsistem WSK dapat memanggil fungsi panggilan balik peristiwa WskReceiveEvent lagi ketika data baru diterima di soket. Namun, jika aplikasi WSK hanya menerima sebagian dari data yang diterima, subsistem WSK tidak akan memanggil fungsi panggilan balik peristiwa WskReceiveEvent lagi sampai setelah aplikasi WSK memanggil fungsi WskReceive . Setelah aplikasi WSK memanggil fungsi WskReceive , subsistem WSK akan terus memanggil fungsi panggilan balik peristiwa WskReceiveEvent dengan data buffer yang tersisa dan kapan data baru diterima di soket. Aplikasi WSK dapat memanggil fungsi WskReceive dengan buffer panjang nol, yang akan menyebabkan subsistem WSK dilanjutkan memanggil fungsi panggilan balik peristiwa WskReceiveEvent tanpa memanggil WskReceive untuk menerima data apa pun dari soket.
STATUS_PENDING	Aplikasi WSK menerima data tetapi tidak mengambil semua data yang terkandung dalam daftar tertaut struktur WSK_DATA_INDICATION . Aplikasi WSK mempertahankan daftar tertaut struktur WSK_DATA_INDICATION hingga semua data diambil. Setelah aplikasi WSK mengambil semua data, aplikasi tersebut memanggil fungsi WskRelease untuk merilis daftar tertaut struktur WSK_DATA_INDICATION kembali ke subsistem WSK. Subsistem WSK dapat memanggil fungsi panggilan balik peristiwa WskReceiveEvent lagi ketika data baru diterima di soket.
STATUS_DATA_NOT_ACCEPTED	Aplikasi WSK tidak menerima data. Dalam situasi ini, subsistem WSK akan memiliki buffer transportasi yang mendasar pada data jika memungkinkan atau jika diperlukan oleh protokol. Subsistem WSK tidak akan memanggil fungsi panggilan balik peristiwa WskReceiveEvent lagi sampai setelah aplikasi WSK memanggil fungsi WskReceive . Setelah aplikasi WSK memanggil fungsi WskReceive , subsistem WSK akan terus memanggil fungsi panggilan balik peristiwa WskReceiveEvent dengan data buffer yang tersisa dan kapan data baru diterima di soket. Aplikasi WSK dapat memanggil fungsi WskReceive dengan buffer panjang nol, yang akan menyebabkan subsistem WSK dilanjutkan memanggil fungsi panggilan balik peristiwa WskReceiveEvent tanpa memanggil WskReceive untuk menerima data apa pun dari soket.

Keterangan

Subsistem WSK memanggil fungsi panggilan balik peristiwa WSK aplikasi WSKReceiveEvent saat data baru diterima pada soket berorientasi koneksi 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 WskReceiveEvent aplikasi WSK diaktifkan pada soket berorientasi koneksi dan aplikasi juga memiliki panggilan tertunda ke fungsi WskReceive pada soket berorientasi koneksi yang sama, maka, ketika data tiba, panggilan tertunda ke fungsi WskReceive akan lebih diutamakan daripada fungsi panggilan balik peristiwa WskReceiveEvent . Subsistem WSK memanggil fungsi panggilan balik peristiwa WskReceiveEvent aplikasi hanya jika tidak ada IRP yang diantrekan dari panggilan yang tertunda ke fungsi WskReceive . Namun, aplikasi WSK tidak boleh berasumsi bahwa subsistem WSK tidak akan memanggil fungsi panggilan balik peristiwa WskReceiveEvent aplikasi untuk soket berorientasi koneksi yang memiliki panggilan tertunda ke fungsi WskReceive . Kondisi balapan ada di mana subsistem WSK masih dapat memanggil fungsi panggilan balik peristiwa WskReceiveEvent aplikasi WSK untuk soket. Satu-satunya cara bagi aplikasi WSK untuk memastikan bahwa subsistem WSK tidak akan memanggil fungsi panggilan balik peristiwa WskReceiveEvent aplikasi untuk soket berorientasi koneksi adalah dengan menonaktifkan fungsi panggilan balik peristiwa WskReceiveEvent aplikasi pada soket.

Catatan

Winsock Kernel (WSK) memanggil panggilan balik ini secara serial, sehingga tidak selalu dipanggil segera setelah data diterima.

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

Fungsi panggilan balik peristiwa WskReceiveEvent 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