PFN_WSK_RECEIVE_FROM fungsi panggilan balik (wsk.h)

Artikel
08/08/2023

Fungsi WskReceiveFrom menerima datagram dan informasi kontrol terkait dari alamat transportasi jarak jauh.

Sintaks

PFN_WSK_RECEIVE_FROM PfnWskReceiveFrom;

NTSTATUS PfnWskReceiveFrom(
  [in]            PWSK_SOCKET Socket,
  [in]            PWSK_BUF Buffer,
                  ULONG Flags,
  [out, optional] PSOCKADDR RemoteAddress,
  [in, out]       PULONG ControlLength,
  [out, optional] PCMSGHDR ControlInfo,
  [out, optional] PULONG ControlFlags,
  [in, out]       PIRP Irp
)
{...}

Parameter

[in] Socket

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

[in] Buffer

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

Flags

Parameter ini disediakan untuk penggunaan sistem. Aplikasi WSK harus mengatur parameter ini ke nol.

[out, optional] RemoteAddress

Penunjuk ke buffer yang dialokasikan penelepon yang menerima alamat transportasi jarak jauh tempat datagram yang diterima berasal. Buffer harus terletak di memori non-halaman. Buffer juga harus cukup besar untuk berisi jenis struktur SOCKADDR tertentu yang sesuai dengan keluarga alamat yang ditentukan aplikasi WSK saat membuat soket datagram. Penunjuk ini bersifat opsional dan dapat berupa NULL.

[in, out] ControlLength

Penunjuk ke ULONG yang menentukan ukuran buffer yang diacu oleh parameter ControlInfo . Ketika operasi penerimaan selesai, variabel menerima ukuran informasi kontrol yang terkait dengan datagram yang diterima. Jika nilai yang dikembalikan adalah nol, tidak ada informasi kontrol yang ada untuk datagram. Penunjuk ini bersifat opsional dan dapat berupa NULL. Jika parameter ini NULL, parameter ControlInfo diabaikan.

[out, optional] ControlInfo

Penunjuk ke buffer yang dialokasikan penelepon yang menerima informasi kontrol yang terkait dengan datagram yang diterima. Data informasi kontrol yang terkait dengan datagram terdiri dari satu atau beberapa objek data kontrol, yang masing-masing dimulai dengan struktur CMSGHDR . Jika tidak ada informasi kontrol yang ada untuk datagram yang diterima, konten buffer tidak terdefinisi. Penunjuk ini bersifat opsional dan dapat berupa NULL. Jika parameter ControlInfoLength adalah NULL, parameter ControlInfo harus NULL.

[out, optional] ControlFlags

Penunjuk ke variabel berjenis ULONG yang menerima bitwise OR dari kombinasi bendera berikut:

MSG_BCAST

Datagram diterima sebagai siaran lapisan tautan atau dengan alamat transportasi tujuan yang merupakan alamat siaran.

MSG_MCAST

Datagram diterima dengan alamat transportasi tujuan yang merupakan alamat multicast.

MSG_TRUNC

Datagram dipotok karena ukuran datagram lebih besar dari ukuran buffer yang ditentukan oleh parameter Buffer .

MSG_CTRUNC

Data informasi kontrol terpotok karena jumlah byte informasi kontrol lebih besar dari ukuran buffer yang ditentukan oleh parameter ControlInfo .

Parameter ini bersifat opsional dan dapat berupa NULL.

[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

WskReceiveFrom 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 datagram dari soket. Subsistem WSK akan menyelesaikan IRP setelah menerima datagram 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.
Kode status lainnya	Terjadi kesalahan. IRP akan diselesaikan dengan status kegagalan.

Keterangan

Jika aplikasi WSK telah menetapkan alamat transportasi jarak jauh tetap untuk soket datagram, datagram yang diterima dari alamat transportasi jarak jauh lainnya akan dibuang oleh subsistem WSK. Untuk informasi selengkapnya tentang mengatur alamat transportasi jarak jauh untuk soket datagram, lihat SIO_WSK_SET_REMOTE_ADDRESS.

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

Jika fungsi WskReceiveFrom mengembalikan STATUS_PENDING, rantai MDL yang dijelaskan dalam struktur WSK_BUF yang ditunjukkan oleh parameter Buffer harus tetap terkunci dalam memori hingga IRP selesai. Selain itu, variabel yang ditunjukkan oleh parameter ControlInfoLength , buffer yang ditunjukkan oleh parameter ControlInfo , dan variabel yang ditunjukkan oleh parameter ControlFlags juga harus tetap valid sampai IRP selesai. Jika aplikasi WSK mengalokasikan buffer atau variabel ini dengan salah satu fungsi ExAllocateXxx , aplikasi tidak dapat membebaskan memori dengan fungsi ExFreeXxx yang sesuai sampai setelah IRP selesai. Jika aplikasi WSK mengalokasikan buffer atau variabel ini pada tumpukan, aplikasi tersebut tidak dapat kembali dari fungsi yang memanggil fungsi WskReceiveFrom sampai setelah 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