GetQueuedCompletionStatusEx-Funktion (ioapiset.h)

Artikel
11/08/2024

Ruft mehrere Vervollständigungsporteinträge gleichzeitig ab. Es wartet auf ausstehende E/A-Vorgänge, die dem angegebenen Abschlussport zugeordnet sind, bis er abgeschlossen ist.

Verwenden Sie die GetQueuedCompletionStatus- funktion, um die E/A-Vervollständigungspakete einzeln zu dequeue.

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 zum Abschlussport. Verwenden Sie zum Erstellen eines Abschlussports die CreateIoCompletionPort--Funktion.

[out] lpCompletionPortEntries

Verweist bei der Eingabe auf ein vorab zugeordnetes Array von OVERLAPPED_ENTRY Strukturen.

Bei der Ausgabe empfängt ein Array von OVERLAPPED_ENTRY Strukturen, die die Einträge enthalten. Die Anzahl der Arrayelemente wird von ulNumEntriesRemovedbereitgestellt.

Die Anzahl der während jeder E/A übertragenen Bytes, der Abschlussschlüssel, der angibt, auf welcher Datei jede E/A aufgetreten ist, und die in den ursprünglichen E/A-Adressen verwendete überlappende Strukturadresse werden alle in der lpCompletionPortEntries Array zurückgegeben.

[in] ulCount

Die maximale Anzahl der zu entfernenden Einträge.

[out] ulNumEntriesRemoved

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

[in] dwMilliseconds

Die Anzahl der Millisekunden, die der Aufrufer bereit ist, auf ein Abschlusspaket zu warten, das am Abschlussport angezeigt wird. Wenn ein Vervollständigungspaket nicht innerhalb der angegebenen Zeit angezeigt wird, wird die Funktion aus- und gibt FALSE-zurück.

Wenn dwMillisecondsINFINITE (0xFFFFFFFF) ist, wird die Funktion nie timeout. Wenn dwMilliseconds null ist und keine E/A-Operation dequeue vorhanden ist, wird die Funktion sofort timeout.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der dwMilliseconds Wert umfasst Zeit, die in Energiesparzuständen aufgewendet wurde. So wird beispielsweise das Timeout weiter gezählt, während der Computer eingeschlafen ist.

Windows 8 und neuer, Windows Server 2012 und höher: Der wert dwMilliseconds enthält keine Zeit, die in Energiesparzuständen aufgewendet wurde. Beispielsweise wird das Timeout nicht weiter gezählt, während der Computer eingeschlafen ist.

[in] fAlertable

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

Wenn der Parameter TRUE ist und keine verfügbaren Einträge vorhanden sind, führt die Funktion eine warnbare Wartezeit aus. Der Thread gibt zurück, wenn das System eine E/A-Vervollständigungsroutine oder APC in die Warteschlange stellt und der Thread die Funktion ausführt.

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

Rückgabewert

Gibt nonzero (TRUE) zurück, wenn erfolgreich oder null (FALSE) andernfalls.

Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

Diese Funktion gibt TRUE zurück, wenn mindestens eine ausstehende E/A abgeschlossen ist, aber es ist möglich, dass mindestens ein E/A-Vorgang fehlgeschlagen ist. Beachten Sie, dass der Benutzer dieser Funktion die Liste der zurückgegebenen Einträge im lpCompletionPortEntries Parameter überprüft, um zu bestimmen, welche dieser Vorgänge möglichen fehlgeschlagenen E/A-Vorgängen entsprechen, indem sie den Status im lpOverlapped Member in jedem OVERLAPPED_ENTRYüberprüfen.

Diese Funktion gibt FALSE- zurück, wenn keine E/A-Operation abgebrochen 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 enthält erweiterte Fehlerinformationen.

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

Serveranwendungen verfügen möglicherweise über mehrere Threads, die den GetQueuedCompletionStatusEx--Funktion für den gleichen Abschlussport aufrufen. Nach Abschluss von E/A-Vorgängen werden sie in die Warteschlange für diesen Port in der Reihenfolge "first-in-first-out" eingereiht. Wenn ein Thread aktiv auf diesen Aufruf wartet, führen mindestens eine in die Warteschlange eingereihte Anforderungen den Aufruf nur für diesen Thread aus.

Weitere Informationen zu E/A-Vervollständigungsporttheorie, Verwendung und zugeordneten Funktionen finden Sie unter E/A-Vervollständigungsports.

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

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	ioapiset.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll