Fungsi WSARecvEx (mswsock.h)

Artikel
03/15/2023

Fungsi WSARecvEx menerima data dari soket yang terhubung atau soket tanpa koneksi terikat. Fungsi WSARecvEx mirip dengan fungsi recv , kecuali bahwa parameter bendera hanya digunakan untuk mengembalikan informasi. Ketika pesan parsial diterima saat menggunakan protokol datagram, bit MSG_PARTIAL diatur dalam parameter bendera saat dikembalikan dari fungsi.

Catatan Fungsi WSARecvEx adalah ekstensi khusus Microsoft untuk spesifikasi Windows Sockets.

Sintaks

int WSARecvEx(
  [in]      SOCKET s,
  [out]     char   *buf,
  [in]      int    len,
  [in, out] int    *flags
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tersambung.

[out] buf

Penunjuk ke buffer untuk menerima data masuk.

[in] len

Panjangnya, dalam byte, dari buffer yang diacu oleh parameter buf .

[in, out] flags

Indikator yang menentukan apakah pesan diterima sepenuhnya atau sebagian untuk soket datagram.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, WSARecvEx mengembalikan jumlah byte yang diterima. Jika koneksi telah ditutup, koneksi akan mengembalikan nol. Selain itu, jika pesan parsial diterima, bit MSG_PARTIAL diatur dalam parameter bendera . Jika pesan lengkap diterima, MSG_PARTIAL tidak diatur dalam bendera

Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Penting Untuk protokol transportasi berorientasi aliran, MSG_PARTIAL tidak pernah diatur saat pengembalian dari WSARecvEx. Fungsi ini beraktivitas identik dengan fungsi recv untuk protokol transportasi aliran.

Kode kesalahan	Makna
WSAECONNABORTED	Sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya. Aplikasi harus menutup soket karena tidak lagi dapat digunakan.
WSAECONNRESET	Sirkuit virtual diatur ulang oleh sisi jarak jauh yang mengeksekusi penutupan yang keras atau abortif. Aplikasi harus menutup soket karena tidak lagi dapat digunakan. Pada soket UPD-datagram, kesalahan ini akan menunjukkan bahwa operasi pengiriman sebelumnya menghasilkan pesan "Port Unreachable" ICMP.
WSAEFAULT	Parameter buf tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINTR	Panggilan (pemblokiran) dibatalkan oleh panggilan WSACancelBlockingCall .
WSAEINVAL	Soket belum terikat dengan ikatan, atau bendera yang tidak diketahui ditentukan, atau MSG_OOB ditentukan untuk soket dengan SO_OOBINLINE diaktifkan atau (hanya untuk soket aliran byte) adalah nol atau negatif.
WSAENETDOWN	Subsistem jaringan gagal.
WSAENETRESET	Untuk soket berorientasi koneksi, kesalahan ini menunjukkan bahwa koneksi telah rusak karena aktivitas tetap aktif yang mendeteksi kegagalan saat operasi sedang berlangsung. Untuk soket datagram, kesalahan ini menunjukkan bahwa waktu hidup telah kedaluwarsa.
WSAENOTCONN	Soket tidak tersambung.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	MSG_OOB ditentukan, tetapi soket tidak bergaya aliran seperti jenis SOCK_STREAM, data OOB tidak didukung di domain komunikasi yang terkait dengan soket ini, atau soket tidak langsung dan hanya mendukung operasi pengiriman.
WSAESHUTDOWN	Soket telah dimatikan; tidak dimungkinkan untuk menggunakan WSARecvEx pada soket setelah pematian dipanggil dengan cara diatur ke SD_RECEIVE atau SD_BOTH.
WSAETIMEDOUT	Koneksi terputus karena kegagalan jaringan atau karena sistem serekan gagal merespons.
WSAEWOULDBLOCK	Soket ditandai sebagai nonblocking dan operasi terima akan diblokir.
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.

Keterangan

Fungsi WSARecvEx yang merupakan bagian dari implementasi Microsoft windows Sockets 2 mirip dengan fungsi recv yang lebih umum kecuali bahwa parameter bendera digunakan untuk satu tujuan tertentu. Parameter bendera digunakan untuk menunjukkan apakah pesan parsial atau lengkap diterima saat protokol berorientasi pesan sedang digunakan.

Nilai yang diacu oleh parameter bendera diabaikan pada input. Jadi tidak ada bendera yang dapat diteruskan ke fungsi WSARecvEx untuk memodifikasi perilakunya. Nilai yang ditujukkan oleh parameter bendera diatur pada output. Ini berbeda dari fungsi recv dan WSARecv di mana nilai yang ditunjukkan oleh parameter bendera pada input dapat memodifikasi perilaku fungsi.

Fungsi WSARecvEx dan recv berperilaku identik untuk protokol berorientasi aliran.

Parameter bendera mengakomodasi dua situasi umum di mana pesan parsial akan diterima:

Ketika ukuran buffer data aplikasi lebih kecil dari ukuran pesan dan pesan secara kebetulan tiba dalam dua bagian.
Ketika pesan agak besar dan harus tiba dalam beberapa bagian.

Bit MSG_PARTIAL diatur dalam nilai yang ditunjukkan oleh parameter bendera saat dikembalikan dari WSARecvEx saat pesan parsial diterima. Jika pesan lengkap diterima, MSG_PARTIAL tidak diatur dalam nilai yang ditunjukkan oleh parameter bendera .

Fungsi recv berbeda dari
Fungsi WSARecvEx dan WSARecv karena fungsi recv selalu menerima satu pesan untuk setiap panggilan untuk protokol transportasi berorientasi pesan. Fungsi recv juga tidak memiliki sarana untuk menunjukkan kepada aplikasi bahwa data yang diterima hanyalah pesan parsial. Aplikasi harus membangun protokolnya sendiri untuk memeriksa apakah pesan parsial atau lengkap dengan memeriksa kode kesalahan WSAEMSGSIZE setelah setiap panggilan ke recv. Ketika buffer aplikasi lebih kecil dari data yang dikirim, sebanyak pesan yang akan cocok disalin ke dalam buffer pengguna dan recv kembali dengan kode kesalahan WSAEMSGSIZE. Panggilan berikutnya ke recv akan mendapatkan bagian berikutnya dari pesan.

Aplikasi yang ditulis untuk protokol transportasi berorientasi pesan harus dikodekan untuk kemungkinan ini jika ukuran pesan tidak dijamin oleh protokol transfer data aplikasi. Aplikasi dapat menggunakan recv dan mengelola protokol itu sendiri. Atau, aplikasi dapat menggunakan WSARecvEx dan memeriksa apakah bit MSG_PARTIAL diatur dalam parameter bendera .

Fungsi WSARecvEx memberi pengembang cara yang lebih efektif untuk memeriksa apakah pesan yang diterima sebagian atau lengkap ketika pesan yang sangat besar tiba secara bertahap. Misalnya, jika aplikasi mengirim pesan satu megabyte, protokol transportasi harus memecah pesan untuk mengirimnya melalui jaringan fisik. Secara teoritis dimungkinkan untuk protokol transportasi di sisi penerimaan untuk menyangga semua data dalam pesan, tetapi ini akan sangat mahal dalam hal sumber daya. Sebaliknya, WSARecvEx dapat digunakan, meminimalkan overhead dan menghilangkan kebutuhan akan protokol berbasis aplikasi.

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. Lihat fungsi ExitThread untuk informasi selengkapnya.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	mswsock.h (termasuk Mswsock.h)
Pustaka	Mswsock.lib
DLL	Mswsock.dll