FltWriteFile-Funktion (fltkernel.h)

FltWriteFile- wird verwendet, um Daten in eine geöffnete Datei, einen Datenstrom oder ein Gerät zu schreiben.

Syntax

NTSTATUS FLTAPI FltWriteFile(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext
);

Parameter

[in] InitiatingInstance

Ein undurchsichtiger Instanzzeiger für die Minifiltertreiberinstanz, an die der Vorgang gesendet werden soll. Die Instanz muss an das Volume angefügt werden, auf dem sich die Datei befindet. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] FileObject

Zeigen Sie auf eine FILE_OBJECT für die Datei, in die die Daten geschrieben werden sollen. Dieses Dateiobjekt muss zurzeit geöffnet sein. Das Aufrufen FltWriteFile-, wenn das Dateiobjekt noch nicht geöffnet ist oder nicht mehr geöffnet ist (z. B. in einer Vorerstellungs- oder Nachbereinigungsrückrufroutine), bewirkt, dass das System auf einem überprüften Build ASSERT erhält. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in, optional] ByteOffset

Zeigen Sie auf eine vom Aufrufer zugewiesene Variable, die den Anfangsbyte-Offset innerhalb der Datei angibt, in der der Lesevorgang beginnen soll.

Wenn ByteOffset- angegeben wird, wird die E/A an diesem Offset ausgeführt, unabhängig vom aktuellen Wert des CurrentByteOffset Felds des Dateiobjekts.

  • Wenn die Datei für synchrone E/A geöffnet wurde (FO_SYNCHRONOUS_IO im feld Flags des Dateiobjekts festgelegt ist), kann der Aufrufer ByteOffset->LowPart- FILE_USE_FILE_POINTER_POSITION und ByteOffset->HighPart, um die E/A--1 für das CurrentByteOffset Feld des Dateiobjekts auszuführen. Wenn die Datei nicht für synchrone E/A geöffnet wurde, ist die Verwendung von FILE_USE_FILE_POINTER_POSITION ein Fehler.
  • Der Aufrufer kann ByteOffset->LowPart- auf FILE_WRITE_TO_END_OF_FILE und ByteOffset->HighPart- festlegen, um den Schreibvorgang am Ende der Datei -1 zu starten (d. h. einen Anfügeschreibvorgang ausführen).

Wenn ByteOffset- nicht angegeben ist:

  • Wenn die Datei nicht für synchrone E/A geöffnet wurde, ist dies ein Fehler.
  • Andernfalls wird die E/A im CurrentByteOffset-des Dateiobjekts ausgeführt.

Wenn das Dateiobjekt für synchrone E/A geöffnet wurde, wird das CurrentByteOffset Feld aktualisiert, es sei denn, der Aufrufer übergibt das FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET Flag.

  • Hinweis: Das Dateisystem aktualisiert weiterhin CurrentByteOffset- in diesem Fall. Der Filter-Manager speichert den CurrentByteOffset Wert, bevor der E/A-Wert nach unten gesendet und wiederhergestellt wird, wenn der E/A-Wert zurückgegeben wird. Aus Sicht des Aufrufers von FltWriteFile (und Filter in höheren Höhen) wird die CurrrentByteOffset nicht aktualisiert. Filter unter dem Aufrufer sehen jedoch den aktualisierten CurrentByteOffset Wert in ihren Rückrufen nach Lese-/Schreibzugriff.

Wenn das Dateiobjekt nicht für synchrone E/A geöffnet wurde, wird das feld CurrentByteOffset nicht aktualisiert, unabhängig vom Status des ByteOffset-Parameters.

Wenn das Dateiobjekt, das FileObject verweist, für asynchrone E/A geöffnet wurde, ist dieser Parameter erforderlich und kann nicht NULL sein.

Vor Windows 8 werden die speziellen Konstanten FILE_WRITE_TO_END_OF_FILE und FILE_USE_FILE_POINTER_POSITION für diesen Parameter nicht unterstützt.

[in] Length

Größe des Puffers, auf den der Buffer Parameter verweist, in Byte.

[in] Buffer

Zeigen Sie auf einen Puffer, der die daten enthält, die in die Datei geschrieben werden sollen. Wenn die Datei für nicht zwischengespeicherte E/A geöffnet wird, muss dieser Puffer entsprechend der Ausrichtungsanforderung des zugrunde liegenden Speichergeräts ausgerichtet werden. Minifiltertreiber können einen solchen ausgerichteten Puffer zuordnen, indem FltAllocatePoolAlignedWithTagaufgerufen wird.

[in] Flags

Bitmaske von Flags, die den Typ des auszuführenden Schreibvorgangs angeben.

Flagge Bedeutung
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET Minifiltertreiber können dieses Flag festlegen, um anzugeben, dass FltWriteFile- das CurrentByteOffset Feld des Dateiobjekts nicht aktualisiert.
FLTFL_IO_OPERATION_NON_CACHED Minifiltertreiber können dieses Flag so festlegen, dass ein nicht zwischengespeicherter Schreibzugriff angegeben wird, auch wenn das Dateiobjekt nicht mit FILE_NO_INTERMEDIATE_BUFFERING geöffnet wurde.
FLTFL_IO_OPERATION_PAGING Minifiltertreiber können dieses Kennzeichen festlegen, um einen Paging-Schreibzugriff anzugeben.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING Minifiltertreiber können dieses Kennzeichen festlegen, um einen synchronen E/A-Schreibvorgang anzugeben. Minifiltertreiber, die dieses Kennzeichen festlegen, müssen auch das FLTFL_IO_OPERATION_PAGING Flag festlegen. Dieses Kennzeichen ist ab Windows Vista verfügbar.

[out, optional] BytesWritten

Zeigen Sie auf eine vom Aufrufer zugewiesene Variable, die die Anzahl der in die Datei geschriebenen Bytes empfängt. Wenn CallbackRoutine- nicht NULL ist, wird dieser Parameter ignoriert. Andernfalls ist dieser Parameter optional und kann NULL sein.

[in, optional] CallbackRoutine

Zeiger auf eine PFLT_COMPLETED_ASYNC_IO_CALLBACK-typed callback routine to call when the write operation is complete. Dieser Parameter ist optional und kann NULL sein.

[in, optional] CallbackContext

Kontextzeiger, der an die CallbackRoutine übergeben werden soll, wenn vorhanden. Dieser Parameter ist optional und kann NULL sein. Wenn CallbackRoutine NULL ist, wird dieser Parameter ignoriert.

Rückgabewert

FltWriteFile gibt den NTSTATUS-Wert zurück, der vom Dateisystem zurückgegeben wurde.

Bemerkungen

Ein Minifiltertreiber ruft FltWriteFile- auf, um Daten in eine geöffnete Datei zu schreiben.

FltWriteFile- bewirkt, dass eine Schreibanforderung an die Minifiltertreiberinstanzen gesendet wird, die unterhalb der initiierenden Instanz und an das Dateisystem angefügt sind. Die angegebene Instanz und die darüber angefügten Instanzen erhalten nicht die Schreibanforderung.

FltWriteFile führt nicht zwischengespeicherte E/A-Vorgänge aus, wenn einer der folgenden Werte zutrifft:

  • Der Aufrufer legt das FLTFL_IO_OPERATION_NON_CACHED Flag im Flags Parameter fest.

  • Das Dateiobjekt wurde für nicht zwischengespeicherte E/A geöffnet. In der Regel erfolgt dies durch Angeben des FILE_NO_INTERMEDIATE_BUFFERING CreateOptions- Flags im vorherigen Aufruf von FltCreateFile, FltCreateFileExoder ZwCreateFile.

Nicht zwischengespeicherte E/A-Werte legen die folgenden Einschränkungen für die Parameterwerte fest, die an FltWriteFile-übergeben werden:

  • Der Puffer, auf den der Buffer Parameter verweist, muss entsprechend der Ausrichtungsanforderung des zugrunde liegenden Speichergeräts ausgerichtet werden. Um einen solchen ausgerichteten Puffer zuzuweisen, rufen Sie FltAllocatePoolAlignedWithTagauf.

  • Der Byte-Offset, auf den der ByteOffset Parameter verweist, muss ein nicht-negatives Vielfaches der Größe des Volumensektors sein.

  • Die im Parameter Length Parameter angegebene Länge muss ein nicht negatives Vielfaches der Größe des Volumensektors sein.

Wenn der Wert der CallbackRoutine Parameter nicht NULL ist, wird der Schreibvorgang asynchron ausgeführt.

Wenn der Wert der CallbackRoutine Parameter NULL ist, wird der Schreibvorgang synchron ausgeführt. Das heißt, FltWriteFile wartet, bis der Schreibvorgang abgeschlossen ist, bevor er zurückgegeben wird. Dies gilt auch, wenn das Dateiobjekt, das fileObject verweist, für asynchrone E/A geöffnet wurde.

Wenn mehrere Threads FltWriteFile- für dasselbe Dateiobjekt aufrufen und das Dateiobjekt für synchrone E/A geöffnet wurde, versucht der Filter-Manager nicht, E/A in der Datei zu serialisieren. In dieser Hinsicht unterscheidet sich FltWriteFile von ZwWriteFile.

Anforderungen

Anforderung Wert
Zielplattform- Universal
Header- fltkernel.h (include Fltkernel.h)
Library FltMgr.lib
DLL- Fltmgr.sys
IRQL- PASSIVE_LEVEL

Siehe auch

FILE_OBJECT

FltAllocatePoolAlignedWithTag-

FltCreateFile-

FltCreateFileEx

FltReadFile-

ObReferenceObjectByHandle-

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile-

ZwReadFile-

ZwWriteFile-