FltReadFileEx-Funktion (fltkernel.h)
FltReadFileEx liest Daten aus einer geöffneten Datei, einem stream oder einem gerät. Diese Funktion erweitert FltReadFile , um die optionale Verwendung einer MDL für Lesedaten anstelle einer zugeordneten Pufferadresse zu ermöglichen.
Syntax
NTSTATUS FLTAPI FltReadFileEx(
[in] PFLT_INSTANCE InitiatingInstance,
[in] PFILE_OBJECT FileObject,
[in, optional] PLARGE_INTEGER ByteOffset,
[in] ULONG Length,
[out] PVOID Buffer,
[in] FLT_IO_OPERATION_FLAGS Flags,
[out, optional] PULONG BytesRead,
[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, in dem sich die Datei befindet. Dieser Parameter ist erforderlich und darf nicht NULL sein.
[in] FileObject
Ein Zeiger auf einen FILE_OBJECT für die Datei, aus der die Daten gelesen werden sollen. Dieses Dateiobjekt muss derzeit geöffnet sein. Das Aufrufen von FltReadFileEx , wenn das Dateiobjekt noch nicht geöffnet ist oder nicht mehr geöffnet ist (z. B. in einer Rückrufroutine vor oder nach der Bereinigung), führt dazu, 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 zugewiesene Variable, die den Anfangsbyteoffset in 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 Felds CurrentByteOffset 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-Vorgänge geöffnet wurde, ist die Verwendung FILE_USE_FILE_POINTER_POSITION ein Fehler.
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 CurrentByteOffset-Feld aktualisiert, es sei denn, der Aufrufer übergibt das flag FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.
- Hinweis: In diesem Fall aktualisiert das Dateisystem weiterhin CurrentByteOffset . Der Filter-Manager speichert den Wert CurrentByteOffset vor dem Senden der E/A im Stapel und stellt ihn wieder her, wenn die E/A zurückgibt. Aus sicht des Aufrufers von FltReadFileEx (und Filter in höheren Höhen) wird das 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-Vorgänge geöffnet wurde, wird das Feld CurrentByteOffset unabhängig vom Zustand des ByteOffset-Parameters nicht aktualisiert.
[in] Length
Die Größe des Puffers in Bytes, auf den der Buffer-Parameter verweist.
[out] Buffer
Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der die aus der Datei gelesenen Daten empfängt. Wenn eine MDL in Mdl bereitgestellt wird, muss Puffer NULL sein.
[in] Flags
Eine Bitmaske von Flags, die den Typ des auszuführenden Lesevorgangs angeben.
| Flag | Bedeutung |
|---|---|
| FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Minifiltertreiber können dieses Flag festlegen, um anzugeben, dass FltReadFile das CurrentByteOffset-Feld des Dateiobjekts nicht aktualisieren soll. |
| FLTFL_IO_OPERATION_NON_CACHED | Minifiltertreiber können dieses Flag festlegen, um einen nicht zwischengespeicherten Lesevorgang 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 Paginglesevorgang anzugeben. |
| FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING | Minifiltertreiber können dieses Flag festlegen, um einen synchronen E/A-Lesevorgang anzugeben. Minifiltertreiber, die dieses Flag festlegen, müssen auch das FLTFL_IO_OPERATION_PAGING-Flag festlegen. Verfügbar ab Windows Vista. |
[out, optional] BytesRead
Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Anzahl der aus der Datei gelesenen 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 typisierte Rückrufroutine, die aufgerufen werden soll, wenn der Lesevorgang abgeschlossen ist. Dieser Parameter ist optional und kann NULL sein.
[in, optional] CallbackContext
Ein Kontextzeiger, der an die CallbackRoutine übergeben werden soll, falls 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 Bytebereichssperre zugeordnet ist.
[in, optional] Mdl
Eine optionale MDL, die den Speicher beschreibt, in dem die Daten gelesen werden. Wenn ein Puffer in Puffer bereitgestellt wird, muss Mdl NULL sein.
Rückgabewert
FltReadFileEx gibt den NTSTATUS-Wert zurück, der vom Dateisystem zurückgegeben wurde.
Hinweise
Ein Minifiltertreiber ruft FltReadFileEx auf, um Daten aus einer geöffneten Datei zu lesen.
FltReadFileEx erstellt eine Leseanforderung und sendet sie an die Minifiltertreiberinstanzen, die unterhalb der initiierenden instance angefügt sind, und an das Dateisystem. Die angegebene instance und die darüber angefügten Instanzen empfangen die Leseanforderung nicht.
FltReadFileEx führt nicht zwischengespeicherte E/A-Vorgänge aus, wenn einer der folgenden Punkte zutrifft:
Der Aufrufer hat das FLTFL_IO_OPERATION_NON_CACHED-Flag im Flags-Parameter festgelegt.
Das Dateiobjekt wurde für nicht zwischengespeicherte E/A-Vorgänge geöffnet. In der Regel erfolgt dies durch Angabe des FILE_NO_INTERMEDIATE_BUFFERING CreateOptions-Flags 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 FltReadFileEx übergeben werden:
Der Puffer, auf den der Pufferparameter verweist, muss entsprechend der Ausrichtungsanforderung des zugrunde liegenden Speichergeräts ausgerichtet werden. Um einen solchen ausgerichteten Puffer zuzuweisen, rufen Sie FltAllocatePoolAlignedWithTag auf.
Der Byteoffset-Offset, auf den der ByteOffset-Parameter verweist, muss ein nicht-negatives Vielfaches der Sektorgröße des Volumes sein.
Die im Length-Parameter angegebene Länge muss ein nicht bestimmtes Vielfaches der Sektorgröße des Volumes sein.
Wenn versucht wird, über das Ende der Datei hinaus zu lesen, gibt FltReadFileEx einen Fehler zurück.
Wenn der Wert des CallbackRoutine-Parameters nicht NULL ist, wird der Lesevorgang asynchron ausgeführt.
Wenn der Wert des CallbackRoutine-Parameters NULL ist, wird der Lesevorgang synchron ausgeführt. Das heißt, FltReadFileEx wartet, bis der Lesevorgang abgeschlossen ist, bevor er zurückgegeben wird. Dies gilt auch dann, wenn das Dateiobjekt, auf das FileObject verweist, für asynchrone E/A-Vorgänge geöffnet wurde.
Wenn mehrere Threads FltReadFileEx für dasselbe Dateiobjekt aufrufen und das Dateiobjekt für synchrone E/A-Vorgänge geöffnet wurde, versucht der Filter-Manager nicht, E/A für die Datei zu serialisieren. In dieser Hinsicht unterscheidet sich FltReadFileEx von ZwReadFile.
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 des Zuordnens einer Adresse für Puffer kann vermieden werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 8 |
| Zielplattform | Universell |
| Header | fltkernel.h (include Fltkernel.h) |
| Bibliothek | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |