NtWriteFile-Funktion (ntifs.h)
Die ZwWriteFile Routine schreibt Daten in eine geöffnete Datei.
Syntax
__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] 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: Ein Handle für ein Ereignisobjekt, das nach Abschluss des Schreibvorgangs 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 Schreibvorgang empfängt. Der Information Member erhält die Anzahl der Bytes, die tatsächlich in die Datei geschrieben wurden.
[in] Buffer
Zeigen Sie auf einen vom Aufrufer zugewiesenen Puffer, der die Daten enthält, die in die Datei geschrieben werden sollen.
[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 für den Anfang des Schreibvorgangs angibt. Wenn Length und ByteOffset einen Schreibvorgang über das aktuelle Ende der Dateimarke angeben, NtWriteFile die Datei automatisch erweitert und die End-of-File-Markierung aktualisiert; Alle Bytes, die nicht explizit zwischen solchen alten und neuen End-of-File-Markierungen geschrieben werden, werden als Null definiert.
Wenn der Aufruf von NtCreateFile nur das DesiredAccess Flag FILE_APPEND_DATA festlegen, wird ByteOffset- ignoriert. Daten im angegebenen Bufferwerden für Length Bytes beginnend am aktuellen Ende der Datei geschrieben.
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 NtWriteFile- 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 der HighPart Member auf -1 festgelegt ist, und das LowPart Member auf den vom System definierten Wert FILE_USE_FILE_POINTER_POSITION festgelegt ist.
- Übergeben Sie einen NULL-Zeiger für ByteOffset-.
NtWriteFile aktualisiert die aktuelle Dateiposition, indem die Anzahl von Bytes hinzugefügt wird, die geschrieben werden, wenn sie den Schreibvorgang abgeschlossen hat, 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 NtWriteFile-übergeben wird. Dadurch wird automatisch die aktuelle Dateiposition an den ByteOffsetWert geändert, der Schreibvorgang ausgeführt, und anschließend wird die Position entsprechend der Anzahl der tatsächlich geschriebenen Bytes aktualisiert. Diese Technik bietet dem Aufrufer einen atomaren Such- und Schreibdienst.
Es ist auch möglich, dass ein Schreibvorgang am aktuellen Ende der Datei gestartet wird, indem für ByteOffset ein Zeiger auf einen LARGE_INTEGER Wert angegeben wird, wobei HighPart- auf -1 und LowPart- auf FILE_WRITE_TO_END_OF_FILE festgelegt ist. Dies funktioniert unabhängig davon, ob der E/A-Manager die aktuelle Dateiposition aufrecht erhält.
[in, optional] Key
Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.
Rückgabewert
NtWriteFile- gibt STATUS_SUCCESS bei Erfolg oder den entsprechenden NTSTATUS-Fehlercode beim Fehler zurück.
Bemerkungen
Aufrufer von NtWriteFile- müssen bereits NtCreateFile- mit dem im Parameter DesiredAccess festgelegten FILE_WRITE_DATA-, FILE_APPEND_DATA- oder GENERIC_WRITE-Flag aufgerufen haben. Beachten Sie, dass nur FILE_APPEND_DATA Zugriff auf eine Datei dem Aufrufer das Schreiben an einer beliebigen Stelle in der Datei außer am aktuellen Ende der Datei ermöglicht, während FILE_WRITE_DATA Zugriff auf eine Datei nicht verhindert, dass der Aufrufer an das Ende einer Datei schreibt oder über das Ende einer Datei hinaus schreibt.
Wenn der vorherige Aufruf von NtCreateFile das CreateOptions-Flag FILE_NO_INTERMEDIATE_BUFFERING festlegen, muss die Length und ByteOffset Parameter auf NtWriteFile- ein integraler Bestandteil der Sektorgröße sein. Weitere Informationen finden Sie unter NtCreateFile.
NtWriteFile beginnt den Schreibvorgang in die Datei bei ByteOffset, an der aktuellen Dateiposition oder am Ende der Dateimarke. Der Schreibvorgang wird beendet, wenn er Länge Bytes aus Puffer-geschrieben hat. Bei Bedarf wird die Länge der Datei erweitert und das Ende der Dateimarke zurückgesetzt.
Wenn der Aufrufer die Datei mit dem Flag DesiredAccess SYNCHRONIZE geöffnet hat, kann der Aufrufer warten, bis diese Routine den angegebenen FileHandle- auf den signalierten Zustand festgelegt hat.
Treiber sollten NtWriteFile- im Kontext des Systemprozesses in drei Fällen aufrufen:
- Der Treiber erstellt das Dateihandle, das an NtWriteFileübergeben wird.
- NtWriteFile den Treiber des E/A-Abschlusses anhand eines vom Treiber erstellten Ereignisses benachrichtigt.
- NtWriteFile den Treiber des E/A-Abschlusses anhand einer APC-Rückrufroutine benachrichtigt, die der Treiber an NtWriteFileü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 NtWriteFile- im Kontext des Systemprozesses und nicht im Prozesskontext übergeben wird, in dem sich der Treiber befindet.
Ebenso sollte NtWriteFile- 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 NtWriteFile- im Kontext eines anderen Prozesses als des Systemprozesses aufruft, kann der APC auf unbestimmte Zeit verzögert werden, oder er wird möglicherweise gar nicht ausgelöst, da der ursprüngliche Thread niemals in einen warnbaren Wartezustand wechselt.
Weitere Informationen zum Arbeiten mit Dateien finden Sie unter Verwenden von Dateien in einem Treiber-.
Aufrufer von NtWriteFile- 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 "NtWriteFile" anstelle von "ZwWriteFile" 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 | HwStorPortProhibitedDIs, PowerIrpDDis |