ZwReadFile-Funktion (wdm.h)
Die ZwReadFile-Routine liest Daten aus einer geöffneten Datei.
Syntax
NTSYSAPI NTSTATUS ZwReadFile(
[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
Handle für das Dateiobjekt. Dieses Handle wird durch einen erfolgreichen Aufruf von ZwCreateFile oder ZwOpenFile erstellt.
[in, optional] Event
Optional ein Handle für ein Ereignisobjekt, 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
Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status und Informationen zum angeforderten Lesevorgang empfängt. Das Information-Element empfängt die Anzahl der Bytes, die tatsächlich aus der Datei gelesen werden.
[out] Buffer
Zeiger 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 puffer verweist.
[in, optional] ByteOffset
Zeiger auf eine Variable, die den Anfangsbyteoffset in der Datei angibt, in der der Lesevorgang beginnt. Wenn versucht wird, über das Ende der Datei hinaus zu lesen, gibt ZwReadFile einen Fehler zurück.
Wenn der Aufruf von ZwCreateFile eines der CreateOptions-Flags FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT festgelegt hat, behält der E/A-Manager die aktuelle Dateiposition bei. Wenn ja, kann der Aufrufer von ZwReadFile angeben, dass der aktuelle Dateipositionsoffset anstelle eines expliziten ByteOffset-Werts verwendet wird. Diese Spezifikation kann mit einer der folgenden Methoden erstellt 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.
ZwReadFile aktualisiert die aktuelle Dateiposition, indem die Anzahl der beim Abschluss des Lesevorgangs gelesenen Bytes hinzugefügt wird, wenn die aktuelle Dateiposition verwendet wird, die vom E/A-Manager verwaltet wird.
Auch wenn der E/A-Manager die aktuelle Dateiposition beibehielt, kann der Aufrufer diese Position zurücksetzen, indem er einen expliziten ByteOffset-Wert an ZwReadFile übergibt. Dadurch wird die aktuelle Dateiposition automatisch in diesen ByteOffset-Wert geändert, der Lesevorgang ausgeführt und dann die Position entsprechend der Anzahl der tatsächlich gelesenen Bytes aktualisiert. Diese Technik bietet dem Aufrufer einen atomischen Such- und Lesedienst.
[in, optional] Key
Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.
Rückgabewert
ZwReadFile gibt entweder STATUS_SUCCESS oder den entsprechenden NTSTATUS-Fehlercode zurück.
Hinweise
Aufrufer von ZwReadFile müssen bereits ZwCreateFile mit dem im DesiredAccess-Parameter festgelegten FILE_READ_DATA- oder GENERIC_READ-Wert aufgerufen haben.
Wenn der vorangehende Aufruf von ZwCreateFile das flag FILE_NO_INTERMEDIATE_BUFFERING im CreateOptions-Parameter auf ZwCreateFile festgelegt hat, müssen die Parameter Length und ByteOffset auf ZwReadFile Vielfache der Sektorgröße sein. Weitere Informationen finden Sie unter ZwCreateFile.
ZwReadFile 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 Parameter Length angegebene Anzahl von Bytes gelesen wurde. Daher können keine Daten mehr ohne Überlauf in den Puffer eingefügt werden.
Das Ende der Datei wird während des Lesevorgangs erreicht, sodass keine weiteren Daten in der Datei vorhanden sind, die in den Puffer übertragen werden sollen.
Wenn der Aufrufer die Datei mit dem in DesiredAccess festgelegten SYNCHRONIZE-Flag geöffnet hat, kann der aufrufende Thread mit dem Abschluss des Lesevorgangs synchronisiert werden, indem er auf das Dateihandle wartet. 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 (FILE_SYNCHRONOUS_IO_NONALERT oder FILE_SYNCHRONOUS_IO_ALERT) geöffnet wurde. In diesem Fall wartet ZwReadFile im Namen des Aufrufers und wird erst zurückgegeben, wenn 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. FILE_SYNCHRONOUS_IO_ XXX-Flag wurde nicht angegeben).
Das Handle wird jeweils nur für einen E/A-Vorgang verwendet.
ZwReadFile hat STATUS_PENDING zurückgegeben.
Ein Treiber sollte ZwReadFile im Kontext des Systemprozesses aufrufen, wenn eine der folgenden Bedingungen vorhanden ist:
Der Treiber hat das Dateihandle erstellt, das an ZwReadFile übergeben wird.
ZwReadFile benachrichtigt den Treiber über die E/A-Vervollständigung mithilfe eines Ereignisses, das der Treiber erstellt hat.
ZwReadFile benachrichtigt den Treiber über die E/A-Vervollständigung mithilfe einer APC-Rückrufroutine, die der Treiber an ZwReadFile übergibt.
Datei- und Ereignishandles sind nur in dem Prozesskontext gültig, in dem die Handles erstellt werden. Um Sicherheitslücken zu vermeiden, sollte der Treiber daher jedes Datei- oder Ereignishandle erstellen, das er im Kontext des Systemprozesses an ZwReadFile übergibt und nicht im Kontext des Prozesses, in dem sich der Treiber befindet.
Ebenso sollte ZwReadFile im Kontext des Systemprozesses aufgerufen werden, wenn es den Treiber über die E/A-Vervollständigung mittels APC benachrichtigt, da APCs immer im Kontext des Threads ausgelöst werden, der die E/A-Anforderung ausgibt. Wenn der Treiber ZwReadFile im Kontext eines anderen Prozesses als dem System 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 ZwReadFile müssen unter IRQL = PASSIVE_LEVEL und mit aktivierten speziellen Kernel-APCs ausgeführt werden.
Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtReadFile" anstelle von "ZwReadFile" verwenden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |