Fungsi GetQueuedCompletionStatus (ioapiset.h)

Artikel
11/08/2024

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.

Sintaksis

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

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

[out] lpCompletionKey

Pointer 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 saat operasi I/O 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 hEvent anggota struktur TUMPANG TINDIH, dan mengatur bit berurutan rendah. Handel peristiwa yang valid dengan bit berurutan rendah diatur 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 menetapkan *lpOverlapped ke NULL.

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

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, waktu habis terus menghitung mundur saat komputer sedang tidur.

Windows 8 dan yang lebih baru, Windows Server 2012 dan yang lebih baru: nilai dwMilliseconds tidak termasuk waktu yang dihabiskan dalam status berdaya rendah. Misalnya, batas waktu tidak terus menghitung mundur saat komputer tertidur.

Mengembalikan nilai

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

Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Untuk informasi selengkapnya, lihat bagian Keterangan.

Komentar

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 luar biasa tidak akan mengakibatkan perilaku yang dinyatakan sebelumnya. Fungsi akan terus menunggu hingga 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 ditunjukkan oleh parameter berikut: lpNumberOfBytes, lpCompletionKey, dan lpOverlapped. Setelah kegagalan (nilai pengembalian FALSE), parameter yang sama tersebut dapat berisi kombinasi nilai tertentu sebagai berikut:

Jika *lpOverlappedNULL, fungsi tidak menghapus antrean paket penyelesaian dari port penyelesaian. Dalam hal ini, fungsi tidak menyimpan informasi dalam variabel yang diarahkan oleh lpNumberOfBytes dan parameter lpCompletionKey, dan nilainya tidak ditentukan.
Jika *lpOverlapped tidak 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, panggil GetLastError.

Untuk informasi selengkapnya tentang teori port penyelesaian I/O, penggunaan, dan fungsi terkait, 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
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Persyaratan

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

Lihat juga

ConnectNamedPipe

CreateIoCompletionPort

DeviceIoControl

File Management Functions

Functions

GetQueuedCompletionStatusEx

Port Penyelesaian I/O

LockFileEx

Topik Ringkasan

PostQueuedCompletionStatus

ReadFile

TransactNamedPipe

Menggunakan Header Windows

WaitCommEvent

WriteFile

Bagikan melalui