FltWriteFileEx-Funktion (fltkernel.h)

Artikel
11/16/2023

FltWriteFileEx wird verwendet, um Daten in eine geöffnete Datei, einen Stream oder ein gerät zu schreiben. Diese Funktion erweitert FltWriteFile , um die optionale Verwendung einer MDL zum Schreiben von Daten anstelle einer zugeordneten Pufferadresse zu ermöglichen.

Syntax

NTSTATUS FLTAPI FltWriteFileEx(
  [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,
  [in, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

Parameter

[in] InitiatingInstance

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

[in] FileObject

Ein Zeiger auf eine FILE_OBJECT für die Datei, in die die Daten geschrieben werden sollen. Dieses Dateiobjekt muss derzeit geöffnet sein. Das Aufrufen von FltWriteFileEx , wenn das Dateiobjekt noch nicht geöffnet oder nicht mehr geöffnet ist (z. B. in einer Rückrufroutine vor oder nach der Bereinigung), bewirkt, dass das System bei einem überprüften Build ASSERT erhält. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in, optional] ByteOffset

Zeiger auf eine vom Aufrufer zugeordnete Variable, die den Anfangsbyteoffset innerhalb der Datei angibt, in der der Lesevorgang beginnen soll.

Wenn ByteOffset angegeben ist, 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> auf FILE_USE_FILE_POINTER_POSITION und ByteOffset-HighPart auf -1 festlegen, damit die E/A im CurrentByteOffset-Feld> des Dateiobjekts ausgeführt wird. 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> auf -1 festlegen, um den Schreibvorgang am Ende der Datei zu starten (d. h. einen anfügenden Schreibvorgang auszuführen).

Wenn ByteOffset nicht angegeben ist:

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

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

Hinweis: Das Dateisystem aktualisiert in diesem Fall weiterhin CurrentByteOffset . Der Filter-Manager speichert den CurrentByteOffset-Wert vor dem Senden der E/A nach unten im Stapel und stellt ihn wieder her, wenn die E/A zurückgegeben wird. Aus sicht des Aufrufers von FltWriteFileEx (und Filter in höheren Höhen) wird das CurrrentByteOffset nicht aktualisiert. Filter unterhalb des Aufrufers 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 CurrentByteOffset-Feld unabhängig vom Status des ByteOffset-Parameters nicht aktualisiert.

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

FltWriteFileEx unterstützt das flag FILE_WRITE_TO_END_OF_FILE nicht.

[in] Length

Die Größe des Puffers in Bytes, auf den der Buffer-Parameter verweist. Wenn eine MDL in Mdl bereitgestellt wird, ist Length die Größe der Daten, die MDL beschreibt.

[in] Buffer

Ein Zeiger auf einen Puffer, der die Daten enthält, die in die Datei geschrieben werden sollen. Wenn die Datei für nicht zwischengespeicherte E/A-Vorgänge geöffnet wird, muss dieser Puffer gemäß der Ausrichtungsanforderung des zugrunde liegenden Speichergeräts ausgerichtet werden. Minifiltertreiber können einen solchen ausgerichteten Puffer zuordnen, indem sie FltAllocatePoolAlignedWithTag aufrufen.

Wenn eine MDL in Mdl bereitgestellt wird, muss buffer NULL sein.

[in] Flags

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

Flag	Bedeutung
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Minifiltertreiber können dieses Flag festlegen, um anzugeben, dass FltWriteFileEx das CurrentByteOffset-Feld des Dateiobjekts nicht aktualisiert.
FLTFL_IO_OPERATION_NON_CACHED	Minifiltertreiber können dieses Flag festlegen, um einen nicht zwischengespeicherten Schreibvorgang anzugeben, auch wenn das Dateiobjekt nicht mit FILE_NO_INTERMEDIATE_BUFFERING geöffnet wurde.
FLTFL_IO_OPERATION_PAGING	Minifiltertreiber können dieses Flag festlegen, um einen Pagingschreibvorgang anzugeben.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	Minifiltertreiber können dieses Flag festlegen, um einen synchronen E/A-Schreibvorgang für Paging anzugeben. Minifiltertreiber, die dieses Flag festlegen, müssen auch das FLTFL_IO_OPERATION_PAGING-Flag festlegen. Dieses Flag ist ab Windows Vista verfügbar.

[out, optional] BytesWritten

Ein Zeiger 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

Ein Zeiger auf eine PFLT_COMPLETED_ASYNC_IO_CALLBACK typisierte Rückrufroutine, die nach Abschluss des Schreibvorgangs aufgerufen werden soll. Dieser Parameter ist optional und kann NULL sein.

[in, optional] CallbackContext

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

[in, optional] Key

Ein optionaler Schlüssel, der einer Dateiobjektsperre zugeordnet ist.

[in, optional] Mdl

Eine optionale MDL, die die zu schreibenden Daten beschreibt. Wenn ein Puffer in Buffer bereitgestellt wird, muss Mdl NULL sein.

Rückgabewert

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

Hinweise

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

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

FltWriteFileEx führt nicht zwischengespeicherte E/A-Vorgänge aus, wenn eine der folgenden Punkte zutrifft:

Der Aufrufer legt das flag FLTFL_IO_OPERATION_NON_CACHED im Flags-Parameter fest.
Das Dateiobjekt wurde für nicht zwischengespeicherte E/A-Vorgänge geöffnet. In der Regel erfolgt dies durch Angabe des flags FILE_NO_INTERMEDIATE_BUFFERING****CreateOptions im vorherigen Aufruf von FltCreateFile, FltCreateFileEx oder ZwCreateFile.

Nicht zwischengespeicherte E/A-Vorgänge erzwingen die folgenden Einschränkungen für die Parameterwerte, die an FltWriteFileEx übergeben werden:

Der Puffer, auf den der Buffer-Parameter zeigt, muss gemäß der Ausrichtungsanforderung des zugrunde liegenden Speichergeräts ausgerichtet werden. Um einen solchen ausgerichteten Puffer zuzuordnen, rufen Sie FltAllocatePoolAlignedWithTag auf.
Der Byteoffset-Offset, auf den der ByteOffset-Parameter zeigt, muss ein nicht-negatives Vielfaches der Sektorgröße des Volumes sein.
Die im Parameter Length angegebene Länge muss ein nicht negatives Vielfaches der Sektorgröße des Volumes sein.

Wenn der Wert des CallbackRoutine-Parameters nicht NULL ist, wird der Schreibvorgang asynchron ausgeführt.

Wenn der Wert des CallbackRoutine-Parameters NULL ist, wird der Schreibvorgang synchron ausgeführt. Das heißt, FltWriteFileEx wartet, bis der Schreibvorgang abgeschlossen ist, bevor es zurückgegeben wird. Dies gilt auch, wenn das Dateiobjekt, auf das FileObject verweist, für asynchrone E/A geöffnet wurde.

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

Der Mdl-Parameter wird als Benutzerfreundlichkeit bereitgestellt, wenn ein Minifilter bereits über eine MDL verfügt. Die MDL wird direkt verwendet, und der zusätzliche Schritt zum Zuordnen einer Adresse für Buffer kann vermieden werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8
Zielplattform	Universell
Header	fltkernel.h (fltkernel.h einschließen)
Bibliothek	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL