Fungsi panggilan balik LPWSPGETOVERLAPPEDRESULT (ws2spi.h)

Artikel
08/28/2023

Fungsi LPWSPGetOverlappedResult mengembalikan hasil operasi yang tumpang tindih pada soket yang ditentukan.

Sintaks

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Mengidentifikasi soket. Ini adalah soket yang sama yang ditentukan ketika operasi yang tumpang tindih dimulai oleh panggilan ke LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo, atau LPWSPIoctl.

[in] lpOverlapped

Pointer ke struktur WSAOverlapped yang ditentukan ketika operasi tumpang tindih dimulai.

[out] lpcbTransfer

Pointer ke variabel 32-bit yang menerima jumlah byte yang benar-benar ditransfer oleh operasi kirim atau terima, atau oleh LPWSPIoctl.

[in] fWait

Menentukan apakah fungsi harus menunggu operasi tumpang tindih yang tertunda selesai. Jika TRUE, fungsi tidak kembali sampai operasi selesai. Jika FALSE dan operasi masih tertunda, fungsi mengembalikan FALSE dan lpErrno WSA_IO_INCOMPLETE. Parameter fWait dapat diatur ke TRUE hanya jika operasi tumpang tindih memilih pemberitahuan penyelesaian berbasis peristiwa.

[out] lpdwFlags

Penunjuk ke variabel 32-bit yang akan menerima satu atau beberapa bendera yang melengkapi status penyelesaian. Jika operasi yang tumpang tindih dimulai melalui LPWSPRecv atau LPWSPRecvFrom, parameter ini akan berisi nilai hasil untuk parameter lpFlags .

[out] lpErrno

Arahkan ke kode kesalahan.

Mengembalikan nilai

Jika LPWSPGetOverlappedResult berhasil, nilai yang dikembalikan adalah TRUE. Ini berarti operasi yang tumpang tindih telah berhasil diselesaikan dan nilai yang ditunjukkan oleh lpcbTransfer telah diperbarui. Jika LPWSPGetOverlappedResult mengembalikan FALSE, ini berarti bahwa operasi yang tumpang tindih belum selesai atau operasi yang tumpang tindih selesai tetapi dengan kesalahan, atau status penyelesaian tidak dapat ditentukan karena kesalahan dalam satu atau beberapa parameter ke LPWSPGetOverlappedResult. Jika gagal, nilai yang ditunjukkan oleh lpcbTransfer tidak akan diperbarui. Parameter lpErrno menunjukkan penyebab kegagalan (salah satu dari LPWSPGetOverlappedResult atau operasi tumpang tindih terkait).

Kode Kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAENOTSOCK	Deskriptor bukan soket.
WSA_INVALID_HANDLE	Anggota hEvent dari struktur WSAOverlapped tidak berisi handel objek peristiwa yang valid.
WSAEINVAL	Salah satu parameter tidak dapat diterima.
WSA_IO_INCOMPLETE	Parameter fWait adalah FALSE dan operasi I/O belum selesai.

Keterangan

Hasil yang dilaporkan oleh fungsi LPWSPGetOverlappedResult adalah hasil dari operasi tumpang tindih terakhir soket yang ditentukan tempat struktur WSAOverlapped yang ditentukan disediakan, dan yang hasil operasinya tertunda. Operasi yang tertunda ditunjukkan ketika fungsi yang memulai operasi mengembalikan SOCKET_ERROR, dan lpErrno WSA_IO_PENDING. Ketika operasi I/O tertunda, fungsi yang memulai operasi mereset anggota hEvent dari struktur WSAOVERLAPPED ke status tidak bertanda. Kemudian, ketika operasi yang tertunda telah selesai, sistem mengatur objek peristiwa ke status yang disinyalir.

Jika parameter fWaitTRUE, LPWSPGetOverlappedResult menentukan apakah operasi yang tertunda telah selesai dengan memblokir dan menunggu objek peristiwa berada dalam status disinyalir. Klien dapat mengatur parameter fWait ke TRUE hanya jika memilih pemberitahuan penyelesaian berbasis peristiwa saat operasi I/O diminta. Jika bentuk pemberitahuan lain dipilih, penggunaan anggota hEvent dari struktur WSAOverlapped berbeda, dan mengatur fWait ke TRUE menyebabkan hasil yang tidak dapat diprediksi.

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.

Interaksi dengan WPUCompleteOverlappedRequest

Perilaku WPUCompleteOverlappedRequest menempatkan beberapa batasan tentang bagaimana penyedia layanan mengimplementasikan LPWSPGetOverlappedResult karena hanya anggota Offset dan OffsetHigh dari struktur WSAOverlapped yang secara eksklusif dikendalikan oleh penyedia layanan meskipun tiga nilai (jumlah byte, bendera, dan kesalahan) harus diambil dari struktur oleh LPWSPGetOverlappedResult. Penyedia layanan dapat menyelesaikan ini dengan cara apa pun yang dipilihnya selama berinteraksi dengan perilaku WPUCompleteOverlappedRequest dengan benar. Deskripsi berikut menyajikan implementasi umum:

Pada awal pemrosesan yang tumpang tindih, penyedia layanan mengatur Internal ke WSS_OPERATION_IN_PROGRESS.

Ketika operasi I/O selesai, penyedia mengatur OffsetHigh ke kode kesalahan Windows Sockets 2 yang dihasilkan dari operasi, mengatur Offset ke bendera yang dihasilkan dari operasi I/O, dan memanggil WPUCompleteOverlappedRequest, meneruskan jumlah byte transfer sebagai salah satu parameter. WPUCompleteOverlappedRequest akhirnya mengatur InternalHigh ke jumlah byte transfer, lalu mengatur Internal ke nilai selain WSS_OPERATION_IN_PROGRESS.

Ketika LPWSPGetOverlappedResult dipanggil, penyedia layanan memeriksa Internal. Jika WSS_OPERATION_IN_PROGRESS, penyedia menunggu handel peristiwa di anggota hEvent atau mengembalikan kesalahan, berdasarkan pengaturan bendera fWaitLPWSPGetOverlappedResult. Jika tidak sedang berlangsung, atau setelah selesai menunggu, penyedia mengembalikan nilai dari InternalHigh, OffsetHigh, dan Offset sebagai jumlah transfer, kode kesalahan hasil operasi, dan bendera masing-masing.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Header	ws2spi.h