Fungsi GetQueuedCompletionStatus (ioapiset.h)

Artikel
05/20/2023

Mencoba untuk menghapus antrean paket penyelesaian I/O dari port penyelesaian I/O yang ditentukan. Jika tidak ada paket penyelesaian yang diantrekan, fungsi menunggu operasi I/O yang tertunda yang terkait dengan port penyelesaian selesai.

Untuk menghapus antrean beberapa paket penyelesaian I/O sekaligus, gunakan fungsi GetQueuedCompletionStatusEx .

Sintaks

BOOL GetQueuedCompletionStatus(
  [in]  HANDLE       CompletionPort,
        LPDWORD      lpNumberOfBytesTransferred,
  [out] PULONG_PTR   lpCompletionKey,
  [out] LPOVERLAPPED *lpOverlapped,
  [in]  DWORD        dwMilliseconds
);

Parameter

[in] CompletionPort

Handel ke port penyelesaian. Untuk membuat port penyelesaian, gunakan fungsi CreateIoCompletionPort .

lpNumberOfBytesTransferred

Penunjuk ke variabel yang menerima jumlah byte yang ditransfer dalam operasi I/O yang telah selesai.

[out] lpCompletionKey

Penunjuk ke variabel yang menerima nilai kunci penyelesaian yang terkait dengan handel file yang operasi I/O-nya telah selesai. Kunci penyelesaian adalah kunci per file yang ditentukan dalam panggilan ke CreateIoCompletionPort.

[out] lpOverlapped

Penunjuk ke variabel yang menerima alamat struktur TUMPANG TINDIH yang ditentukan ketika operasi I/O yang selesai dimulai.

Bahkan jika Anda telah melewati fungsi handel file yang terkait dengan port penyelesaian dan struktur TUMPANG TINDIH yang valid, aplikasi dapat mencegah pemberitahuan port penyelesaian. Ini dilakukan dengan menentukan handel peristiwa yang valid untuk anggota hEvent dari struktur yang TUMPANG TINDIH , dan mengatur bit berurutan rendah. Handel peristiwa yang valid dengan bit berurutan rendah yang ditetapkan mencegah penyelesaian I/O yang tumpang tindih dari enqueing paket penyelesaian ke port penyelesaian.

[in] dwMilliseconds

Jumlah milidetik pemanggil bersedia menunggu paket penyelesaian muncul di port penyelesaian. Jika paket penyelesaian tidak muncul dalam waktu yang ditentukan, waktu fungsi habis, mengembalikan FALSE, dan mengatur *lpOverlapped ke NULL.

Jika dwMilliseconds adalah INFINITE, fungsi tidak akan pernah kehabisan waktu. Jika dwMilliseconds adalah nol dan tidak ada operasi I/O untuk menghapus antrean, fungsi akan segera kehabisan waktu.

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.

Mengembalikan nilai

Mengembalikan bukan nol (TRUE) jika berhasil atau nol (FALSE) jika tidak.

Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Untuk informasi selengkapnya, lihat bagian Keterangan.

Keterangan

Fungsi ini mengaitkan utas dengan port penyelesaian yang ditentukan. Utas dapat dikaitkan dengan paling banyak satu port penyelesaian.

Jika panggilan ke GetQueuedCompletionStatus gagal karena handel port penyelesaian yang terkait dengannya ditutup saat panggilan luar biasa, fungsi mengembalikan FALSE, *lpOverlapped akan null, dan GetLastError akan mengembalikan ERROR_ABANDONED_WAIT_0.

Windows Server 2003 dan Windows XP: Menutup handel port penyelesaian saat panggilan terutang tidak akan mengakibatkan perilaku yang dinyatakan sebelumnya. Fungsi akan terus menunggu sampai entri dihapus dari port atau sampai waktu habis terjadi, jika ditentukan sebagai nilai selain INFINITE.

Jika fungsi GetQueuedCompletionStatus berhasil, fungsi ini menghapus antrean paket penyelesaian untuk operasi I/O yang berhasil dari port penyelesaian dan telah menyimpan informasi dalam variabel yang diarahkan oleh parameter berikut: lpNumberOfBytes, lpCompletionKey, dan lpOverlapped. Setelah kegagalan (nilai yang dikembalikan adalah FALSE), parameter yang sama tersebut dapat berisi kombinasi nilai tertentu sebagai berikut:

Jika *lpOverlapped adalah NULL, fungsi tidak menghapus antrean paket penyelesaian dari port penyelesaian. Dalam hal ini, fungsi tidak menyimpan informasi dalam variabel yang diarahkan oleh parameter lpNumberOfBytes dan lpCompletionKey , dan nilainya tidak ditentukan.
Jika *lpOverlapped bukan NULL dan fungsi menghapus antrean paket penyelesaian untuk operasi I/O yang gagal dari port penyelesaian, fungsi menyimpan informasi tentang operasi yang gagal dalam variabel yang diarahkan oleh lpNumberOfBytes, lpCompletionKey, dan lpOverlapped. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Untuk informasi selengkapnya tentang teori, penggunaan, dan fungsi terkait penyelesaian I/O, lihat Port Penyelesaian I/O.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
SMB 3.0 Transparent Failover (TFO)	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Persyaratan


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