NtReadFile-Funktion (ntifs.h)
Die NtReadFile Routine liest Daten aus einer geöffneten Datei.
Syntax
__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
Parameter
[in] FileHandle
Behandeln des Dateiobjekts. Dieses Handle wird durch einen erfolgreichen Aufruf von NtCreateFile- oder NtOpenFile-erstellt.
[in, optional] Event
Optional kann ein Handle zu einem Ereignisobjekt verwendet werden, das nach Abschluss des Lesevorgangs auf den signalierten Zustand festgelegt werden soll. Geräte- und Zwischentreiber sollten diesen Parameter auf NULL festlegen.
[in, optional] ApcRoutine
Dieser Parameter ist reserviert. Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.
[in, optional] ApcContext
Dieser Parameter ist reserviert. Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.
[out] IoStatusBlock
Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Lesevorgang empfängt. Der Information Member erhält die Anzahl der Bytes, die tatsächlich aus der Datei gelesen werden.
[out] Buffer
Zeigen Sie auf einen vom Aufrufer zugewiesenen Puffer, der die aus der Datei gelesenen Daten empfängt.
[in] Length
Die Größe des Puffers in Bytes, auf den Bufferverweist.
[in, optional] ByteOffset
Zeigen Sie auf eine Variable, die den Anfangsbyte-Offset 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 der Aufruf von NtCreateFile eines der CreateOptions- Flags FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT festlegen, 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 mithilfe einer der folgenden Methoden erfolgen:
- Geben Sie einen Zeiger auf einen LARGE_INTEGER Wert an, wobei das HighPart-Element auf -1 festgelegt ist, und das LowPart-Element, das auf den vom System definierten 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 sie die aktuelle Dateiposition verwendet, die vom E/A-Manager verwaltet wird.
Selbst wenn der E/A-Manager die aktuelle Dateiposition verwaltet, kann der Aufrufer diese Position zurücksetzen, indem ein expliziter ByteOffset- Wert an NtReadFile-übergeben wird. Dadurch wird die aktuelle Dateiposition automatisch an den wert ByteOffset, der Lesevorgang ausgeführt, und anschließend wird die Position entsprechend der Anzahl der tatsächlich gelesenen Bytes aktualisiert. Mit dieser Technik erhält der Aufrufer den Atomar-Seek-and-Read-Dienst.
[in, optional] Key
Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.
Rückgabewert
NtReadFile- gibt entweder STATUS_SUCCESS oder den entsprechenden NTSTATUS-Fehlercode zurück.
Bemerkungen
Aufrufer von NtReadFile- müssen bereits NtCreateFile- aufgerufen haben, wobei der FILE_READ_DATA oder GENERIC_READ Wert im parameter DesiredAccess festgelegt ist.
Wenn der vorherige Aufruf von NtCreateFile das FILE_NO_INTERMEDIATE_BUFFERING Flag im parameter CreateOptions auf NtCreateFilefestlegen, muss die Length und ByteOffset Parameter auf NtReadFile Vielfache der Sektorgröße sein.
NtReadFile- beginnt mit dem Lesen aus dem angegebenen ByteOffset- oder der aktuellen Dateiposition in die angegebene Buffer-. Er beendet den Lesevorgang unter einer der folgenden Bedingungen:
- Der Puffer ist voll, da die Anzahl der durch den Parameter Length Parameter angegebenen Bytes gelesen wurde. Daher können keine weiteren Daten ohne Überlauf in den Puffer eingefügt werden.
- Das Ende der Datei wird während des Lesevorgangs erreicht, sodass es keine weiteren Daten in der Datei gibt, die in den Puffer übertragen werden sollen.
Wenn der Aufrufer die Datei mit dem in DesiredAccessfestgelegten SYNCHRONIZE-Flag geöffnet hat, kann der aufrufende Thread mit dem Abschluss des Lesevorgangs synchronisiert werden, indem er auf das Dateihandle wartet, FileHandle. Das Handle wird jedes Mal signalisiert, wenn ein E/A-Vorgang, der auf dem Handle ausgegeben wurde, abgeschlossen ist. 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 Namen des Aufrufers und gibt erst zurück, wenn der Lesevorgang abgeschlossen ist. Der Aufrufer kann sicher auf den Dateihandle warten, wenn alle drei der folgenden Bedingungen erfüllt sind:
- Das Handle wurde für asynchronen Zugriff geöffnet (d. h. keine FILE_SYNCHRONOUS_IO_XXX- Flag wurde angegeben).
- Der Handle wird jeweils nur für einen E/A-Vorgang verwendet.
- NtReadFile 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 an NtReadFile-übergeben wird.
- NtReadFile- benachrichtigt den Treiber über den Abschluss von E/A mithilfe eines Ereignisses, das der Treiber erstellt hat.
- NtReadFile- benachrichtigt den Treiber über den Abschluss von E/A 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 ein Datei- oder Ereignishandle erstellen, das an NtReadFile- im Kontext des Systemprozesses und nicht im Kontext des Prozesses übergeben wird, in dem sich der Treiber befindet.
Ebenso sollte NtReadFile- im Kontext des Systemprozesses aufgerufen werden, wenn er den Treiber des E/A-Abschlusses mittels eines APC benachrichtigt, 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 dem System aufruft, kann der APC auf unbestimmte Zeit verzögert werden oder überhaupt nicht ausgelöst werden.
Weitere Informationen zum Arbeiten mit Dateien finden Sie unter Verwenden von Dateien in einem Treiber-.
Aufrufer von NtReadFile- müssen unter IRQL = PASSIVE_LEVEL und mit speziellen Kernel-APCs ausgeführt werden, dieaktiviert sind.
Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtReadFile" anstelle von "ZwReadFile" verwenden.
Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 |
| Zielplattform- | Universal |
| Header- | ntifs.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | BufAfterReqCompletedIntIoctlA, BufAfterReqCompletedIoctlA, BufAfterReqCompletedReadA, BufAfterReqCompletedWriteA, HwStorPortProhibitedDIs, PowerIrpDDis |