GetQueuedCompletionStatus-Funktion (ioapiset.h)

Artikel
05/20/2023

Versucht, ein E/A-Vervollständigungspaket vom angegebenen E/A-Abschlussport aus der Warteschlange zu entfernen. Wenn kein Abschlusspaket in die Warteschlange eingereiht ist, wartet die Funktion auf den Abschluss eines ausstehenden E/A-Vorgangs, der dem Abschlussport zugeordnet ist.

Verwenden Sie die GetQueuedCompletionStatusEx-Funktion , um mehrere E/A-Vervollständigungspakete gleichzeitig aus der Warteschlange zu entfernen.

Syntax

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

Parameter

[in] CompletionPort

Ein Handle zum Abschlussport. Verwenden Sie zum Erstellen eines Abschlussports die CreateIoCompletionPort-Funktion .

lpNumberOfBytesTransferred

Ein Zeiger auf eine Variable, die die Anzahl der in einem abgeschlossenen E/A-Vorgang übertragenen Bytes empfängt.

[out] lpCompletionKey

Ein Zeiger auf eine Variable, die den Abschlussschlüsselwert empfängt, der dem Dateihandle zugeordnet ist, dessen E/A-Vorgang abgeschlossen wurde. Ein Abschlussschlüssel ist ein Dateischlüssel, der in einem Aufruf von CreateIoCompletionPort angegeben wird.

[out] lpOverlapped

Ein Zeiger auf eine Variable, die die Adresse der OVERLAPPED-Struktur empfängt , die beim Starten des abgeschlossenen E/A-Vorgangs angegeben wurde.

Selbst wenn Sie der Funktion ein Dateihandle übergeben haben, das einem Abschlussport und einer gültigen OVERLAPPED-Struktur zugeordnet ist, kann eine Anwendung die Benachrichtigung über den Abschlussport verhindern. Dazu geben Sie ein gültiges Ereignishandle für den hEvent-Member der OVERLAPPED-Struktur an und legen dessen Bit mit niedriger Reihenfolge fest. Ein gültiges Ereignishandle, dessen Bit mit niedriger Reihenfolge festgelegt ist, verhindert, dass der Abschluss der überlappenden E/A-Vorgänge ein Abschlusspaket an den Abschlussport angibt.

[in] dwMilliseconds

Die Anzahl der Millisekunden, die der Aufrufer bereit ist, auf das Erscheinen eines Abschlusspakets am Abschlussport zu warten. Wenn ein Vervollständigungspaket nicht innerhalb der angegebenen Zeit angezeigt wird, gibt die Funktion ein Timeout zurück, gibt FALSE zurück und legt *lpOverlapped auf NULL fest.

Wenn dwMillisecondsINFINITE ist, wird für die Funktion kein Timeout ausgeführt. Wenn dwMilliseconds null ist und kein E/A-Vorgang aus der Warteschlange verschoben werden soll, wird für die Funktion sofort ein Timeout ausgeführt.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der DwMilliseconds-Wert enthält die Zeit, die in Energiesparzuständen verbracht wird. Beispielsweise wird das Timeout weiter gezählt, während sich der Computer im Ruhezustand befindet.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 und Windows Server 2016: Der DwMilliseconds-Wert enthält keine Zeit, die bei niedriger Leistung aufgewendet wurde. Staaten. Beispielsweise wird das Timeout nicht weiter heruntergezählt, während sich der Computer im Ruhezustand befindet.

Rückgabewert

Gibt ungleich Null (TRUE) zurück, wenn erfolgreich war, oder andernfalls null (FALSE).

Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Hinweise

Diese Funktion ordnet einen Thread dem angegebenen Abschlussport zu. Ein Thread kann höchstens einem Abschlussport zugeordnet werden.

Wenn ein Aufruf von GetQueuedCompletionStatus fehlschlägt , weil das zugehörige Abschlussporthandle geschlossen wird, während der Aufruf aussteht, gibt die Funktion FALSE zurück, *lpOverlapped ist NULL, und GetLastError gibt ERROR_ABANDONED_WAIT_0 zurück.

Windows Server 2003 und Windows XP: Das Schließen des Abschlussporthandles, während ein Aufruf aussteht, führt nicht zu dem zuvor angegebenen Verhalten. Die Funktion wartet weiterhin, bis ein Eintrag aus dem Port entfernt wird oder bis ein Timeout auftritt, wenn ein anderer Wert als INFINITE angegeben wird.

Wenn die GetQueuedCompletionStatus-Funktion erfolgreich ist, hat sie ein Abschlusspaket für einen erfolgreichen E/A-Vorgang vom Abschlussport entfernt und enthält Informationen in den Variablen, auf die mit den folgenden Parametern verwiesen wird: lpNumberOfBytes, lpCompletionKey und lpOverlapped. Bei einem Fehler (der Rückgabewert ist FALSE) können dieselben Parameter bestimmte Wertkombinationen wie folgt enthalten:

Wenn *lpOverlappedNULL ist, hat die Funktion kein Abschlusspaket vom Abschlussport aus der Warteschlange entfernt. In diesem Fall speichert die Funktion keine Informationen in den Variablen, auf die die Parameter lpNumberOfBytes und lpCompletionKey verweisen, und ihre Werte sind unbestimmt.
Wenn *lpOverlapped nicht NULL ist und die Funktion ein Abschlusspaket für einen fehlgeschlagenen E/A-Vorgang vom Abschlussport aus der Warteschlange ausgibt, speichert die Funktion Informationen zum fehlgeschlagenen Vorgang in den Variablen, auf die von lpNumberOfBytes, lpCompletionKey und lpOverlapped verwiesen wird. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Weitere Informationen zur E/A-Vervollständigung von Ports, zur Verwendung und zu den zugehörigen Funktionen finden Sie unter E/A-Abschlussports.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben für horizontales Skalieren (SO)	Ja
Freigegebenes Clustervolume-Dateisystem (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	ioapiset.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll