GetOverlappedResultEx-Funktion (ioapiset.h)

Artikel
02/26/2024

Ruft die Ergebnisse eines überlappenden Vorgangs für die angegebene Datei, named pipe oder das angegebene Kommunikationsgerät innerhalb des angegebenen Timeoutintervalls ab. Der aufrufende Thread kann eine warnbare Wartezeit ausführen.

Syntax

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Parameter

[in] hFile

Ein Handle für die Datei, die Named Pipe oder das Kommunikationsgerät. Dies ist das gleiche Handle, das angegeben wurde, als der überlappende Vorgang durch einen Aufruf der Funktion ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl oder WaitCommEvent gestartet wurde.

[in] lpOverlapped

Ein Zeiger auf eine OVERLAPPED-Struktur , die beim Starten des überlappenden Vorgangs angegeben wurde.

[out] lpNumberOfBytesTransferred

Ein Zeiger auf eine Variable, die die Anzahl der Bytes empfängt, die tatsächlich durch einen Lese- oder Schreibvorgang übertragen wurden. Bei einem TransactNamedPipe-Vorgang ist dies die Anzahl der Bytes, die aus der Pipe gelesen wurden. Bei einem DeviceIoControl-Vorgang ist dies die Anzahl der Vom Gerätetreiber zurückgegebenen Ausgabedaten in Bytes. Für einen ConnectNamedPipe- oder WaitCommEvent-Vorgang ist dieser Wert nicht definiert.

[in] dwMilliseconds

Das Timeoutintervall in Millisekunden.

Wenn dwMilliseconds null ist und der Vorgang noch ausgeführt wird, wird die Funktion sofort zurückgegeben, und die GetLastError-Funktion gibt ERROR_IO_INCOMPLETE zurück.

Wenn dwMilliseconds ungleich null ist und der Vorgang noch ausgeführt wird, wartet die Funktion, bis das Objekt signalisiert wird, eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht wird oder das Intervall vor der Rückgabe verstrichen ist. Verwenden Sie GetLastError , um erweiterte Fehlerinformationen abzurufen.

Wenn dwMillisecondsINFINITE ist, gibt die Funktion nur zurück, wenn das Objekt signalisiert wird, eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht wird.

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 Wert dwMilliseconds enthält keine Zeit, die mit Zuständen mit niedriger Energie verbracht wurde. Beispielsweise wird das Timeout nicht weiter heruntergezählt, während sich der Computer im Ruhezustand befindet.

[in] bAlertable

Wenn dieser Parameter TRUE ist und sich der aufrufende Thread im Wartezustand befindet, gibt die Funktion zurück, wenn das System eine E/A-Vervollständigungsroutine oder APC in die Warteschlange stellt. Der aufrufende Thread führt dann die Routine oder Funktion aus. Andernfalls gibt die Funktion nicht zurück, und die Vervollständigungsroutine oder APC-Funktion wird nicht ausgeführt.

Eine Vervollständigungsroutine wird in die Warteschlange gestellt, wenn die ReadFileEx - oder WriteFileEx-Funktion , in der sie angegeben wurde, abgeschlossen wurde. Die Funktion gibt zurück, und die Vervollständigungsroutine wird nur aufgerufen, wenn bAlertableTRUE ist, und der aufrufende Thread ist der Thread, der den Lese- oder Schreibvorgang initiiert hat. Beim Aufrufen von QueueUserAPC wird ein APC in eine Warteschlange gestellt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Zu den gängigen Fehlercodes gehören:

Wenn dwMilliseconds null ist und der Vorgang noch ausgeführt wird, gibt GetLastErrorERROR_IO_INCOMPLETE zurück.
Wenn dwMilliseconds ungleich null ist und eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht wird, gibt GetLastErrorWAIT_IO_COMPLETION zurück.
Wenn dwMilliseconds ungleich null ist und das angegebene Timeoutintervall verstrichen ist, gibt GetLastErrorWAIT_TIMEOUT zurück.

Hinweise

Die GetOverlappedResultEx-Funktion unterscheidet sich auf folgende Weise von GetOverlappedResult : Der dwMilliseconds-Parameter kann ein Timeoutintervall für den Vorgang angeben, und der bAlertable-Parameter kann angeben, dass der aufrufende Thread einen warnbaren Wartevorgang ausführen soll.

Die von der GetOverlappedResultEx-Funktion gemeldeten Ergebnisse entsprechen denen des letzten überlappenden Vorgangs des angegebenen Handles, für den die angegebene OVERLAPPED-Struktur bereitgestellt wurde und für die die Ergebnisse des Vorgangs ausstehen. Ein ausstehender Vorgang wird angezeigt, wenn die Funktion, die den Vorgang gestartet hat, FALSE zurückgibt, und die GetLastError-FunktionERROR_IO_PENDING zurückgibt. Wenn ein E/A-Vorgang aussteht, setzt die Funktion, die den Vorgang gestartet hat, den hEvent-Member der OVERLAPPED-Struktur auf den nicht signalierten Zustand zurück. Wenn der ausstehende Vorgang abgeschlossen ist, legt das System das Ereignisobjekt auf den signalierten Zustand fest.

Geben Sie ein Ereignisobjekt für manuelles Zurücksetzen in der OVERLAPPED-Struktur an. Wenn ein Ereignisobjekt für die automatische Zurücksetzung verwendet wird, darf das Ereignishandle in keinem anderen Wartevorgang im Intervall zwischen dem Starten des überlappenden Vorgangs und dem Aufruf von GetOverlappedResultEx angegeben werden. Beispielsweise wird das Ereignisobjekt manchmal in einer der Wartefunktionen angegeben, um auf den Abschluss des Vorgangs zu warten. Wenn die Wait-Funktion zurückgibt, legt das System den Zustand eines Ereignisses für das automatische Zurücksetzen auf nicht signalisiert fest, und ein nachfolgender Aufruf von GetOverlappedResultEx mit dem parameter dwMilliseconds , der auf INFINITE festgelegt ist, bewirkt, dass die Funktion auf unbestimmte Zeit blockiert wird.

Wenn der hEvent-Member der OVERLAPPED-StrukturNULL ist, verwendet das System den Status des hFile-Handles , um zu signalisieren, wann der Vorgang abgeschlossen wurde. Die Verwendung von Datei-, Named Pipe- oder Kommunikationsgerätehandles für diesen Zweck wird abgeraten. Es ist sicherer, ein Ereignisobjekt aufgrund der Verwirrung zu verwenden, die auftreten kann, wenn mehrere gleichzeitige überlappende Vorgänge für dieselbe Datei, Named Pipe oder ein Kommunikationsgerät ausgeführt werden. In dieser Situation gibt es keine Möglichkeit zu wissen, welcher Vorgang dazu geführt hat, dass der Zustand des Objekts signalisiert wurde.

Anforderungen

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