NtReadFile-Funktion

Liest Daten aus einer geöffneten Datei.

Diese Funktion entspricht dem Benutzermodus der ZwReadFile-Funktion, die im Windows Driver Kit (WDK) dokumentiert ist.

Syntax

NTSTATUS NtReadFile(
  _In_     HANDLE           FileHandle,
  _In_opt_ HANDLE           Event,
  _In_opt_ PIO_APC_ROUTINE  ApcRoutine,
  _In_opt_ PVOID            ApcContext,
  _Out_    PIO_STATUS_BLOCK IoStatusBlock,
  _Out_    PVOID            Buffer,
  _In_     ULONG            Length,
  _In_opt_ PLARGE_INTEGER   ByteOffset,
  _In_opt_ PULONG           Key
);

Parameter

FileHandle [ In]

Handle für das Dateiobjekt. Dieses Handle wird durch einen erfolgreichen Aufruf von NtCreateFile oder NtOpenFileerstellt.

Ereignis [ in, optional]

Optional ein Handle für ein Ereignisobjekt, das nach Abschluss des Lesevorgangs auf den signalisierten Zustand festgelegt werden soll. Geräte- und Zwischentreiber sollten diesen Parameter auf NULL festlegen.

ApcRoutine [ in, optional]

Dieser Parameter ist reserviert. Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.

ApcContext [ in, optional]

Dieser Parameter ist reserviert. Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.

IoStatusBlock [ out]

Zeiger auf eine IO _ STATUS _ BLOCK-Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Lesevorgang empfängt. Der Information-Member empfängt die Anzahl der tatsächlich aus der Datei gelesenen Bytes.

Puffer [ out]

Zeiger auf einen vom Aufrufer zugeordneten Puffer, der die aus der Datei gelesenen Daten empfängt.

Länge [ In]

Die Größe des Puffers in Bytes, auf den von Buffer gezeigt wird.

ByteOffset [ in, optional]

Zeiger auf eine Variable, die den Start-Byteoffset in der Datei angibt, in der der Lesevorgang beginnt. Wenn versucht wird, über das Ende der Datei hinaus zu lesen, gibt NtReadFile einen Fehler zurück.

Wenn beim Aufruf von NtCreateFile eines der CreateOptions-Flags FILE _ SYNCHRONOUS IO ALERT oder FILE SYNCHRONOUS IO _ _ NONALERT festgelegt _ _ _ ist, behält der E/A-Manager die aktuelle Dateiposition bei. Wenn ja, kann der Aufrufer von NtReadFile angeben, dass der aktuelle Dateipositionsoffset anstelle eines expliziten ByteOffset-Werts verwendet werden soll. Diese Spezifikation kann mit einer der folgenden Methoden vorgenommen werden:

  • Geben Sie einen Zeiger auf einen LARGE _ INTEGER-Wert an, wobei der HighPart-Member auf -1 und der LowPart-Member auf den systemdefinierte Wert FILE USE FILE POINTER POSITION festgelegt _ _ _ _ ist.

  • Übergeben Sie einen NULL-Zeiger für ByteOffset.

NtReadFile aktualisiert die aktuelle Dateiposition, indem die Anzahl der gelesenen Bytes hinzugefügt wird, wenn der Lesevorgang abgeschlossen ist, wenn die aktuelle Dateiposition verwendet wird, die vom E/A-Manager verwaltet wird.

Selbst wenn der E/A-Manager die aktuelle Dateiposition beibehält, kann der Aufrufer diese Position zurücksetzen, indem er einen expliziten ByteOffset-Wert an NtReadFile übergibt. Dadurch ändert sich automatisch die aktuelle Dateiposition in diesen ByteOffset-Wert, führt den Lesevorgang aus und aktualisiert dann die Position entsprechend der Anzahl der tatsächlich gelesenen Bytes. Diese Technik bietet dem Aufrufer einen atomaren Such- und Lesedienst.

Schlüssel [ in, optional]

Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.

Rückgabewert

NtReadFile gibt entweder STATUS _ SUCCESS oder den entsprechenden NTSTATUS-Fehlercode zurück.

Hinweise

Aufrufer von NtReadFile müssen ntCreateFile bereits aufgerufen haben, wobei der WERT FILE _ READ DATA oder GENERIC READ im _ _ DesiredAccess-Parameter festgelegt ist.

Wenn der vorherige Aufruf von NtCreateFile das _ FILE NO INTERMEDIATE _ _ BUFFERING-Flag im CreateOptions-Parameter auf NtCreateFile festgelegt hat, müssen die Parameter Length und ByteOffset auf NtReadFile ein Vielfaches der Sektorgröße sein. Weitere Informationen finden Sie unter NtCreateFile.

NtReadFile beginnt mit dem Lesen aus dem angegebenen ByteOffset oder der aktuellen Dateiposition in den angegebenen Puffer. Der Lesevorgang wird unter einer der folgenden Bedingungen beendet:

  • Der Puffer ist voll, da die vom Length-Parameter angegebene Anzahl von Bytes gelesen wurde. Daher können keine Daten mehr ohne Überlauf in den Puffer platziert werden.

  • Das Ende der Datei wird während des Lesevorgangs erreicht, sodass die Datei keine Daten mehr enthält, die in den Puffer übertragen werden sollen.

Wenn der Aufrufer die Datei mit dem synchronize-Flag geöffnet hat, das in DesiredAccess festgelegt ist, kann der aufrufende Thread bis zum Abschluss des Lesevorgangs synchronisiert werden, indem auf das Dateihandle FileHandle gewartet wird. Das Handle wird jedes Mal signalisiert, wenn ein E/A-Vorgang, der für das Handle ausgegeben wurde, abgeschlossen wird. Der Aufrufer darf jedoch nicht auf ein Handle warten, das für den synchronen Dateizugriff geöffnet wurde (FILE _ SYNCHRONOUS _ IO _ NONALERT oder FILE _ SYNCHRONOUS IO _ _ ALERT). In diesem Fall wartet NtReadFile im Auftrag des Aufrufers und gibt nicht zurück, bis der Lesevorgang abgeschlossen ist. Der Aufrufer kann nur dann sicher auf das Dateihandle warten, wenn alle drei der folgenden Bedingungen erfüllt sind:

  • Das Handle wurde für den asynchronen Zugriff geöffnet (d. b. es wurde kein FILE _ SYNCHRONOUS _ IO _ XXX-Flag angegeben).

  • Das Handle wird jeweils nur für einen E/A-Vorgang verwendet.

  • NtReadFile hat STATUS _ PENDING zurückgegeben.

Ein Treiber sollte NtReadFile im Kontext des Systemprozesses aufrufen, wenn eine der folgenden Bedingungen vorhanden ist:

  • Der Treiber hat das Dateihandle erstellt, das er an NtReadFile übergibt.

  • NtReadFile benachrichtigt den Treiber über den E/A-Abschluss mithilfe eines Ereignisses, das der Treiber erstellt hat.

  • NtReadFile benachrichtigt den Treiber über den E/A-Abschluss mithilfe einer APC-Rückrufroutine, die der Treiber an NtReadFile übergibt.

Datei- und Ereignishandles sind nur im Prozesskontext gültig, in dem die Handles erstellt werden. Um Sicherheitslücken zu vermeiden, sollte der Treiber daher alle Dateien oder Ereignishandles erstellen, die im Kontext des Systemprozesses an NtReadFile übergeben werden, anstatt im Kontext des Prozesses, in dem sich der Treiber befindet.

Ebenso sollte NtReadFile im Kontext des Systemprozesses aufgerufen werden, wenn der Treiber über einen APC über den E/A-Abschluss benachrichtigt wird, da APCs immer im Kontext des Threads ausgelöst werden, der die E/A-Anforderung ausgibt. Wenn der Treiber NtReadFile im Kontext eines anderen Prozesses als des Systemprozesses aufruft, kann der APC auf unbestimmte Zeit verzögert werden oder gar nicht ausgelöst werden.

Weitere Informationen zum Arbeiten mit Dateien finden Sie unter Verwenden von Dateien in einem Treiber.

Aufrufer von NtReadFile müssen auf IRQL = PASSIVE _ LEVEL und mit aktivierten speziellen Kernel-APCsausgeführt werden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows 2000 Server [nur Desktop-Apps]
Zielplattform
Universell
Header
Wdm.h (einschließlich Wdm.h, Ntddk.h oder Ntifs.h)
Bibliothek
Ntdll.lib
DLL
Ntdll.dll (Benutzermodus)

Weitere Informationen

KeInitializeEvent

NtCreateFile

NtQueryInformationFile

NtSetInformationFile

NtWriteFile