LPFN_RIORECEIVE fungsi panggilan balik (mswsock.h)

Fungsi RIOReceive menerima data jaringan pada soket I/O TCP terdaftar yang terhubung atau soket I/O UDP terikat yang terikat untuk digunakan dengan ekstensi I/O terdaftar Winsock.

Sintaks

LPFN_RIORECEIVE LpfnRioreceive;

BOOL LpfnRioreceive(
  RIO_RQ SocketQueue,
  PRIO_BUF pData,
  ULONG DataBufferCount,
  DWORD Flags,
  PVOID RequestContext
)
{...}

Parameter

SocketQueue

Deskriptor yang mengidentifikasi soket TCP I/O terdaftar yang terhubung atau soket UDP I/O terikat yang terdaftar.

pData

Deskripsi bagian buffer terdaftar untuk menerima data.

Parameter ini mungkin NULL untuk soket UDP I/O terikat jika aplikasi tidak perlu menerima payload data dalam datagram UDP.

DataBufferCount

Parameter jumlah buffer data yang menunjukkan apakah data akan diterima di buffer yang ditunjukkan oleh parameter pData .

Parameter ini harus diatur ke nol jika pData adalah NULL. Jika tidak, parameter ini harus diatur ke 1.

Flags

Sekumpulan bendera yang memodifikasi perilaku fungsi RIOReceive .

Parameter Bendera dapat berisi kombinasi opsi berikut, yang ditentukan dalam Mswsockdef.h file header:

RIO_MSG_COMMIT_ONLY

Permintaan sebelumnya yang ditambahkan dengan bendera RIO_MSG_DEFER akan diterapkan.

Ketika bendera RIO_MSG_COMMIT_ONLY diatur, tidak ada bendera lain yang dapat ditentukan. Ketika bendera RIO_MSG_COMMIT_ONLY diatur, argumen pData dan RequestContext harus NULL, dan argumen DataBufferCount harus nol.

Bendera ini biasanya akan digunakan sesekali setelah sejumlah permintaan dikeluarkan dengan set bendera RIO_MSG_DEFER . Ini menghilangkan kebutuhan saat menggunakan bendera RIO_MSG_DEFER untuk membuat permintaan terakhir tanpa bendera RIO_MSG_DEFER , yang menyebabkan permintaan terakhir selesai jauh lebih lambat daripada permintaan lain.

Tidak seperti panggilan lain ke fungsi RIOReceive , ketika bendera RIO_MSG_COMMIT_ONLY diatur panggilan ke fungsi RIOReceive tidak perlu diserialisasikan. Untuk satu RIO_RQ, fungsi RIOReceive dapat dipanggil dengan RIO_MSG_COMMIT_ONLY pada satu utas sambil memanggil fungsi RIOReceive pada utas lain.

RIO_MSG_DONT_NOTIFY

Permintaan tidak boleh memicu fungsi RIONotify ketika penyelesaian permintaan dimasukkan ke dalam antrean penyelesaiannya.

RIO_MSG_DEFER

Permintaan tidak perlu segera dijalankan. Ini akan memasukkan permintaan ke dalam antrean permintaan, tetapi mungkin atau mungkin tidak memicu eksekusi permintaan.

Penerimaan data mungkin tertunda hingga permintaan terima dibuat pada RIO_RQ diteruskan dalam parameter SocketQueue tanpa bendera RIO_MSG_DEFER ditetapkan. Untuk memicu eksekusi untuk semua penerimaan dalam antrean permintaan, panggil fungsi RIOReceive atau RIOReceiveEx tanpa bendera RIO_MSG_DEFER diatur.

Catatan

Permintaan terima dibebankan terhadap kapasitas I/O yang beredar pada RIO_RQ yang diteruskan dalam parameter SocketQueue terlepas dari apakah RIO_MSG_DEFER ditetapkan.

RIO_MSG_WAITALL

Fungsi RIOReceive tidak akan selesai sampai salah satu peristiwa berikut terjadi:

• Segmen buffer yang disediakan oleh pemanggil dalam parameter pData sepenuhnya penuh.
• Sambungan telah ditutup.
• Permintaan telah dibatalkan atau terjadi kesalahan.

Bendera ini tidak didukung pada soket UDP.

RequestContext

Konteks permintaan untuk dikaitkan dengan operasi penerima ini.

Nilai kembali

Jika tidak ada kesalahan yang terjadi, fungsi RIOReceive mengembalikan TRUE. Dalam hal ini, operasi terima berhasil dimulai dan penyelesaian akan telah diantrekan atau operasi telah berhasil dimulai dan penyelesaian akan diantrekan di lain waktu.

Nilai FALSE menunjukkan fungsi gagal, operasi tidak berhasil dimulai dan tidak ada indikasi penyelesaian yang akan diantrekan. Kode kesalahan tertentu dapat diambil dengan memanggil fungsi WSAGetLastError .

Menampilkan kode	Deskripsi
WSAEFAULT	Sistem mendeteksi alamat penunjuk yang tidak valid dalam mencoba menggunakan argumen pointer dalam panggilan. Kesalahan ini dikembalikan jika pengidentifikasi buffer dibatalkan pendaftarannya atau buffer dibebaskan untuk salah satu struktur RIO_BUF yang diteruskan dalam parameter sebelum operasi diantrekan atau dipanggil.
WSAEINVAL	Parameter yang tidak valid diteruskan ke fungsi. Kesalahan ini dikembalikan jika parameter SocketQueue tidak valid, parameter Bendera berisi nilai yang tidak valid untuk operasi penerimaan, atau integritas antrean penyelesaian telah disusupi. Kesalahan ini juga dapat dikembalikan untuk masalah lain dengan parameter.
WSAENOBUFS	Memori yang cukup tidak dapat dialokasikan. Kesalahan ini dikembalikan jika antrean penyelesaian I/O yang terkait dengan parameter SocketQueue penuh atau antrean penyelesaian I/O dibuat dengan entri penerima nol.
WSA_OPERATION_ABORTED	Operasi telah dibatalkan saat operasi penerimaan tertunda. Kesalahan ini dikembalikan jika soket ditutup secara lokal atau jarak jauh, atau perintah SIO_FLUSH di WSAIoctl dijalankan pada soket ini.

Keterangan

Aplikasi dapat menggunakan fungsi RIOReceive untuk menerima data jaringan ke dalam buffer apa pun yang sepenuhnya terkandung dalam satu buffer terdaftar. Anggota Offset dan Length dari struktur RIO_BUF yang diacu oleh parameter pData menentukan di mana data jaringan diterima di buffer.

Setelah fungsi RIOReceive dipanggil, buffer yang diteruskan dalam parameter pData termasuk RIO_BUFFERID di anggota BufferId struktur RIO_BUF harus tetap berlaku selama durasi operasi penerimaan.

Untuk menghindari kondisi balapan, buffer yang terkait dengan permintaan terima tidak boleh dibaca atau ditulis sebelum permintaan selesai. Ini termasuk menggunakan buffer sebagai sumber untuk permintaan kirim atau tujuan untuk permintaan penerimaan lain. Bagian dari buffer terdaftar yang tidak terkait dengan permintaan terima apa pun tidak disertakan dalam pembatasan ini.

Parameter Bendera dapat digunakan untuk memengaruhi perilaku pemanggilan fungsi RIOReceive di luar opsi yang ditentukan untuk soket terkait. Perilaku fungsi ini ditentukan oleh kombinasi opsi soket apa pun yang diatur pada soket yang terkait dengan parameter SocketQueue dan nilai yang ditentukan dalam parameter Bendera .

Catatan

Penunjuk fungsi ke fungsi RIOReceive harus diperoleh pada durasi dengan melakukan panggilan ke fungsi WSAIoctl dengan opcode SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER yang ditentukan. Buffer input yang diteruskan ke fungsi WSAIoctl harus berisi WSAID_MULTIPLE_RIO, pengidentifikasi unik global (GUID) yang nilainya mengidentifikasi fungsi ekstensi I/O terdaftar Winsock. Setelah berhasil, output yang dikembalikan oleh fungsi WSAIoctl berisi pointer ke struktur RIO_EXTENSION_FUNCTION_TABLE yang berisi pointer ke fungsi ekstensi I/O terdaftar Winsock. IOCTL SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER didefinisikan dalam file header Ws2def.h. GUID WSAID_MULTIPLE_RIO didefinisikan dalam file header Mswsock.h .

Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Persyaratan

Persyaratan	Nilai
Header	mswsock.h