GetQueuedCompletionStatusEx-Funktion

2025-05-08

Ruft mehrere Vervollständigungsporteinträge gleichzeitig ab. Er wartet darauf, dass ausstehende E/A-Vorgänge, die dem angegebenen Abschlussport zugeordnet sind, abgeschlossen sind.

Um E/A-Abschlusspakete nacheinander aus der Warteschlange zu entfernen, verwenden Sie die GetQueuedCompletionStatus-Funktion .

Syntax

BOOL WINAPI GetQueuedCompletionStatusEx(
  _In_  HANDLE             CompletionPort,
  _Out_ LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  _In_  ULONG              ulCount,
  _Out_ PULONG             ulNumEntriesRemoved,
  _In_  DWORD              dwMilliseconds,
  _In_  BOOL               fAlertable
);

Die Parameter

AbschlussHafen[in]

Ein Handle für den Abschlussport. Verwenden Sie zum Erstellen eines Abschlussports die CreateIoCompletionPort-Funktion .

lpCompletionPortEntries[out]

Bei der Eingabe zeigt auf ein vorab zugeordnetes Array von OVERLAPPED_ENTRY Strukturen.

Empfängt bei der Ausgabe ein Array von OVERLAPPED_ENTRY Strukturen, die die Einträge enthalten. Die Anzahl der Arrayelemente wird von ulNumEntriesRemoved bereitgestellt.

Die Anzahl der Bytes, die während jeder E/A übertragen wurden, der Vervollständigungsschlüssel, der angibt, in welcher Datei die einzelnen E/A-Vorgänge aufgetreten sind, und die überlappende Strukturadresse, die in den einzelnen ursprünglichen E/A-Vorgänge verwendet wurde, werden im lpCompletionPortEntries-Array zurückgegeben.

ulCount[in]

Die maximale Anzahl von Einträgen, die entfernt werden sollen.

ulNumEntriesEntfernt[out]

Ein Zeiger auf eine Variable, der die Anzahl der tatsächlich entfernten Einträge empfängt.

dwMillisekunden[in]

Die Anzahl der Millisekunden, die der Aufrufer bereit ist zu warten, bis ein Abschlusspaket am Abschlussport angezeigt wird. Wenn innerhalb der angegebenen Zeit kein Abschlusspaket angezeigt wird, tritt eine Zeitüberschreitung der Funktion auf und sie gibt FALSEzurück.

Wenn dwMillisecondsauf INFINITE (0xFFFFFFFF) gesetzt ist, tritt für die Funktion nie eine Zeitüberschreitung auf. Wenn dwMilliseconds null ist und kein E/A-Vorgang zum Entfernen der Warteschlange vorhanden ist, tritt für die Funktion sofort eine Zeitüberschreitung auf.

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 wurde. Zum Beispiel wird die Zeitüberschreitung weiter heruntergezä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 nicht die Zeit, die in Energiesparzuständen verbracht wird. Beispielsweise wird der Countdown für das Timeout nicht fortgesetzt, während sich der Computer im Ruhezustand befindet.

fAlarmierbar[in]

Wenn dieser Parameter ist FALSE, wird die Funktion erst zurückgegeben, wenn der Timeoutzeitraum abgelaufen ist oder ein Eintrag abgerufen wird.

Wenn der Parameter ist TRUE und keine Einträge verfügbar sind, führt die Funktion eine warnbare Wartezeit aus. Der Thread wird zurückgegeben, wenn das System eine E/A-Abschlussroutine (APC) in die Warteschlange des Threads einreiht und der Thread die Funktion ausführt.

Eine Abschlussroutine wird in die Warteschlange eingereiht, wenn die ReadFileEx - oder WriteFileEx-Funktion , in der sie angegeben wurde, abgeschlossen wurde und der aufrufende Thread der Thread ist, der den Vorgang initiiert hat. Ein APC wird in die Warteschlange eingereiht, wenn Sie QueueUserAPC aufrufen.

Rückgabewert

Gibt bei Erfolg ungleich Null TRUE oder andernfalls Null FALSE zurück.

Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

Diese Funktion wird zurückgegeben TRUE , wenn mindestens eine ausstehende E/A-Vorgänge abgeschlossen ist, es jedoch möglich ist, dass ein oder mehrere E/A-Vorgänge fehlgeschlagen sind. Beachten Sie, dass es Aufgabe des Benutzers dieser Funktion ist, die Liste der zurückgegebenen Einträge im lpCompletionPortEntries-Parameter zu überprüfen, um zu bestimmen, welche von ihnen möglichen fehlgeschlagenen E/A-Vorgängen entsprechen, indem er sich den Status ansieht, der im lpOverlapped-Member in jedem OVERLAPPED_ENTRY enthalten ist.

Diese Funktion wird zurückgegeben FALSE , wenn kein E/A-Vorgang aus der Warteschlange entfernt wurde. Dies bedeutet in der Regel, dass beim Verarbeiten der Parameter für diesen Aufruf ein Fehler aufgetreten ist oder dass das CompletionPort-Handle geschlossen wurde oder anderweitig ungültig ist. Die GetLastError-Funktion stellt erweiterte Fehlerinformationen bereit.

Wenn ein Aufruf von GetQueuedCompletionStatusEx fehlschlägt, weil das zugehörige Handle geschlossen ist, gibt die Funktion zurück FALSE , und GetLastError gibt ERROR_ABANDONED_WAIT_0zurück.

Serveranwendungen können über mehrere Threads verfügen, die die GetQueuedCompletionStatusEx-Funktion für denselben Abschlussport aufrufen. Wenn E/A-Vorgänge abgeschlossen sind, werden sie an diesem Port in der Reihenfolge "first-in-first-out" in die Warteschlange eingereiht. Wenn ein Thread aktiv auf diesen Aufruf wartet, wird der Aufruf nur für diesen Thread durch eine oder mehrere Anforderungen in der Warteschlange abgeschlossen.

Weitere Informationen zur Theorie, Verwendung und den zugehörigen Funktionen der E/A-Abschlussports 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 Transparentes Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Robustes Dateisystem (Resilient File System (ReFS))	Ja

Anforderungen

Anforderung	Wert
Mindest unterstützter Client	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützter Server (Mindestversion)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Kopfzeile	`IoAPI.h` (einschließen `Windows.h`) `WinBase.h` unter Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista (einschließlich `Windows.h`)
Bibliothek	`Kernel32.lib`
DLL	`Kernel32.dll`