PFN_WSK_RECEIVE fungsi panggilan balik (wsk.h)

Artikel
08/08/2023

Fungsi WskReceive menerima data melalui soket berorientasi koneksi atau streaming dari alamat transportasi jarak jauh.

Sintaks

PFN_WSK_RECEIVE PfnWskReceive;

NTSTATUS PfnWskReceive(
  [in]      PWSK_SOCKET Socket,
  [in]      PWSK_BUF Buffer,
  [in]      ULONG Flags,
  [in, out] PIRP Irp
)
{...}

Parameter

[in] Socket

Penunjuk ke struktur WSK_SOCKET yang menentukan objek soket untuk soket tempat menerima data.

[in] Buffer

Penunjuk ke struktur WSK_BUF yang diinisialisasi yang menjelaskan buffer data yang menerima data dari soket.

[in] Flags

Nilai ULONG yang berisi bitwise OR dari kombinasi bendera berikut:

WSK_FLAG_WAITALL

Tunggu hingga buffer data benar-benar terisi. Jika bendera ini ditentukan, IRP yang ditentukan dalam parameter Irp tidak akan selesai sampai salah satu peristiwa berikut terjadi:

Buffer data yang dijelaskan oleh struktur WSK_BUF yang ditujukkan oleh parameter Buffer sepenuhnya diisi.
Koneksi terputus dengan baik oleh pengirim jarak jauh.
Koneksi secara abortif terputus oleh aplikasi WSK atau oleh pengirim jarak jauh.
IRP yang ditentukan dibatalkan.

Bendera ini didukung oleh protokol transportasi Microsoft TCP/IP. Bendera ini mungkin tidak didukung oleh protokol transportasi lainnya.

WSK_FLAG_DRAIN

Tunggu hingga soket terputus, membuang data apa pun yang diterima di soket. Jika bendera ini ditentukan, IRP yang ditentukan tidak akan selesai sampai salah satu peristiwa berikut terjadi:

Koneksi terputus dengan baik oleh pengirim jarak jauh.
Koneksi secara abortif terputus oleh aplikasi WSK atau oleh pengirim jarak jauh.
IRP yang ditentukan dibatalkan.

Setiap data yang diterima dibuang oleh subsistem WSK. Tidak ada data yang diterima yang akan disalin ke dalam buffer data. Parameter Buffer masih diperlukan ketika bendera ini ditentukan, tetapi panjang buffer yang dijelaskan oleh struktur WSK_BUF harus nol.

Bendera ini didukung oleh protokol transportasi Microsoft TCP/IP. Bendera ini mungkin tidak didukung oleh protokol transportasi lainnya.

Bendera WSK_FLAG_WAITALL dan WSK_FLAG_DRAIN saling eksklusif. Aplikasi WSK tidak boleh menentukan kedua bendera ini secara bersamaan.

[in, out] Irp

Penunjuk ke IRP yang dialokasikan penelepon yang digunakan subsistem WSK untuk menyelesaikan operasi penerima secara asinkron. Untuk informasi selengkapnya tentang menggunakan runtime integrasi dengan fungsi WSK, lihat Menggunakan IRP dengan Fungsi Kernel Winsock.

Nilai kembali

WskReceive mengembalikan salah satu kode NTSTATUS berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Data berhasil diterima dari soket. IRP akan diselesaikan dengan status keberhasilan. Bidang IoStatus.Information dari IRP berisi jumlah byte yang diterima.
STATUS_PENDING	Subsistem WSK tidak dapat segera menerima data dari soket. Subsistem WSK akan menyelesaikan IRP setelah menerima data dari soket. Status operasi terima akan dikembalikan di bidang IoStatus.Status dari IRP. Jika operasi berhasil, bidang IoStatus.Information dari IRP akan berisi jumlah byte yang diterima.
STATUS_FILE_FORCED_CLOSED	Soket tidak lagi berfungsi. IRP akan diselesaikan dengan status kegagalan. Aplikasi WSK harus memanggil fungsi WskCloseSocket untuk menutup soket sesegera mungkin.
STATUS_NOT_SUPPORTED	Bendera yang ditentukan tidak didukung oleh transportasi jaringan yang mendasar.
Kode status lainnya	Terjadi kesalahan. IRP akan diselesaikan dengan status kegagalan.

Keterangan

Aplikasi WSK dapat memanggil fungsi WskReceive hanya pada soket berorientasi koneksi atau streaming yang sebelumnya telah terhubung ke alamat transportasi jarak jauh. Soket berorientasi koneksi tersambung ke alamat transportasi jarak jauh dengan salah satu metode berikut:

Aplikasi WSK menghubungkan soket dengan memanggil fungsi WskConnect .
Aplikasi WSK membuat, mengikat, dan menyambungkan soket dengan memanggil fungsi WskSocketConnect .
Subsistem WSK menghubungkan soket ketika aplikasi WSK menerima permintaan koneksi masuk pada soket mendengarkan.

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.

Aplikasi WSK dapat memanggil fungsi WskReceive dengan panjang nol yang ditentukan dalam anggota Panjang struktur WSK_BUF yang diacu oleh parameter Buffer . Menentukan panjang nol dalam anggota ini berguna dalam situasi berikut:

Saat mengaktifkan kembali fungsi panggilan balik peristiwa WskReceiveEvent untuk soket setelah fungsi panggilan balik peristiwa WskReceiveEvent yang sebelumnya dikembalikan STATUS_DATA_NOT_ACCEPTED
Saat menentukan bendera WSK_FLAG_DRAIN untuk membuang data tambahan apa pun yang diterima di soket

Jika fungsi WskReceive mengembalikan STATUS_PENDING, rantai MDL yang dijelaskan dalam struktur WSK_BUF yang ditunjukkan oleh parameter Buffer harus tetap terkunci dalam memori hingga IRP selesai.

Persyaratan

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