ReadFileEx-Funktion (fileapi.h)

Artikel
08/23/2023

Liest Daten aus der angegebenen Datei oder dem angegebenen Eingabe-/Ausgabegerät (E/A). Der Abschlussstatus wird asynchron durch Aufruf der angegebenen Abschlussroutine gemeldet, wenn der Lesevorgang abgeschlossen oder abgebrochen wurde und sich der aufrufende Thread in einem warnbaren Wartezustand befindet.

Verwenden Sie die ReadFile-Funktion , um Daten synchron aus einer Datei oder einem Gerät zu lesen.

Syntax

BOOL ReadFileEx(
  [in]            HANDLE                          hFile,
  [out, optional] LPVOID                          lpBuffer,
  [in]            DWORD                           nNumberOfBytesToRead,
  [in, out]       LPOVERLAPPED                    lpOverlapped,
  [in]            LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameter

[in] hFile

Ein Handle für die Datei oder das E/A-Gerät (z. B. eine Datei, einen Dateistream, einen physischen Datenträger, ein Volume, einen Konsolenpuffer, ein Bandlaufwerk, einen Socket, eine Kommunikationsressource, ein Maillot oder eine Pipe).

Dieser Parameter kann ein beliebiges Handle sein, das mit dem flag FILE_FLAG_OVERLAPPED von der CreateFile-Funktion geöffnet wird, oder ein Sockethandle, das von der Socket- oder Acceptfunktion zurückgegeben wird.

Dieses Handle muss auch über das Zugriffsrecht GENERIC_READ verfügen. Weitere Informationen zu Zugriffsrechten finden Sie unter Dateisicherheit und Zugriffsrechte.

[out, optional] lpBuffer

Ein Zeiger auf einen Puffer, der die aus der Datei oder dem Gerät gelesenen Daten empfängt.

Dieser Puffer muss für die Dauer des Lesevorgangs gültig bleiben. Die Anwendung sollte diesen Puffer erst verwenden, wenn der Lesevorgang abgeschlossen ist.

[in] nNumberOfBytesToRead

Die Anzahl der zu lesenden Bytes.

[in, out] lpOverlapped

Ein Zeiger auf eine OVERLAPPED-Datenstruktur , die Daten bereitstellt, die während des asynchronen (überlappenden) Dateilesevorgangs verwendet werden sollen.

Für Dateien, die Byteoffsets unterstützen, müssen Sie ein Byteoffset angeben, ab dem mit dem Lesen aus der Datei begonnen werden soll. Sie geben diesen Offset an, indem Sie die Elemente Offset und OffsetHigh der OVERLAPPED-Struktur festlegen. Für Dateien oder Geräte, die byteoffsets nicht unterstützen, werden Offset und OffsetHigh ignoriert.

Die ReadFileEx-Funktion ignoriert den hEvent-Member der OVERLAPPED-Struktur. Eine Anwendung kann dieses Element für eigene Zwecke im Kontext eines ReadFileEx-Aufrufs verwenden. ReadFileEx signalisiert den Abschluss des Lesevorgangs, indem die Abschlussroutine, auf die von lpCompletionRoutine verwiesen wird, aufgerufen oder eine Warteschlange angestellt wird, sodass kein Ereignishandle benötigt wird.

Die ReadFileEx-Funktion verwendet die Member Internal und InternalHigh der OVERLAPPED-Struktur. Eine Anwendung sollte diese Member nicht festlegen.

Die OVERLAPPED-Datenstruktur muss für die Dauer des Lesevorgangs gültig bleiben. Es sollte keine Variable sein, die den Gültigkeitsbereich sprengen kann, während der Lesevorgang abgeschlossen ist.

[in] lpCompletionRoutine

Ein Zeiger auf die Abschlussroutine, die aufgerufen werden soll, wenn der Lesevorgang abgeschlossen ist und sich der aufrufende Thread in einem warnbaren Wartezustand befindet. Weitere Informationen zur Vervollständigungsroutine finden Sie unter FileIOCompletionRoutine.

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.

Wenn die Funktion erfolgreich ist, steht für den aufrufenden Thread ein asynchroner E/A-Vorgang aus: der überlappende Lesevorgang aus der Datei. Wenn dieser E/A-Vorgang abgeschlossen ist und der aufrufende Thread in einem warnbaren Wartezustand blockiert wird, ruft das System die Funktion auf, auf die von lpCompletionRoutine verwiesen wird, und der Wartezustand wird mit dem Rückgabecode WAIT_IO_COMPLETION abgeschlossen.

Wenn die Funktion erfolgreich ist und der Dateilesevorgang abgeschlossen ist, sich der aufrufende Thread jedoch nicht in einem warnbaren Wartezustand befindet, wird der Aufruf der Abschlussroutine in die Warteschlange des Systems eingereiht und der Aufruf gehalten, bis der aufrufende Thread in einen warnbaren Wartezustand wechselt. Informationen zu warnbaren Wartevorgängen und überlappenden Eingabe-/Ausgabevorgängen finden Sie unter Informationen zur Synchronisierung.

Wenn ReadFileEx versucht, über das Dateiende (EOF) hinaus zu lesen, gibt der Aufruf von GetOverlappedResult für diesen Vorgang FALSE zurück, und GetLastError gibt ERROR_HANDLE_EOF zurück.

Hinweise

Wenn Sie ReadFileEx verwenden, sollten Sie GetLastError auch dann überprüfen, wenn die Funktion "success" zurückgibt, um nach Bedingungen zu suchen, die "Erfolge" sind, aber ein Ergebnis haben, das Sie vielleicht wissen möchten. Beispielsweise gibt ein Pufferüberlauf beim Aufrufen von ReadFileExTRUE zurück, aber GetLastError meldet den Überlauf mit ERROR_MORE_DATA. Wenn der Funktionsaufruf erfolgreich ist und keine Warnungsbedingungen vorhanden sind, gibt GetLastErrorERROR_SUCCESS zurück.

Die ReadFileEx-Funktion schlägt möglicherweise fehl, wenn zu viele ausstehende asynchrone E/A-Anforderungen vorhanden sind. Im Falle eines solchen Fehlers kann GetLastErrorERROR_INVALID_USER_BUFFER oder ERROR_NOT_ENOUGH_MEMORY zurückgeben.

Verwenden Sie eine der folgenden Optionen, um alle ausstehenden asynchronen E/A-Vorgänge abzubrechen:

CancelIo: Diese Funktion bricht nur Vorgänge ab, die vom aufrufenden Thread für das angegebene Dateihandle ausgegeben wurden.
CancelIoEx: Diese Funktion bricht alle Vorgänge ab, die von den Threads für das angegebene Dateihandle ausgegeben wurden.

Verwenden Sie CancelSynchronousIo, um ausstehende synchrone E/A-Vorgänge abzubrechen.

E/A-Vorgänge, die mit dem fehler ERROR_OPERATION_ABORTED abgebrochen werden.

Wenn ein Teil der durch hFile angegebenen Datei von einem anderen Prozess gesperrt wird und der in einem Aufruf von ReadFileEx angegebene Lesevorgang den gesperrten Teil überlappt, schlägt der Aufruf von ReadFileEx fehl.

Beim Versuch, Daten aus einem Maillot zu lesen, dessen Puffer zu klein ist, gibt ReadFileExFALSE und GetLastErrorERROR_INSUFFICIENT_BUFFER zurück.

Der Zugriff auf den Eingabepuffer, während ein Lesevorgang den Puffer verwendet, kann zu einer Beschädigung der daten führen, die in diesen Puffer eingelesen werden. Anwendungen dürfen den Eingabepuffer, den ein Lesevorgang verwendet, erst nach Abschluss des Lesevorgangs lesen, in diese schreiben, neu zuweisen oder freigeben.

Eine Anwendung verwendet die Funktionen MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, WaitForMultipleObjectsEx und SleepEx , um einen warnbaren Wartezustand zu erhalten. Weitere Informationen zu warnbaren Wartevorgängen und überlappenden Eingaben/Ausgaben finden Sie unter Informationen zur Synchronisierung.

Es gibt strenge Anforderungen für die erfolgreiche Arbeit mit Dateien, die mit CreateFile mithilfe von FILE_FLAG_NO_BUFFERING geöffnet wurden. Weitere Informationen finden Sie unter Dateipufferung.

Unter 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

Transaktionierte Vorgänge

Ist an das Dateihandle eine Transaktion gebunden, gibt die Funktion Daten aus der transaktiven Dateiansicht zurück. Ein transaktives Lesehandle zeigt für die Dauer des Handles garantiert die gleiche Dateiansicht an. Weitere Informationen finden Sie unter Informationen zu transaktionsbasiertem NTFS.

Beispiele

Ein Beispiel finden Sie unter Named Pipe Server Using Completion Routines.

Anforderungen

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