ZwWriteFile-Funktion (wdm.h)
Die ZwWriteFile-Routine schreibt Daten in eine geöffnete Datei.
Syntax
NTSYSAPI NTSTATUS ZwWriteFile(
[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
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 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
Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status und Informationen zum angeforderten Schreibvorgang empfängt. Der Information-Member empfängt die Anzahl der Bytes, die tatsächlich in die Datei geschrieben werden.
[in] Buffer
Zeiger 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 puffer verweist.
[in, optional] ByteOffset
Zeiger auf eine Variable, die den Anfangsbyteoffset in der Datei zum Starten des Schreibvorgangs angibt. Wenn Length und ByteOffset einen Schreibvorgang angeben, der über die aktuelle Dateiendemarkierung hinaus liegt, erweitert ZwWriteFile automatisch die Datei und aktualisiert die Dateiendemarkierung. Alle Bytes, die nicht explizit zwischen diesen alten und neuen End-of-File-Markierungen geschrieben werden, werden als null definiert.
Wenn der Aufruf von ZwCreateFile nur das DesiredAccess-Flag FILE_APPEND_DATA festgelegt hat, wird ByteOffset ignoriert. Daten im angegebenen Puffer für Längenbytes werden ab dem aktuellen Ende der Datei geschrieben.
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 ZwWriteFile angeben, dass anstelle eines expliziten ByteOffset-Werts der aktuelle Dateipositionsoffset 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.
ZwWriteFile aktualisiert die aktuelle Dateiposition, indem die Anzahl der geschriebenen Bytes hinzugefügt wird, wenn der Schreibvorgang abgeschlossen 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 ZwWriteFile übergibt. Dadurch wird die aktuelle Dateiposition automatisch in diesen ByteOffset-Wertgeändert, der Schreibvorgang ausgeführt und dann die Position entsprechend der Anzahl der tatsächlich geschriebenen Bytes aktualisiert. Diese Technik bietet dem Aufrufer einen atomischen Such- und Schreibdienst.
Es ist auch möglich, einen Schreibvorgang am aktuellen Ende der Datei zu starten, 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 bei behält.
[in, optional] Key
Geräte- und Zwischentreiber sollten diesen Zeiger auf NULL festlegen.
Rückgabewert
ZwWriteFile gibt STATUS_SUCCESS bei Erfolg oder den entsprechenden NTSTATUS-Fehlercode bei Einem Fehler zurück.
Hinweise
Aufrufer von ZwWriteFile müssen bereits ZwCreateFile mit dem flag FILE_WRITE_DATA, FILE_APPEND_DATA oder GENERIC_WRITE im DesiredAccess-Parameter aufgerufen haben. Beachten Sie, dass nur FILE_APPEND_DATA Zugriff auf eine Datei dem Aufrufer nicht erlaubt, an einer beliebigen Stelle in der Datei zu schreiben, außer am aktuellen Ende der Datei, während FILE_WRITE_DATA Zugriff auf eine Datei den Aufrufer nicht daran hindert, an oder über das Ende einer Datei zu schreiben.
Wenn der vorangehende Aufruf von ZwCreateFile das CreateOptions-Flag FILE_NO_INTERMEDIATE_BUFFERING festgelegt hat, müssen die Parameter Length und ByteOffset auf ZwWriteFile ein Integral der Sektorgröße sein. Weitere Informationen finden Sie unter ZwCreateFile.
ZwWriteFile beginnt den Schreibvorgang für die Datei bei ByteOffset, an der aktuellen Dateiposition oder am Ende der Dateimarkierung. Der Schreibvorgang wird beendet, wenn Längenbytes aus Buffer geschrieben wurden. Bei Bedarf wird die Länge der Datei verlängert und die End-of-File-Markierung zurückgesetzt.
Wenn der Aufrufer die Datei mit festgelegtem DesiredAccess SYNCHRONIZE-Flag geöffnet hat, kann der Aufrufer warten, bis diese Routine das angegebene FileHandle auf den signalierten Zustand festgelegt hat.
Treiber sollten ZwWriteFile in drei Fällen im Kontext des Systemprozesses aufrufen:
Der Treiber erstellt das Dateihandle, das an ZwWriteFile übergeben wird.
ZwWriteFile benachrichtigt den Treiber über die E/A-Vervollständigung mithilfe eines vom Treiber erstellten Ereignisses.
ZwWriteFile benachrichtigt den Treiber über die E/A-Vervollständigung mithilfe einer APC-Rückrufroutine, die der Treiber an ZwWriteFile ü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 anstelle des Prozesskontexts, in dem sich der Treiber befindet, an ZwWriteFile übergibt.
Ebenso sollte ZwWriteFile im Kontext des Systemprozesses aufgerufen werden, wenn es den Treiber über die E/A-Vervollständigung mithilfe eines APC benachrichtigt, da APCs immer im Kontext des Threads ausgelöst werden, der die E/A-Anforderung ausgibt. Wenn der Treiber ZwWriteFile 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 möglicherweise nie in einen warnbaren Wartezustand wechselt.
Weitere Informationen zum Arbeiten mit Dateien finden Sie unter Verwenden von Dateien in einem Treiber.
Aufrufer von ZwWriteFile 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 "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 verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der systemeigenen Systemdienstroutinen.
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 | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |