Fungsi panggilan balik LPWSPRECV (ws2spi.h)

Artikel
08/28/2023

Fungsi LPWSPRecv menerima data pada soket.

Sintaks

LPWSPRECV Lpwsprecv;

int Lpwsprecv(
  [in]         SOCKET s,
  \[in\, out\] LPWSABUF lpBuffers,
  [in]         DWORD dwBufferCount,
  [out]        LPDWORD lpNumberOfBytesRecvd,
  \[in\, out\] LPDWORD lpFlags,
  [in]         LPWSAOVERLAPPED lpOverlapped,
  [in]         LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  [in]         LPWSATHREADID lpThreadId,
  [out]        LPINT lpErrno
)
{...}

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang terhubung.

\\[in\\, out\\] lpBuffers

Penunjuk ke array struktur WSABUF . Setiap struktur WSABUF berisi penunjuk ke buffer dan panjang buffer, dalam byte.

[in] dwBufferCount

Jumlah struktur WSABUF dalam array lpBuffers .

[out] lpNumberOfBytesRecvd

Penunjuk ke jumlah byte yang diterima oleh panggilan ini.

\\[in\\, out\\] lpFlags

Penunjuk ke bendera yang menentukan cara panggilan dilakukan.

[in] lpOverlapped

Penunjuk ke struktur WSAOverlapped (diabaikan untuk struktur yang tidak tumpang tindih).

[in] lpCompletionRoutine

Jenis: LPWSAOVERLAPPED_COMPLETION_ROUTINE _In_opt_

Penunjuk ke rutinitas penyelesaian yang dipanggil ketika operasi terima telah selesai (diabaikan untuk struktur yang tidak tumpang tindih).

[in] lpThreadId

Penunjuk ke struktur WSATHREADID yang akan digunakan oleh penyedia dalam panggilan berikutnya ke WPUQueueApc. Penyedia harus menyimpan struktur WSATHREADID yang direferensikan (bukan penunjuk ke yang sama) sampai setelah fungsi WPUQueueApc kembali.

[out] lpErrno

Penunjuk ke kode kesalahan.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi dan operasi penerimaan telah segera selesai, LPWSPRecv mengembalikan nol. Perhatikan bahwa dalam hal ini rutinitas penyelesaian, jika ditentukan, akan telah diantrekan. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu tersedia di lpErrno. 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 tidak ada operasi yang tumpang tindih yang dimulai dan tidak ada indikasi penyelesaian yang akan terjadi.

Kode Kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAENOTCONN	Soket tidak terhubung.
WSAEINTR	(Pemblokiran) panggilan dibatalkan melalui LPWSPCancelBlockingCall.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAENETRESET	Koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung.
WSAEFAULT	Parameter lpBuffers tidak sepenuhnya terkandung dalam bagian ruang alamat pengguna yang valid.
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 mungkin untuk menerima melalui LPWSPRecv pada soket setelah LPWSPShutdown dipanggil dengan cara diatur ke SD_RECEIVE atau SD_BOTH.
WSAEWOULDBLOCK	Windows NT: Soket yang tumpang tindih: ada terlalu banyak permintaan I/O yang tumpang tindih yang luar biasa. Soket yang tidak tumpang tindih: Soket ditandai sebagai nonblocking dan operasi penerimaan tidak dapat segera diselesaikan.
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.
WSAEINVAL	Soket belum terikat (misalnya, dengan LPWSPBind) atau soket tidak dibuat dengan bendera tumpang tindih.
WSAECONNABORTED	Sirkuit virtual dihentikan karena waktu habis atau kegagalan lainnya.
WSAECONNRESET	Sirkuit virtual direset oleh sisi jarak jauh.
WSAEDISCON	Soket berorientasi pesan dan sirkuit virtual ditutup dengan anggun oleh sisi jarak jauh.
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

LPWSPRecv digunakan pada soket yang terhubung atau soket tanpa koneksi terikat yang ditentukan oleh parameter s dan digunakan untuk membaca data masuk. Alamat lokal soket harus diketahui. Ini dapat dilakukan secara eksplisit melalui LPWSPBind atau secara implisit melalui LPWSPAccept, LPWSPConnect, LPWSPSendTo, atau LPWSPJoinLeaf.

Untuk soket yang tersambung dan tanpa koneksi, fungsi ini membatasi alamat tempat pesan yang diterima diterima. Fungsi ini hanya mengembalikan pesan dari alamat jarak jauh yang ditentukan dalam koneksi. Pesan dari alamat lain (diam-diam) dibuang.

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

Jika lpOverlapped dan lpCompletionRoutine null, soket dalam fungsi ini akan diperlakukan sebagai soket yang tidak tumpang tindih.

Untuk soket yang tidak tumpang tindih, parameter lpOverlapped, lpCompletionRoutine, dan lpThreadId diabaikan. Setiap data yang telah diterima dan di-buffer oleh transportasi akan disalin ke dalam buffer pengguna yang disediakan. Untuk 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 disediakan 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.

Apakah protokol bertindak sebagai byte-stream ditentukan oleh pengaturan XP1_MESSAGE_ORIENTED dan XP1_PSEUDO_STREAM dalam struktur WSAPROTOCOL_INFO dan pengaturan bendera MSG_PARTIAL yang diteruskan ke fungsi ini (untuk protokol yang mendukungnya). Kombinasi yang relevan dirangkum dalam tabel berikut (tanda bintang (*) menunjukkan bahwa pengaturan bit ini tidak masalah dalam hal ini).

XP1_MESSAGE_ORIENTED	XP1_PSEUDO_STREAM	MSG_PARTIAL	Bertindak sebagai
tidak diatur	*	*	aliran byte
*	set	*	aliran byte
set	tidak diatur	set	aliran byte
set	tidak diatur	tidak diatur	pesan berorientasi

Buffer yang disediakan diisi dalam urutan di mana buffer muncul dalam array yang ditujukkan oleh lpBuffers, dan buffer dikemas sehingga tidak ada lubang yang dibuat.

Array struktur WSABUF yang diacu oleh parameter lpBuffers bersifat sementara. Jika operasi ini selesai dengan cara yang tumpang tindih, penyedia layanan bertanggung jawab untuk menangkap array pointer ini ke struktur WSABUF sebelum kembali dari panggilan ini. Ini memungkinkan klien Windows Sockets SPI untuk membangun array WSABUF berbasis tumpukan.

Untuk soket gaya aliran byte (misalnya, jenis SOCK_STREAM), data masuk ditempatkan ke dalam buffer hingga buffer terisi, koneksi ditutup, atau data yang di-buffer secara internal habis. Terlepas dari apakah data yang masuk mengisi semua buffer atau tidak, indikasi penyelesaian terjadi untuk soket yang tumpang tindih. Untuk soket berorientasi pesan (misalnya, ketik SOCK_DGRAM), pesan masuk ditempatkan ke dalam buffer yang disediakan, hingga ukuran total buffer yang disediakan, dan indikasi penyelesaian terjadi untuk soket yang tumpang tindih. Jika pesan lebih besar dari buffer yang disediakan, buffer diisi dengan bagian pertama pesan. Jika fitur MSG_PARTIAL didukung oleh penyedia layanan, bendera MSG_PARTIAL diatur dalam lpFlags dan operasi penerimaan berikutnya dapat digunakan untuk mengambil sisa pesan. Jika MSG_PARTIAL tidak didukung tetapi protokolnya dapat diandalkan, LPWSPRecv menghasilkan kesalahan WSAEMSGSIZE dan operasi penerimaan berikutnya dengan buffer yang lebih besar dapat digunakan untuk mengambil seluruh pesan. Jika tidak, (artinya, protokol tidak dapat diandalkan dan tidak mendukung MSG_PARTIAL), data berlebih hilang, dan LPWSPRecv menghasilkan kesalahan WSAEMSGSIZE.

Untuk soket berorientasi koneksi, LPWSPRecv dapat menunjukkan penghentian sirkuit virtual dengan anggun dengan salah satu dari dua cara, tergantung pada apakah soket adalah aliran byte atau pesan yang berorientasi. Untuk aliran byte, nol byte yang telah dibaca menunjukkan penutupan anggun dan tidak ada lagi byte yang akan dibaca. Untuk soket berorientasi pesan, di mana pesan byte nol sering diizinkan, kode kesalahan pengembalian WSAEDISCON digunakan untuk menunjukkan penutupan dengan baik. Dalam hal apa pun kode kesalahan pengembalian WSAECONNRESET menunjukkan penutupan abortif telah terjadi.

Parameter lpFlags dapat digunakan untuk memengaruhi perilaku pemanggilan fungsi di luar opsi yang ditentukan untuk soket terkait. Artinya, semantik fungsi ini ditentukan oleh opsi soket dan parameter lpFlags . Yang terakhir dibangun dengan menggunakan operator bitwise OR dengan salah satu nilai berikut.

Nilai	Makna
MSG_PEEK	Mengintip data masuk. Data disalin ke dalam buffer tetapi tidak dihapus dari antrean input. Bendera ini hanya berlaku untuk soket yang tidak tumpang tindih.
MSG_OOB	Memproses data Out of Band (OOB).
MSG_PARTIAL	Bendera ini hanya untuk soket berorientasi pesan. Pada output, menunjukkan bahwa data yang diberikan adalah bagian dari pesan yang dikirimkan oleh pengirim. Bagian pesan yang tersisa akan disediakan dalam operasi penerimaan berikutnya. Operasi penerimaan berikutnya dengan bendera MSG_PARTIAL dihapus menunjukkan akhir pesan pengirim. Sebagai parameter input, MSG_PARTIAL menunjukkan bahwa operasi penerimaan harus selesai meskipun hanya sebagian pesan yang telah diterima oleh penyedia layanan.

Jika operasi yang tumpang tindih segera selesai, LPWSPRecv 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, LPWSPRecv mengembalikan SOCKET_ERROR dan menunjukkan kode kesalahan WSA_IO_PENDING. Dalam hal ini, lpNumberOfBytesRecvd dan lpFlags tidak diperbarui. Ketika operasi yang tumpang tindih menyelesaikan jumlah data yang ditransfer ditunjukkan baik melalui parameter cbTransferred dalam rutinitas penyelesaian (jika ditentukan), atau melalui parameter lpcbTransfer di LPWSPGetOverlappedResult. Nilai bendera diperoleh baik melalui parameter dwFlags dari rutinitas penyelesaian, atau dengan memeriksa parameter lpdwFlags dari WSAGetOverlappedResult.

Penyedia harus mengizinkan fungsi ini dipanggil dari dalam rutinitas penyelesaian fungsi LPWSPRecv, LPWSPRecvFrom, LPWSPSend atau LPWSPSendTo sebelumnya. Namun, untuk soket tertentu, rutinitas penyelesaian I/O tidak dapat 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 tumpang tindih terpisah. Struktur WSAOverlapped didefinisikan di halaman referensinya sendiri.

Jika parameter lpCompletionRoutine null, penyedia layanan memberi sinyal kepada anggota hEventdari lpOverlapped ketika operasi yang tumpang tindih selesai jika berisi handel objek peristiwa yang valid. Klien Windows Sockets SPI dapat menggunakan LPWSPGetOverlappedResult untuk menunggu atau melakukan polling pada objek peristiwa.

Jika lpCompletionRoutine tidak null, anggota hEvent diabaikan dan dapat digunakan oleh klien Windows Sockets SPI untuk meneruskan informasi konteks ke rutinitas penyelesaian. Klien yang melewati lpCompletionRoutine 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 anggota hEvent tidak terdefinisi, dan mencoba menunggu anggota hEvent akan menghasilkan hasil yang tidak dapat diprediksi.

Merupakan tanggung jawab penyedia layanan untuk mengatur pemanggilan klien yang ditentukan–rutinitas penyelesaian ketika operasi yang tumpang tindih selesai. Karena rutinitas penyelesaian harus dijalankan dalam konteks utas yang sama yang memulai operasi yang tumpang tindih, itu tidak dapat dipanggil langsung dari penyedia layanan. Ws2_32.dll menawarkan mekanisme panggilan prosedur asinkron (APC) untuk memfasilitasi pemanggilan rutinitas penyelesaian.

Penyedia layanan mengatur agar fungsi dijalankan dalam rangkaian dan konteks proses yang tepat dengan memanggil WPUQueueApc, yang digunakan untuk memulai operasi yang tumpang tindih. Fungsi ini dapat dipanggil dari konteks proses dan utas apa pun, bahkan konteks yang berbeda dari utas dan proses yang digunakan untuk memulai operasi yang tumpang tindih.

WPUQueueApc mengambil sebagai parameter input penunjuk ke struktur WSATHREADID (diberikan kepada penyedia melalui parameter input lpThreadId ), penunjuk ke fungsi APC yang akan dipanggil, dan nilai konteks yang kemudian diteruskan ke fungsi APC. Karena hanya satu nilai konteks yang tersedia, fungsi APC itu sendiri tidak dapat menjadi rutinitas penyelesaian yang ditentukan klien. Penyedia layanan harus menyediakan pointer ke fungsi APC sendiri yang menggunakan nilai konteks yang disediakan untuk mengakses informasi hasil yang diperlukan untuk operasi yang tumpang tindih, dan kemudian memanggil rutinitas penyelesaian yang ditentukan klien.

Prototipe untuk rutinitas penyelesaian yang disediakan klien adalah sebagai berikut.

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

Parameter CompletionRoutine adalah tempat penampung untuk nama fungsi yang disediakan klien. dwError menentukan status penyelesaian untuk operasi yang tumpang tindih seperti yang ditunjukkan oleh lpOverlapped. Parameter cbTransferred menentukan jumlah byte yang diterima. dwFlags berisi informasi yang akan muncul di lpFlags jika operasi penerimaan telah selesai segera. Fungsi ini tidak mengembalikan nilai.

Rutinitas penyelesaian dapat dipanggil dalam urutan apa pun, tetapi tidak harus urutan yang sama di mana operasi yang tumpang tindih selesai. Namun, buffer yang diposting dijamin akan diisi dalam urutan yang sama di mana mereka disediakan.

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