GetOverlappedResult-Funktion (ioapiset.h)

  • Artikel

Ruft die Ergebnisse eines überlappenden Vorgangs für die angegebene Datei, benannte Pipe oder das angegebene Kommunikationsgerät ab. Verwenden Sie GetOverlappedResultEx, um ein Timeoutintervall anzugeben oder auf einen warnbaren Thread zu warten.

Syntax

BOOL GetOverlappedResult(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  BOOL         bWait
);

Parameter

[in] hFile

Ein Handle für die Datei, die Benannte Pipe oder das Kommunikationsgerät. Dies ist das gleiche Handle, das beim Starten des überlappenden Vorgangs durch einen Aufruf einer der folgenden Funktionen angegeben 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 Bytes der Ausgabedaten. Bei einem ConnectNamedPipe- oder WaitCommEvent-Vorgang ist dieser Wert nicht definiert.

[in] bWait

Wenn dieser Parameter TRUE ist und das interne Element der lpOverlapped-StrukturSTATUS_PENDING ist, wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde. Wenn dieser Parameter FALSE ist und der Vorgang noch aussteht, gibt die Funktion FALSE zurück, und die GetLastError-Funktion gibt ERROR_IO_INCOMPLETE zurück.

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.

Hinweise

Die von der GetOverlappedResult-Funktion gemeldeten Ergebnisse sind die Ergebnisse 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 wurde, legt das System das Ereignisobjekt auf den signalierten Zustand fest.

Wenn der bWait-ParameterTRUE ist, bestimmt GetOverlappedResult , ob der ausstehende Vorgang abgeschlossen wurde, indem darauf gewartet wird, dass sich das Ereignisobjekt im signalierten Zustand befindet.

Wenn das hEvent-Element der OVERLAPPED-StrukturNULL ist, verwendet das System den Zustand des hFile-Handles , um zu signalisieren, wenn 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 wird.

Beispiele

Ein Beispiel, das GetOverlappedResult verwendet, finden Sie unter Testen für das Ende einer Datei.

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ßlich Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

CancelIo, CreateEvent, GetOverlappedResultEx, OVERLAPPED, Overlapped Input and Output, Synchronization Functions