LPFN_WSARECVMSG fungsi panggilan balik (mswsock.h)

Artikel
03/16/2023

LPFN_WSARECVMSG adalah jenis penunjuk fungsi. Anda menerapkan fungsi panggilan balik WSARecvMsg yang cocok di aplikasi Anda. Sistem menggunakan fungsi panggilan balik Anda untuk mengirimkan data dalam memori, atau data file, melalui soket yang terhubung.

Fungsi panggilan balik WSARecvMsg Anda menerima informasi data/kontrol tambahan dengan pesan, dari soket yang tersambung dan tidak terhubung.

Catatan

Fungsi ini adalah ekstensi khusus Microsoft untuk spesifikasi Windows Sockets.

Sintaks

LPFN_WSARECVMSG LpfnWsarecvmsg;

INT LpfnWsarecvmsg(
  SOCKET s,
  LPWSAMSG lpMsg,
  LPDWORD lpdwNumberOfBytesRecvd,
  LPWSAOVERLAPPED lpOverlapped,
  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
)
{...}

Parameter

s

Ketik: _In_ SOCKET

Deskriptor yang mengidentifikasi soket.

lpMsg

Jenis: _Inout_ LPWSAMSG

Penunjuk ke struktur WSAMSG berdasarkan spesifikasi Posix.1g untuk struktur msghdr.

lpdwNumberOfBytesRecvd

Jenis: _Out_opt_ LPDWORD

Pointer ke DWORD yang berisi jumlah byte yang diterima oleh panggilan ini jika operasi WSARecvMsg segera selesai.

Untuk menghindari hasil yang berpotensi salah, berikan NULL untuk parameter ini jika parameter lpOverlapped bukan NULL . Parameter ini dapat berupa NULL hanya jika parameter lpOverlapped bukan NULL.

lpOverlapped

Jenis: _Inout_opt_ LPWSAOVERLAPPED

Penunjuk ke struktur WSAOVERLAPPED . Diabaikan untuk struktur yang tidak tumpang tindih.

lpCompletionRoutine

Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi penerima selesai. Diabaikan untuk struktur yang tidak tumpang tindih.

Nilai kembali

Jika tidak ada kesalahan yang terjadi dan operasi penerimaan telah segera selesai, WSARecvMsg mengembalikan nol. Dalam hal ini, rutinitas penyelesaian akan dijadwalkan untuk dipanggil setelah utas panggilan berada dalam status yang dapat diperingatkan. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError. Kode kesalahan WSA_IO_PENDING menunjukkan bahwa operasi yang tumpang tindih telah berhasil dimulai dan penyelesaian tersebut akan ditunjukkan di lain waktu.

Kode kesalahan lainnya menunjukkan bahwa operasi tidak berhasil dimulai dan tidak ada indikasi penyelesaian yang akan terjadi jika operasi yang tumpang tindih diminta.

Kode kesalahan	Makna
WSAECONNRESET	Untuk soket datagram UDP, kesalahan ini akan menunjukkan bahwa operasi pengiriman sebelumnya menghasilkan pesan "Port Unreachable" ICMP.
WSAEFAULT	Parameter lpBuffers, lpFlags, lpFrom, lpNumberOfBytesRecvd, lpFromlen, lpOverlapped, atau lpCompletionRoutine tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid: lpFrom buffer terlalu kecil untuk mengakomodasi alamat serekan. Kesalahan ini juga dikembalikan jika anggota nama struktur WSAMSG yang diacu oleh parameter lpMsg adalah penunjuk NULL dan anggota namelen struktur WSAMSG tidak diatur ke nol. Kesalahan ini juga dikembalikan jika anggota Control.buf dari struktur WSAMSG yang diarahkan oleh parameter lpMsg adalah pointer NULL dan anggota Control.len dari struktur WSAMSG tidak diatur ke nol.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINTR	Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall.
WSAEINVAL	Soket belum terikat (dengan ikatan, misalnya).
WSAEMSGSIZE	Pesan terlalu besar untuk dimasukkan ke dalam buffer yang ditentukan dan (hanya untuk protokol yang tidak dapat diandalkan) bagian berikutnya dari pesan yang tidak cocok dengan buffer telah dibuang.
WSAENETDOWN	Subsistem jaringan gagal.
WSAENETRESET	Untuk soket datagram, kesalahan ini menunjukkan bahwa waktu hidup telah kedaluwarsa.
WSAENOTCONN	Soket tidak tersambung (hanya soket berorientasi koneksi).
WSAETIMEDOUT	Waktu soket habis. Kesalahan ini dikembalikan jika soket memiliki batas waktu tunggu yang ditentukan menggunakan opsi soket SO_RCVTIMEO dan batas waktu terlampaui.
WSAEOPNOTSUPP	Operasi soket tidak didukung. Kesalahan ini dikembalikan jika anggota dwFlags dari struktur WSAMSG yang diarahkan oleh parameter lpMsg mencakup bendera kontrol MSG_PEEK pada soket non-datagram.
WSAEWOULDBLOCK	Windows NT: Soket yang tumpang tindih: Ada terlalu banyak permintaan I/O yang tumpang tindih. Soket yang tidak tumpang tindih: Soket ditandai sebagai nonblocking dan operasi penerimaan tidak dapat segera diselesaikan.
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSA_IO_PENDING	Operasi yang tumpang tindih berhasil dimulai dan penyelesaian akan ditunjukkan di lain waktu.
WSA_OPERATION_ABORTED	Operasi yang tumpang tindih telah dibatalkan karena penutupan soket.

Keterangan

Fungsi WSARecvMsg dapat digunakan sebagai pengganti fungsi WSARecv dan WSARecvFrom untuk menerima data dan informasi kontrol opsional dari soket yang terhubung dan tidak terhubung. Fungsi WSARecvMsg hanya dapat digunakan dengan datagram dan soket mentah. Deskriptor soket dalam parameter s harus dibuka dengan jenis soket yang diatur ke SOCK_DGRAM atau SOCK_RAW.

Catatan Penunjuk fungsi untuk fungsi WSARecvMsg harus diperoleh pada durasi dengan melakukan panggilan ke fungsi WSAIoctl dengan opcode SIO_GET_EXTENSION_FUNCTION_POINTER yang ditentukan. Buffer input yang diteruskan ke fungsi WSAIoctl harus berisi WSAID_WSARECVMSG, pengidentifikasi unik global (GUID) yang nilainya mengidentifikasi fungsi ekstensi WSARecvMsg . Setelah berhasil, output yang dikembalikan oleh fungsi WSAIoctl berisi penunjuk ke fungsi WSARecvMsg . GUID WSAID_WSARECVMSG ditentukan dalam file header Mswsock.h .

Anggota dwFlags dari struktur WSAMSG yang diarahkan oleh parameter lpMsg hanya dapat berisi bendera kontrol MSG_PEEK pada input.

Soket yang tumpang tindih dibuat dengan panggilan fungsi WSASocket yang memiliki set bendera WSA_FLAG_OVERLAPPED . Untuk soket yang tumpang tindih, informasi penerimaan menggunakan I/O yang tumpang tindih kecuali parameter lpOverlapped dan lpCompletionRoutine adalah NULL. Soket diperlakukan sebagai soket yang tidak tumpang tindih ketika parameter lpOverlapped dan lpCompletionRoutineadalah NULL.

Indikasi penyelesaian terjadi dengan soket yang tumpang tindih. Setelah buffer atau buffer dikonsumsi oleh transportasi, rutinitas penyelesaian dipicu atau objek peristiwa diatur. Jika operasi tidak segera selesai, status penyelesaian akhir diambil melalui rutinitas penyelesaian atau dengan memanggil fungsi WSAGetOverlappedResult .

Untuk soket yang tumpang tindih, WSARecvMsg digunakan untuk memposting satu atau beberapa buffer tempat data masuk akan ditempatkan saat tersedia, setelah itu indikasi penyelesaian yang ditentukan aplikasi (pemanggilan rutinitas penyelesaian atau pengaturan objek peristiwa) terjadi. Jika operasi tidak segera selesai, status penyelesaian akhir diambil melalui rutinitas penyelesaian atau fungsi WSAGetOverlappedResult .

Untuk soket yang tidak tumpang tindih, semantik pemblokiran identik dengan fungsi recv standar dan parameter lpOverlapped dan lpCompletionRoutine diabaikan. Data apa pun yang telah diterima dan di-buffer oleh transportasi akan disalin ke dalam buffer pengguna yang ditentukan. Dalam kasus soket pemblokiran tanpa data yang saat ini telah diterima dan di-buffer oleh transportasi, panggilan akan memblokir hingga data diterima. Windows Sockets 2 tidak menentukan mekanisme batas waktu pemblokiran standar untuk fungsi ini. Untuk protokol yang bertindak sebagai protokol byte-stream, tumpukan mencoba mengembalikan data sebanyak mungkin yang tunduk pada ruang buffer yang tersedia dan jumlah data yang diterima yang tersedia. Namun, penerimaan satu byte cukup untuk membuka blokir pemanggil. Tidak ada jaminan bahwa lebih dari satu byte akan dikembalikan. Untuk protokol yang bertindak sebagai berorientasi pesan, pesan lengkap diperlukan untuk membuka blokir pemanggil.

Catatan Opsi soket SO_RCVTIMEO hanya berlaku untuk memblokir soket.

Buffer diisi dalam urutan di mana mereka muncul dalam array yang ditujukkan oleh anggota lpBuffers dari struktur WSAMSG yang ditujukkan oleh parameter lpMsg , dan buffer dikemas sehingga tidak ada lubang yang dibuat.

Jika fungsi ini selesai dengan cara yang tumpang tindih, penyedia layanan Winsock bertanggung jawab untuk menangkap struktur WSABUF ini sebelum kembali dari panggilan ini. Ini memungkinkan aplikasi untuk membangun array WSABUF berbasis tumpukan yang diacu oleh anggota lpBuffers dari struktur WSAMSG yang diacu oleh parameter lpMsg .

Untuk soket berorientasi pesan (jenis soket SOCK_DGRAM atau SOCK_RAW), pesan masuk ditempatkan ke dalam buffer hingga ukuran total buffer, dan indikasi penyelesaian terjadi untuk soket yang tumpang tindih. Jika pesan lebih besar dari buffer, buffer diisi dengan bagian pertama pesan dan kelebihan data hilang, dan WSARecvMsg menghasilkan kesalahan WSAEMSGSIZE.

Ketika opsi soket IP_PKTINFO diaktifkan pada soket jenis IPv4 SOCK_DGRAM atau SOCK_RAW, fungsi WSARecvMsg mengembalikan informasi paket dalam struktur WSAMSG yang ditunjukkan oleh parameter lpMsg . Salah satu objek data kontrol dalam struktur WSAMSG yang dikembalikan akan berisi struktur in_pktinfo yang digunakan untuk menyimpan informasi alamat paket yang diterima.

Untuk datagram yang diterima melalui IPv4, anggota Kontrol struktur WSAMSG yang diterima akan berisi struktur WSABUF yang berisi struktur WSACMSGHDR . Anggota cmsg_level struktur WSACMSGHDR ini akan berisi IPPROTO_IP, anggota cmsg_type struktur ini akan berisi IP_PKTINFO, dan anggota cmsg_data akan berisi struktur in_pktinfo yang digunakan untuk menyimpan informasi alamat paket IPv4 yang diterima. Alamat IPv4 dalam struktur in_pktinfo adalah alamat IPv4 tempat paket diterima.

Ketika opsi soket IPV6_PKTINFO diaktifkan pada soket IPv6 jenis SOCK_DGRAM atau SOCK_RAW, fungsi WSARecvMsg mengembalikan informasi paket dalam struktur WSAMSG yang ditunjukkan oleh parameter lpMsg . Salah satu objek data kontrol dalam struktur WSAMSG yang dikembalikan akan berisi struktur in6_pktinfo yang digunakan untuk menyimpan informasi alamat paket yang diterima.

Untuk datagram yang diterima melalui IPv6, anggota Kontrol struktur WSAMSG yang diterima akan berisi struktur WSABUF yang berisi struktur WSACMSGHDR . Anggota cmsg_level struktur WSACMSGHDR ini akan berisi IPPROTO_IPV6, anggota cmsg_type struktur ini akan berisi IPV6_PKTINFO, dan anggota cmsg_data akan berisi struktur in6_pktinfo yang digunakan untuk menyimpan informasi alamat paket IPv6 yang diterima. Alamat IPv6 dalam struktur in6_pktinfo adalah alamat IPv6 tempat paket diterima.

Untuk soket datagram tumpukan ganda, jika aplikasi memerlukan fungsi WSARecvMsg untuk mengembalikan informasi paket dalam struktur WSAMSG untuk datagram yang diterima melalui IPv4, maka opsi soket IP_PKTINFO harus diatur ke true pada soket. Jika hanya opsi IPV6_PKTINFO diatur ke true pada soket, informasi paket akan diberikan untuk datagram yang diterima melalui IPv6 tetapi mungkin tidak disediakan untuk datagram yang diterima melalui IPv4.

Perhatikan bahwa file header Ws2ipdef.h secara otomatis disertakan dalam Ws2tcpip.h, dan tidak boleh digunakan secara langsung.

Catatan Semua I/O yang dimulai oleh utas tertentu dibatalkan ketika utas tersebut keluar. Untuk soket yang tumpang tindih, operasi asinkron yang tertunda dapat gagal jika utas ditutup sebelum operasi selesai. Untuk informasi selengkapnya, lihat ExitThread.

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.

dwFlags

Pada input, anggota dwFlags dari struktur WSAMSG yang ditunjukkan oleh parameter lpMsg dapat digunakan untuk memengaruhi perilaku pemanggilan fungsi di luar opsi soket yang ditentukan untuk soket terkait. Artinya, semantik fungsi ini ditentukan oleh opsi soket dan anggota dwFlags dari struktur WSAMSG . Satu-satunya nilai input yang mungkin untuk anggota dwFlags dari struktur WSAMSG yang diarahkan oleh parameter lpMsg adalah MSG_PEEK.

Nilai	Makna
MSG_PEEK	Intip pada data masuk. Data disalin ke dalam buffer, tetapi tidak dihapus dari antrean input. Bendera ini hanya berlaku untuk soket yang tidak tumpang tindih.

Nilai yang mungkin untuk anggota dwFlags pada input didefinisikan dalam file header Winsock2.h .

Pada output, anggota dwFlags dari struktur WSAMSG yang diarahkan oleh parameter lpMsg dapat mengembalikan kombinasi dari salah satu nilai berikut.

Nilai	Makna
MSG_BCAST	Datagram diterima sebagai siaran lapisan tautan atau dengan alamat IP tujuan yang merupakan alamat siaran.
MSG_CTRUNC	Data kontrol (tambahan) dipotok. Data kontrol lebih banyak ada daripada ruang yang dialokasikan proses.
MSG_MCAST	Datagram diterima dengan alamat IP tujuan yang merupakan alamat multicast.
MSG_TRUNC	Datagram dipotok. Lebih banyak data yang ada daripada ruang yang dialokasikan proses.

Pada Kit Pengembangan Perangkat Lunak (SDK) Microsoft Windows yang dirilis untuk Windows Vista dan yang lebih baru, organisasi file header telah berubah dan nilai yang mungkin untuk anggota dwFlags pada output didefinisikan dalam file header Ws2def.h yang secara otomatis disertakan oleh file header Winsock2.h .

Pada versi Kit Pengembangan Perangkat Lunak Platform (SDK) untuk Windows Server 2003 dan yang lebih lama, nilai yang mungkin untuk anggota dwFlags pada output ditentukan dalam file header Mswsock.h .

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti WSARecvMsg dengan parameter lpOverlapped diatur ke NULL, Winsock mungkin perlu menunggu peristiwa jaringan sebelum panggilan dapat selesai. Winsock melakukan penantian yang dapat diperingatkan dalam situasi ini, yang dapat terganggu oleh panggilan prosedur asinkron (APC) yang dijadwalkan pada utas yang sama. Mengeluarkan panggilan Winsock pemblokiran lain di dalam APC yang mengganggu panggilan Winsock pemblokiran yang sedang berlangsung pada utas yang sama akan menyebabkan perilaku yang tidak terdefinisi, dan tidak boleh dicoba oleh klien Winsock.

I/O Soket Tumpang Tindih

Jika operasi yang tumpang tindih segera selesai, WSARecvMsg mengembalikan nilai nol dan parameter lpNumberOfBytesRecvd diperbarui dengan jumlah byte yang diterima dan bit bendera yang ditunjukkan oleh parameter lpFlags juga diperbarui. Jika operasi yang tumpang tindih berhasil dimulai dan akan selesai nanti, WSARecvMsg mengembalikan SOCKET_ERROR dan menunjukkan kode kesalahan WSA_IO_PENDING. Dalam hal ini, lpNumberOfBytesRecvd tidak diperbarui. Ketika operasi yang tumpang tindih selesai, jumlah data yang ditransfer ditunjukkan baik melalui parameter cbTransferred dalam rutinitas penyelesaian (jika ditentukan), atau melalui parameter lpcbTransfer di WSAGetOverlappedResult. Nilai bendera diperoleh dengan memeriksa parameter lpdwFlags dari WSAGetOverlappedResult.

Fungsi WSARecvMsg menggunakan I/O yang tumpang tindih dapat dipanggil dari dalam rutinitas penyelesaian fungsi WSARecv, WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg, atau WSASendTo sebelumnya. Untuk soket tertentu, rutinitas penyelesaian I/O tidak akan ditumpuk. Ini memungkinkan transmisi data sensitif waktu terjadi sepenuhnya dalam konteks preemptive.

Parameter lpOverlapped harus valid selama durasi operasi yang tumpang tindih. Jika beberapa operasi I/O secara bersamaan luar biasa, masing-masing harus mereferensikan struktur WSAOVERLAPPED terpisah.

Jika parameter lpCompletionRoutine adalah NULL, parameter hEventdari lpOverlapped diberi sinyal ketika operasi yang tumpang tindih selesai jika berisi handel objek peristiwa yang valid. Aplikasi dapat menggunakan WSAWaitForMultipleEvents atau WSAGetOverlappedResult untuk menunggu atau melakukan polling pada objek peristiwa.

Jika lpCompletionRoutine bukan NULL, parameter hEvent diabaikan dan dapat digunakan oleh aplikasi untuk meneruskan informasi konteks ke rutinitas penyelesaian. Penelepon yang melewati lpCompletionRoutinenon-NULL dan kemudian memanggil WSAGetOverlappedResult untuk permintaan I/O yang tumpang tindih yang sama mungkin tidak mengatur parameter fWait untuk pemanggilan WSAGetOverlappedResult ke TRUE. Dalam hal ini penggunaan parameter hEvent tidak terdefinisi, dan mencoba menunggu parameter hEvent akan menghasilkan hasil yang tidak dapat diprediksi.

Rutinitas penyelesaian mengikuti aturan yang sama seperti yang ditetapkan untuk rutinitas penyelesaian I/O file Windows. Rutinitas penyelesaian tidak akan dipanggil sampai utas berada dalam status tunggu yang dapat diperingatkan seperti dapat terjadi ketika fungsi WSAWaitForMultipleEvents dengan parameter fAlertable diatur ke TRUE dipanggil.

Prototipe rutinitas penyelesaian adalah sebagai berikut:


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags
);

CompletionRoutine adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi atau yang ditentukan pustaka. Parameter dwError menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh parameter lpOverlapped . Parameter cbTransferred menentukan jumlah byte yang diterima. Parameter dwFlags berisi informasi yang juga dikembalikan pada anggota dwFlags dari struktur WSAMSG yang ditunjukkan oleh parameter lpMsg jika operasi penerimaan telah selesai segera. Fungsi CompletionRoutine tidak mengembalikan nilai.

Mengembalikan dari fungsi ini memungkinkan pemanggilan rutinitas penyelesaian lain yang tertunda untuk soket ini. Saat menggunakan WSAWaitForMultipleEvents, semua rutinitas penyelesaian tunggu dipanggil sebelum penantian utas yang dapat diperingatkan dipenuhi dengan kode pengembalian WSA_IO_COMPLETION. Rutinitas penyelesaian dapat dipanggil dalam urutan apa pun, tidak harus dalam urutan yang sama operasi yang tumpang tindih selesai. Namun, buffer yang diposting dijamin akan diisi dalam urutan yang sama di mana buffer ditentukan.

Jika Anda menggunakan port penyelesaian I/O, ketahuilah bahwa urutan panggilan yang dilakukan ke WSARecvMsg juga merupakan urutan di mana buffer diisi. Fungsi WSARecvMsg tidak boleh dipanggil pada soket yang sama secara bersamaan dari utas yang berbeda, karena dapat menghasilkan urutan buffer yang tidak dapat diprediksi.