Fungsi GetOverlappedResultEx (ioapiset.h)

Artikel
02/29/2024

Mengambil hasil operasi yang tumpang tindih pada file yang ditentukan, pipa bernama, atau perangkat komunikasi dalam interval waktu habis yang ditentukan. Utas panggilan dapat melakukan penantian yang dapat diperingatkan.

Sintaks

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Parameter

[in] hFile

Handel ke file, pipa bernama, atau perangkat komunikasi. Ini adalah handel yang sama yang ditentukan ketika operasi yang tumpang tindih dimulai oleh panggilan ke fungsi ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl, atau WaitCommEvent .

[in] lpOverlapped

Penunjuk ke struktur TUMPANG TINDIH yang ditentukan ketika operasi yang tumpang tindih dimulai.

[out] lpNumberOfBytesTransferred

Pointer ke variabel yang menerima jumlah byte yang benar-benar ditransfer oleh operasi baca atau tulis. Untuk operasi TransactNamedPipe , ini adalah jumlah byte yang dibaca dari pipa. Untuk operasi DeviceIoControl , ini adalah jumlah byte data output yang dikembalikan oleh driver perangkat. Untuk operasi ConnectNamedPipe atau WaitCommEvent , nilai ini tidak ditentukan.

[in] dwMilliseconds

Interval waktu habis, dalam milidetik.

Jika dwMilliseconds adalah nol dan operasi masih berlangsung, fungsi segera kembali dan fungsi GetLastError mengembalikan ERROR_IO_INCOMPLETE.

Jika dwMilliseconds bukan nol dan operasi masih berlangsung, fungsi menunggu sampai objek diberi sinyal, rutinitas penyelesaian I/O atau APC diantrekan, atau interval berlalu sebelum kembali. Gunakan GetLastError untuk mendapatkan informasi kesalahan yang diperluas.

Jika dwMilliseconds adalah INFINITE, fungsi hanya mengembalikan ketika objek diberi sinyal atau rutinitas penyelesaian I/O atau APC diantrekan.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 dan Windows Server 2008 R2: Nilai dwMilliseconds mencakup waktu yang dihabiskan dalam status berdaya rendah. Misalnya, batas waktu terus menghitung mundur saat komputer tertidur.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 dan Windows Server 2016: Nilai dwMilliseconds tidak termasuk waktu yang dihabiskan dalam status berdaya rendah. Misalnya, batas waktu tidak terus menghitung mundur saat komputer tertidur.

[in] bAlertable

Jika parameter ini TRUE dan utas panggilan berada dalam status menunggu, fungsi akan kembali saat sistem mengantre rutinitas penyelesaian I/O atau APC. Utas panggilan kemudian menjalankan rutinitas atau fungsi. Jika tidak, fungsi tidak kembali, dan rutinitas penyelesaian atau fungsi APC tidak dijalankan.

Rutinitas penyelesaian diantrekan ketika fungsi ReadFileEx atau WriteFileEx tempat fungsi ditentukan telah selesai. Fungsi mengembalikan dan rutinitas penyelesaian dipanggil hanya jika bAlertableTRUE, dan utas panggilan adalah utas yang memulai operasi baca atau tulis. APC diantrekan saat Anda memanggil QueueUserAPC.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Kode kesalahan umum meliputi yang berikut ini:

Jika dwMilliseconds adalah nol dan operasi masih berlangsung, GetLastError mengembalikan ERROR_IO_INCOMPLETE.
Jika dwMilliseconds bukan nol, dan rutinitas penyelesaian I/O atau APC diantrekan, GetLastError mengembalikan WAIT_IO_COMPLETION.
Jika dwMilliseconds bukan nol dan interval batas waktu yang ditentukan berlalu, GetLastError akan mengembalikan WAIT_TIMEOUT.

Keterangan

Fungsi GetOverlappedResultEx berbeda dari GetOverlappedResult dengan cara berikut: Parameter dwMilliseconds dapat menentukan interval batas waktu untuk operasi, dan parameter bAlertable dapat menentukan bahwa utas panggilan harus melakukan penantian yang dapat diperingatkan.

Hasil yang dilaporkan oleh fungsi GetOverlappedResultEx adalah dari operasi tumpang tindih terakhir handel yang ditentukan tempat struktur TUMPANG TINDIH yang ditentukan disediakan, dan yang hasil operasinya tertunda. Operasi yang tertunda ditunjukkan ketika fungsi yang memulai operasi mengembalikan FALSE, dan fungsi GetLastError mengembalikan ERROR_IO_PENDING. Ketika operasi I/O tertunda, fungsi yang memulai operasi mengatur ulang anggota hEvent dari struktur TUMPANG TINDIH ke status tidak ditandatangani. Kemudian ketika operasi yang tertunda telah selesai, sistem mengatur objek peristiwa ke status yang disinyalkan.

Tentukan objek peristiwa reset manual dalam struktur YANG TUMPANG TINDIH . Jika objek peristiwa reset otomatis digunakan, penanganan aktivitas tidak boleh ditentukan dalam operasi tunggu lainnya dalam interval antara memulai operasi yang tumpang tindih dan panggilan ke GetOverlappedResultEx. Misalnya, objek peristiwa terkadang ditentukan di salah satu fungsi tunggu untuk menunggu penyelesaian operasi. Ketika fungsi tunggu kembali, sistem mengatur status peristiwa reset otomatis ke nonsignaled, dan panggilan berikutnya ke GetOverlappedResultEx dengan parameter dwMilliseconds diatur ke INFINITE menyebabkan fungsi diblokir tanpa batas waktu.

Jika anggota hEvent dari struktur TUMPANG TINDIH ADALAH NULL, sistem menggunakan status handel hFile untuk memberi sinyal ketika operasi telah selesai. Penggunaan file, pipa bernama, atau handel perangkat komunikasi untuk tujuan ini tidak disarankan. Lebih aman untuk menggunakan objek peristiwa karena kebingungan yang dapat terjadi ketika beberapa operasi yang tumpang tindih secara bersamaan dilakukan pada file yang sama, pipa bernama, atau perangkat komunikasi. Dalam situasi ini, tidak ada cara untuk mengetahui operasi mana yang menyebabkan status objek diberi sinyal.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	ioapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll