FltCreateFileEx-Funktion (fltkernel.h)

Artikel
08/07/2023

Minifiltertreiber rufen FltCreateFileEx auf, um eine neue Datei zu erstellen oder eine vorhandene Datei zu öffnen.

Syntax

NTSTATUS FLTAPI FltCreateFileEx(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [out]          PHANDLE            FileHandle,
  [out]          PFILE_OBJECT       *FileObject,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           ULONG              Flags
);

Parameter

[in] Filter

Ein undurchsichtiger Filterzeiger für den Aufrufer.

[in, optional] Instance

Ein nicht transparenter instance-Zeiger für den Minifiltertreiber instance, an den die Erstellungsanforderung gesendet werden soll. Die instance muss an das Volume angefügt werden, auf dem sich die Datei oder das Verzeichnis befindet. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, wird die Anforderung an das Geräteobjekt am Anfang des Dateisystemtreiberstapels für das Volume gesendet. Wenn es nicht NULL ist, wird die Anforderung nur an Minifiltertreiberinstanzen gesendet, die unterhalb der angegebenen instance angefügt sind.

[out] FileHandle

Ein Zeiger auf eine vom Aufrufer zugeordnete Variable, die das Dateihandle empfängt, wenn der Aufruf von FltCreateFileEx erfolgreich ist.

[out] FileObject

Ein Zeiger auf eine vom Aufrufer zugeordnete Variable, die den Dateiobjektzeiger empfängt, wenn der Aufruf von FltCreateFileEx erfolgreich ist. Dieser Parameter ist optional und kann NULL sein.

[in] DesiredAccess

Eine Bitmaske von Flags, die den Typ des Zugriffs auf die Datei oder das Verzeichnis angeben, den der Aufrufer benötigt. Weitere Informationen zu diesem Parameter und die Liste der Flagwerte finden Sie im DesiredAccess-Parameter von IoCreateFileEx .

[in] ObjectAttributes

Zeiger auf eine nicht transparente OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributes initialisiert wurde. Weitere Informationen und eine Beschreibung der einzelnen Strukturmember finden Sie im Parameter ObjectAttributes von IoCreateFileEx .

[out] IoStatusBlock

Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status und Informationen zum angeforderten Vorgang empfängt. Weitere Informationen finden Sie unter dem IoStatusBlock-Parameter von IoCreateFileEx.

[in, optional] AllocationSize

Gibt optional die anfängliche Zuordnungsgröße in Byte für den Dateidatenstrom an. Ein Wert ungleich null hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder ersetzt.

[in] FileAttributes

Gibt mindestens ein FILE_ATTRIBUTE_XXX-Flags an, die die festzulegenden Dateiattribute darstellen, wenn Sie eine Datei erstellen, ablösen oder überschreiben. Weitere Informationen und eine Liste der Flags finden Sie im FileAttributes-Parameter von IoCreateFileEx .

[in] ShareAccess

Gibt den Typ des Freigabezugriffs auf die Datei an, den der Aufrufer benötigt, als Null oder 1 oder eine Kombination der Flags. Weitere Informationen und eine Liste der Flags finden Sie im ShareAccess-Parameter von IoCreateFileEx .

[in] CreateDisposition

Gibt einen Wert an, der die auszuführende Aktion bestimmt, je nachdem, ob die Datei bereits vorhanden ist. Eine Liste der möglichen Werte finden Sie im Disposition-Parameter von IoCreateFileEx .

[in] CreateOptions

Gibt die Optionen an, die beim Erstellen oder Öffnen der Datei angewendet werden sollen. Dieser Parameter ist eine kompatible Kombination der Flags, die im CreateOptions-Parameter von IoCreateFileEx aufgeführt und beschrieben werden.

[in, optional] EaBuffer

Ein Zeiger auf einen vom Aufrufer bereitgestellten FILE_FULL_EA_INFORMATION strukturierten Puffer mit erweiterten Attributinformationen (EA), die auf die Datei angewendet werden sollen.

[in] EaLength

Länge von EaBuffer in Bytes.

[in] Flags

Gibt Optionen an, die während der Erstellung der Erstellungsanforderung verwendet werden sollen. Eine Liste der möglichen Optionen finden Sie im Options-Parameter von IoCreateFileEx .

Rückgabewert

FltCreateFileEx gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück. Eine Liste der möglichen Rückgabecodes finden Sie im Abschnitt Rückgabewert von IoCreateFileEx .

Hinweis

FltCreateFileEx gibt möglicherweise STATUS_FILE_LOCK_CONFLICT als Rückgabewert oder im Status-Element der IO_STATUS_BLOCK-Struktur zurück, auf die der IoStatusBlock-Parameter verweist. Dies würde nur auftreten, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während FltCreateFileEx versucht, diese Situation zu behandeln.

Hinweise

Dateisystem-Minifiltertreiber sollten FltCreateFileEx anstelle von FltCreateFile aufrufen, um einen Dateiobjektzeiger für die Verwendung mit FltXxx-E /A-Routinen wie FltReadFile und FltQueryInformationFile abzurufen.

FltCreateFileEx sendet die Erstellungsanforderung nur an die Instanzen, die unterhalb des angegebenen Minifiltertreibers instance und an das Dateisystem angefügt sind. Die angegebene instance und die darüber angefügten Instanzen empfangen die Erstellungsanforderung nicht. Wenn kein instance angegeben ist, wird die Anforderung an den Anfang des Stapels geleitet und von allen Instanzen und dem Dateisystem empfangen.

Es gibt zwei alternative Möglichkeiten, den Namen der Datei anzugeben, die mit FltCreateFileEx erstellt oder geöffnet werden soll:

Als vollqualifizierter Pfadname, der im ObjectName-Element der Eingabe ObjectAttributes angegeben wird.
Als Pfadname relativ zur Verzeichnisdatei, die durch das Handle im RootDirectory-Element der ObjectAttributes-Eingabe dargestellt wird.

Jedes FileHandle , das von FltCreateFileEx abgerufen wird, muss schließlich durch Aufrufen von FltClose freigegeben werden. Darüber hinaus muss jeder zurückgegebene FileObject-Zeiger dereferenziert werden, wenn er durch Aufrufen von ObDereferenceObject nicht mehr benötigt wird.

Treiberroutinen, die nicht im Systemprozesskontext ausgeführt werden, müssen das OBJ_KERNEL_HANDLE-Attribut für den ObjectAttributes-Parameter von FltCreateFileEx festlegen. Das Festlegen dieses Attributs schränkt die Verwendung des von FltCreateFileEx zurückgegebenen Handles auf Prozesse ein, die im Kernelmodus ausgeführt werden. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen.

Hinweis

Rufen Sie diese Routine nicht mit einem Nicht-NULL-IRP-Wert der obersten Ebene auf, da dies zu einem System deadlock führen kann.

Bestimmte DesiredAccess-Flags und Kombinationen von Flags haben die folgenden Auswirkungen:

Damit ein Aufrufer eine E/A-Vervollständigung synchronisieren kann, indem er darauf wartet, dass der zurückgegebene FileHandle auf den Signalzustand festgelegt wird, muss das SYNCHRONIZE-Flag festgelegt werden.
Wenn nur die Flags FILE_APPEND_DATA und SYNCHRONIZE festgelegt sind, kann der Aufrufer nur an das Ende der Datei schreiben, und alle Offsetinformationen zu Schreibvorgängen in die Datei werden ignoriert. Die Datei wird jedoch automatisch erweitert, wenn dies für diese Art von Schreibvorgang erforderlich ist.
Das Festlegen des FILE_WRITE_DATA-Flags für eine Datei ermöglicht auch Schreibvorgänge über das Ende der Datei hinaus. Die Datei wird auch für diese Schreibart automatisch erweitert.
Wenn nur die Flags FILE_EXECUTE und SYNCHRONIZE festgelegt sind, kann der Aufrufer die zurückgegebene FileHandle-Datei nicht verwenden, um Daten direkt in oder aus der Datei zu lesen oder daraus zu schreiben. Das heißt, alle Vorgänge für die Datei müssen die System paging-E/A verwenden, um Dateidaten zu lesen oder zu schreiben.

Der ShareAccess-Parameter bestimmt, ob separate Threads möglicherweise gleichzeitig auf dieselbe Datei zugreifen können. Wenn beide Dateiöffner über die Berechtigung verfügen, auf die angegebene Weise auf eine Datei zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von FltCreateFileEx keine FILE_SHARE_READ, FILE_SHARE_WRITE oder FILE_SHARE_DELETE angibt, können keine anderen Geöffneten Vorgänge für die Datei ausgeführt werden, da der ursprüngliche Aufrufer exklusiven Zugriff auf die Datei erhält.

Damit eine freigegebene Datei erfolgreich geöffnet werden kann, muss der angeforderte DesiredAccess für die Datei sowohl mit den DesiredAccess - als auch mit den ShareAccess-Spezifikationen aller vorherigen Geöffnete kompatibel sein, die noch nicht mit FltClose veröffentlicht wurden. Das heißt, der desiredAccess , der für FltCreateFileEx für eine bestimmte Datei angegeben wurde, darf nicht mit den Zugriffen in Konflikt stehen, die andere Öffnende der Datei nicht zugelassen haben.

Hinweis

Wenn IO_IGNORE_SHARE_ACCESS_CHECK im Flags-Parameter angegeben ist, ignoriert der E/A-Manager den ShareAccess-Parameter . Das Dateisystem kann jedoch weiterhin Zugriffsprüfungen durchführen. Daher ist es wichtig, den gewünschten Freigabemodus für den ShareAccess-Parameter anzugeben, auch wenn sie das flag IO_IGNORE_SHARE_ACCESS_CHECK verwenden. Beachten Sie außerdem, dass das Dateisystem, wenn IO_IGNORE_SHARE_ACCESS_CHECK angegeben ist, den gewünschten Zugriff oder den freigegebenen Zugriff des aktuellen Geöffneten nicht nachverfolgt. Aus diesem Fall können nachfolgende offene Aufrufe für dieselbe Datei erfolgreich sein.

Der CreateDisposition-Wert FILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Falls ja, wird diese Datei bei einem erfolgreichen Aufruf von FltCreateFileEx mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und dann neu erstellt. Dies bedeutet, dass die Datei geöffnet wurde, wenn die Datei bereits von einem anderen Thread geöffnet wurde, indem sie einen ShareAccess-Parameter mit festgelegtem FILE_SHARE_DELETE Flag angegeben hat. Beachten Sie, dass diese Art von Disposition mit dem POSIX-Stil des Überschreibens von Dateien konsistent ist.

Die CreateDisposition-Werte FILE_OVERWRITE_IF und FILE_SUPERSEDE sind ähnlich. Wenn FltCreateFileEx mit einer vorhandenen Datei und einem dieser CreateDisposition-Werte aufgerufen wird, wird die Datei ersetzt.

Das Überschreiben einer Datei entspricht semantisch einem Ablösungsvorgang, mit Ausnahme von Folgenden:

Der Aufrufer muss über Schreibzugriff auf die Datei verfügen, anstatt den Zugriff zu löschen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei mit dem in der ShareAccess-Eingabe festgelegten FILE_SHARE_WRITE-Flag geöffnet wurde.
Die angegebenen Dateiattribute werden logisch mit denen, die sich bereits in der Datei befinden, aufgehoben. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, ein nachfolgender Aufrufer von FltCreateFileEx vorhandene FileAttributes-Flags nicht deaktivieren kann, sondern zusätzliche Flags für dieselbe Datei aktivieren kann. Beachten Sie, dass diese Art des Überschreibens von Dateien mit MS-DOS, Windows 3.1 und OS/2 konsistent ist.

Der Wert createOptions FILE_DIRECTORY_FILE gibt an, dass die zu erstellende oder zu öffnende Datei eine Verzeichnisdatei ist. Wenn eine Verzeichnisdatei erstellt wird, erstellt das Dateisystem eine geeignete Struktur auf dem Datenträger, um ein leeres Verzeichnis für die Struktur auf dem Datenträger dieses bestimmten Dateisystems darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist oder wenn der Aufrufer einen inkonsistenten CreateOptions - oder CreateDisposition-Wert angegeben hat, schlägt der Aufruf von FltCreateFileEx fehl.

Das Flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING verhindert, dass das Dateisystem im Namen des Aufrufers Zwischenpufferungen ausführt. Die Angabe dieses Werts setzt bestimmte Einschränkungen für die Parameter des Aufrufers auf andere Flt.. Dateiroutinen oder Zw.. Dateiroutinen , einschließlich der folgenden:

Jeder Byteoffsetwert , der an FltReadFile, ZwReadFile, FltWriteFile oder ZwWriteFile übergeben wird, muss ein Vielfaches der Sektorgröße aufweisen.
Die anFltReadFile, ZwReadFile, FltWriteFile oder ZwWriteFile übergebene Länge muss ein Vielfaches der Sektorgröße sein. Beachten Sie, dass die Angabe eines Lesevorgangs für einen Puffer, dessen Länge genau der Sektorgröße entspricht, dazu führen kann, dass weniger signifikante Bytes an diesen Puffer übertragen werden, wenn das Ende der Datei während der Übertragung erreicht wurde.
Puffer müssen entsprechend der Ausrichtungsanforderung des zugrunde liegenden Speichergeräts ausgerichtet werden. Diese Informationen können abgerufen werden, indem Sie FltCreateFileEx aufrufen, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und dann ZwQueryInformationFile mit diesem Handle aufrufen, wobei FileAlignmentInformation als FileInformationClass angegeben wird. Weitere Informationen zu den System FILE_XXX_ALIGNMENT-Werten, die in ntifs.h definiert sind, finden Sie unter DEVICE_OBJECT und Initialisieren eines Geräteobjekts.
Aufrufe von FltSetInformationFile oder ZwSetInformationFile mit dem FileInformationClass-Parameter , der auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Vielfaches der Sektorgröße ist.

Die CreateOptions-FILE_SYNCHRONOUS_IO_ALERT und FILE_SYNCHRONOUS_IO_NONALERT, die sich gegenseitig ausschließen, wie ihre Namen vermuten lassen, geben an, dass die Datei für synchrone E/A-Vorgänge geöffnet wird. Dies bedeutet, dass alle E/A-Vorgänge für die Datei synchron sein müssen, solange sie über das Dateiobjekt erfolgen, auf das das zurückgegebene FileHandle verweist. Alle E/A-Vorgänge in einer solchen Datei werden über alle Threads serialisiert, indem das zurückgegebene Handle verwendet wird. Wenn eine dieser CreateOptions festgelegt ist , behält der E/A-Manager den aktuellen Dateipositionsoffset im CurrentByteOffset-Feld des Dateiobjekts bei. Dieser Offset kann in Aufrufen von ZwReadFile und ZwWriteFile verwendet werden. Sie kann auch abgefragt oder festgelegt werden, indem Sie ZwQueryInformationFile oder ZwSetInformationFile aufrufen.

Wenn das Flag CreateOptions FILE_OPEN_REPARSE_POINT nicht angegeben ist und FltCreateFileEx versucht, eine Datei mit einem Analysepunkt zu öffnen, erfolgt die normale Analysepunktverarbeitung für die Datei. Wenn dagegen das flag FILE_OPEN_REPARSE_POINT angegeben wird, erfolgt keine normale Analyseverarbeitung, und FltCreateFileEx versucht, die Analysepunktdatei direkt zu öffnen. In beiden Fällen gibt FltCreateFileEx STATUS_SUCCESS zurück, wenn der Öffnenvorgang erfolgreich war. Andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. FltCreateFileEx gibt nie STATUS_REPARSE zurück.

Das Flag CreateOptions FILE_OPEN_REQUIRING_OPLOCK entfernt die Zeit zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der es einem Drittanbieter möglicherweise ermöglichen könnte, die Datei zu öffnen und einen Freigabeverstoß zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag auf FltCreateFileEx verwenden und dann einen beliebigen Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die einen Verstoß gegen die Freigabe verursacht.

Wenn in Windows 7 andere Handles für die Datei vorhanden sind, wenn eine Anwendung das flag FILE_OPEN_REQUIRING_OPLOCK verwendet, schlägt der Erstellungsvorgang mit STATUS_OPLOCK_NOT_GRANTED fehl. Diese Einschränkung ist ab Windows 8 nicht mehr vorhanden.

Wenn dieser Erstellungsvorgang einen oplock unterbrechen würde, der bereits für die Datei vorhanden ist, führt das Festlegen des FILE_OPEN_REQUIRING_OPLOCK-Flags dazu, dass der Erstellungsvorgang mit STATUS_CANNOT_BREAK_OPLOCK fehlschlägt. Der vorhandene Oplock wird durch diesen Erstellungsvorgang nicht unterbrochen.

Eine Anwendung, die dieses Flag verwendet, muss einen Oplock anfordern, nachdem dieser Aufruf erfolgreich war, oder alle späteren Versuche, die Datei zu öffnen, werden ohne den Vorteil der typischen Oplockverarbeitung blockiert. Wenn dieser Aufruf erfolgreich ist, aber die spätere oplock-Anforderung fehlschlägt, muss eine Anwendung, die dieses Flag verwendet, ihr Handle schließen, nachdem sie erkannt hat, dass die Oplock-Anforderung fehlgeschlagen ist.

Hinweis

Das flag FILE_OPEN_REQUIRING_OPLOCK ist unter Windows 7, Windows Server 2008 R2 und höher unter Windows verfügbar. Die Microsoft-Dateisysteme, die dieses Flag in Windows 7 implementieren, sind NTFS, FAT und exFAT.

Das CreateOptions-Flag FILE_RESERVE_OPFILTER ermöglicht es einer Anwendung, einen Oplock der Ebene 1, batch oder filter anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. FILE_RESERVE_OPFILTER ist jedoch nur für Filter oplocks praktisch nützlich. Um es verwenden zu können, müssen Sie die folgenden Schritte ausführen:

Stellen Sie eine Create-Anforderung mit CreateOptions von FILE_RESERVE_OPFILTER, DesiredAccess von genau FILE_READ_ATTRIBUTES und ShareAccess von genau FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTED fehl, und auch der nächste angeforderte Oplock schlägt fehl.
- Wenn Sie mit mehr Zugriff oder weniger Freigabe öffnen, tritt auch ein Fehler von STATUS_OPLOCK_NOT_GRANTED auf.
Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie einen Oplock an.
Öffnen Sie ein weiteres Handle für die Datei, um E/A-Vorgänge zu erledigen.

Schritt 3 macht dies nur für Filter oplocks praktisch. Das in Schritt 3 geöffnete Handle kann einen DesiredAccess-Wert aufweisen, der maximal FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONISIEREN | READ_CONTROL einen Filter oplock nicht zu unterbrechen. Ein DesiredAccess-Wert größer als FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE unterbricht einen Oplock der Ebene 1 oder batch und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen unbrauchbar.

NTFS ist das einzige Microsoft-Dateisystem, das FILE_RESERVE_OPFILTER implementiert.

Minifiltertreiber müssen FltSetInformationFile und nicht ZwSetInformationFile verwenden, um eine Datei umzubenennen.

Hinweis

Wenn Sie versuchen, ein Volume zu öffnen, aber nur eine Kombination der folgenden Flags für den DesiredAccess-Parameter angeben, öffnet FltCreateFileEx2 unabhängig vom Dateisystem ein Handle, das direkten Zugriff auf das Speichergerät für das Volume hat.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

Sie dürfen FltCreateFileEx nicht verwenden, um ein Handle mit direktem Zugriff auf das Speichergerät für das Volume zu öffnen, da sonst Systemressourcen verloren gehen. Wenn Sie ein Handle mit direktem Zugriff auf ein Speichergerät öffnen möchten, rufen Sie stattdessen die Funktion IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint oder ZwCreateFile auf .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 Updaterollup 1 für SP4, Windows XP SP3, Windows Server 2003 SP1 und höheren Versionen des Windows-Betriebssystems.
Zielplattform	Universell
Header	fltkernel.h (fltKernel.h einschließen)
Bibliothek	Fltmgr.lib
IRQL	PASSIVE_LEVEL