Fungsi GetOverlappedResultEx (ioapiset.h)
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
Penunjuk 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 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.
Nilai dwMilliseconds tidak menyertakan waktu yang dihabiskan dalam status berdaya rendah. Misalnya, batas waktu tidak terus menghitung mundur saat komputer sedang tidur.
[in] bAlertable
Jika parameter ini TRUE dan utas panggilan 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 fungsi rutinitas penyelesaian atau APC tidak dijalankan.
Rutinitas penyelesaian diantrekan ketika fungsi ReadFileEx atau WriteFileEx tempat fungsi ditentukan telah selesai. Fungsi kembali dan rutinitas penyelesaian dipanggil hanya jika bAlertableTRUE, dan utas panggilan adalah utas yang memulai operasi baca atau tulis. APC diantrekan saat Anda memanggil QueueUserAPC.
Menampilkan 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 akan mengembalikan WAIT_IO_COMPLETION.
- Jika dwMilliseconds bukan nol dan interval batas waktu yang ditentukan berlalu, GetLastError 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 hasil 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 mereset anggota hEvent dari struktur TUMPANG TINDIH ke status tidak bertanda. Kemudian ketika operasi yang tertunda telah selesai, sistem mengatur objek peristiwa ke status tersinyal.
Tentukan objek peristiwa reset manual dalam struktur 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 dalam 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 tumpang tindih 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 |