GetQueuedCompletionStatusEx-Funktion (ioapiset.h)

Artikel
08/24/2023

Ruft mehrere Abschlussporteinträge gleichzeitig ab. Sie wartet, bis ausstehende E/A-Vorgänge abgeschlossen werden, die dem angegebenen Abschlussport zugeordnet sind.

Verwenden Sie die Funktion GetQueuedCompletionStatus, um E/A-Abschlusspakete nacheinander zu entfernen.

Syntax

BOOL GetQueuedCompletionStatusEx(
  [in]  HANDLE             CompletionPort,
  [out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  [in]  ULONG              ulCount,
  [out] PULONG             ulNumEntriesRemoved,
  [in]  DWORD              dwMilliseconds,
  [in]  BOOL               fAlertable
);

Parameter

[in] CompletionPort

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

[out] lpCompletionPortEntries

Zeigt bei der Eingabe auf ein vorab zugewiesenes Array von Strukturen OVERLAPPED_ENTRY.

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

Die Anzahl der bei jeder E/A übertragenen Bytes, der Abschlussschlüssel, der angibt, in welcher Datei die einzelnen E/A-Vorgänge aufgetreten sind, und die in jeder ursprünglichen E/A verwendete überlappende Strukturadresse werden im Array lpCompletionPortEntries zurückgegeben.

[in] ulCount

Die maximale Anzahl von zu entfernenden Einträgen.

[out] ulNumEntriesRemoved

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

[in] dwMilliseconds

Die Anzahl von Millisekunden, die der Aufrufer warten möchte, bis ein Abschlusspaket am Abschlussport angezeigt wird. Wenn ein Abschlusspaket nicht innerhalb der angegebenen Zeit angezeigt wird, wird für die Funktion ein Timeout ausgeführt und FALSE zurückgegeben.

Wenn dwMillisecondsINFINITE (0xFFFFFFFF) ist, tritt für die Funktion kein Timeout auf. Wenn dwMilliseconds null ist und kein E/A-Vorgang zum aus der Warteschlange entfernen ausgeführt werden muss, tritt für die Funktion ein Timeout sofort auf.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der dwMilliseconds-Wert enthält Zeit, die in Zuständen mit geringer Leistung verbracht wurde. Beispielsweise wird das Timeout 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 Wert dwMilliseconds enthält keine Zeit, die mit Zuständen mit niedriger Energie verbracht wurde. Beispielsweise wird das Timeout nicht mehr heruntergezählt, während sich der Computer im Ruhezustand befindet.

[in] fAlertable

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

Wenn der Parameter TRUE ist 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 oder einen APC für den Thread in die Warteschlange stellt und der Thread die Funktion ausführt.

Eine Abschlussroutine wird in die Warteschlange gestellt, wenn die Funktionen ReadFileEx oder WriteFileEx, in der sie angegeben wurde, abgeschlossen wurde, und der aufrufende Thread der Thread ist, der den Vorgang initiiert hat. Beim Aufrufen von QueueUserAPC wird ein APC in eine Warteschlange gestellt.

Rückgabewert

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

Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Bemerkungen

Diese Funktion ordnet einem Thread den angegebenen Abschlussport zu. Einem Thread kann höchstens ein Abschlussport zugeordnet werden.

Diese Funktion gibt TRUE zurück, wenn mindestens eine ausstehende E/A abgeschlossen ist, es ist jedoch möglich, 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 Parameter lpCompletionPortEntries zu überprüfen, um zu bestimmen, welche von ihnen allen möglichen fehlgeschlagenen E/A-Vorgängen entsprechen, indem sie sich den Status im Member lpOverlapped in jedem OVERLAPPED_ENTRY ansehen.

Diese Funktion gibt FALSE zurück, 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 Handle CompletionPort geschlossen wurde oder anderweitig ungültig ist. Die Funktion GetLastError bietet erweiterte Fehlerinformationen.

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

Serveranwendungen können über mehrere Threads verfügen, die die Funktion GetQueuedCompletionStatusEx für denselben Abschlussport aufrufen. Nach Abschluss der E/A-Vorgänge werden sie in der Reihenfolge First-in-First-Out an diesem Port in die Warteschlange gestellt. Wenn ein Thread aktiv auf diesen Aufruf wartet, schließt mindestens eine eingestellte Anfrage den Aufruf für diesen Thread ab.

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
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Anforderungen

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