FltCreateFileEx-Funktion (fltkernel.h)

Artikel
02/06/2025

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 undurchsichtiger Instanzzeiger für die Minifiltertreiberinstanz, an die die Erstellungsanforderung gesendet werden soll. Die Instanz muss an das Volume angefügt werden, in dem sich die Datei oder das Verzeichnis befindet. Dieser Parameter ist optional und kann NULL-werden. Wenn dieser Parameter NULL-ist, wird die Anforderung am oberen Rand des Dateisystemtreiberstapels für das Volume an das Geräteobjekt gesendet. Wenn es nichtNULL-ist, wird die Anforderung nur an Minifiltertreiberinstanzen gesendet, die unterhalb der angegebenen Instanz angefügt sind.

[out] FileHandle

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

[out] FileObject

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

[in] DesiredAccess

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

[in] ObjectAttributes

Zeiger auf eine undurchsichtige OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributesinitialisiert wurde. Weitere Informationen und eine Beschreibung jedes Strukturelements finden Sie im ObjectAttributes Parameter von IoCreateFileEx.

[out] IoStatusBlock

Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Siehe den IoStatusBlock Parameter von IoCreateFileEx.

[in, optional] AllocationSize

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

[in] FileAttributes

Gibt ein oder mehrere FILE_ATTRIBUTE_XXX- Flags an, die die festzulegenden Dateiattribute darstellen, wenn Sie eine Datei erstellen, ersetzen oder überschreiben. Weitere Details und die Liste der Flags finden Sie im FileAttributes Parameter von IoCreateFileEx.

[in] ShareAccess

Gibt den Typ des Freigabezugriffs auf die Datei an, die der Aufrufer als Null oder 1 oder eine Kombination der Flags benötigt. Weitere Details und die 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. Die 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 im CreateOptions Parameter von IoCreateFileExaufgeführten und beschriebenen Flags.

[in, optional] EaBuffer

Ein Zeiger auf einen vom Aufrufer bereitgestellten FILE_FULL_EA_INFORMATION-strukturierten Puffer, der informationen zum erweiterten Attribut (EXTENDED Attribute, EA) enthält, die auf die Datei angewendet werden sollen.

[in] EaLength

Länge in Byte von EaBuffer.

[in] Flags

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

Rückgabewert

FltCreateFileEx gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück. Eine Liste möglicher Rückgabecodes finden Sie im Abschnitt RückgabewertIoCreateFileEx.

Anmerkung

FltCreateFileEx- kann STATUS_FILE_LOCK_CONFLICT als Rückgabewert oder im Status Member der IO_STATUS_BLOCK Struktur zurückgeben, auf die der IoStatusBlock-Parameter verweist. Dies tritt nur auf, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während FltCreateFileEx- versucht, diese Situation zu behandeln.

Bemerkungen

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

FltCreateFileEx sendet die Erstellungsanforderung nur an die Instanzen, die unterhalb der angegebenen Minifiltertreiberinstanz und an das Dateisystem angefügt sind. Die angegebene Instanz und die oben angefügten Instanzen erhalten nicht die Erstellungsanforderung. Wenn keine Instanz angegeben ist, wechselt die Anforderung an den Anfang des Stapels und wird von allen Instanzen und dem Dateisystem empfangen.

Es gibt zwei alternative Möglichkeiten, den Namen der zu erstellenden oder geöffneten Datei mit FltCreateFileExanzugeben:

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

Alle FileHandle-, die von FltCreateFileEx abgerufen werden, müssen schließlich durch Aufrufen von FltClosefreigegeben werden. Darüber hinaus muss jeder zurückgegebene FileObject Zeiger abgeleitet werden, wenn er nicht mehr benötigt wird, indem ObDereferenceObjectaufgerufen wird.

Treiberroutinen, die nicht im Systemprozesskontext ausgeführt werden, müssen das OBJ_KERNEL_HANDLE-Attribut für den parameter ObjectAttributes Parameter von FltCreateFileExfestlegen. Durch Festlegen dieses Attributs wird die Verwendung des Handles eingeschränkt, das von FltCreateFileEx auf Prozesse im Kernelmodus zurückgegeben wird. Andernfalls kann über den Prozess, in dem der Treiber ausgeführt wird, auf das Handle zugegriffen werden kann.

Anmerkung

Rufen Sie diese Routine nicht mit einem IRP-Wert auf nicht NULL auf, da dies zu einem System-Deadlock führen kann.

Bestimmte DesiredAccess Flags und Kombinationen von Flags haben folgende Auswirkungen:

Damit ein Aufrufer einen E/A-Abschluss synchronisiert, indem er auf die zurückgegebene FileHandle- auf den Signalstatus 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 bei Bedarf automatisch für diesen Schreibvorgangstyp erweitert.
Das Festlegen des FILE_WRITE_DATA Flags für eine Datei ermöglicht auch das Auftreten von Schreibvorgängen über das Ende der Datei hinaus. Die Datei wird für diesen Schreibtyp automatisch erweitert.
Wenn nur die FILE_EXECUTE- und SYNCHRONIZE-Flags festgelegt sind, kann der Aufrufer die zurückgegebene FileHandle- nicht verwenden, um daten direkt in oder aus der Datei zu lesen oder aus der Datei zu schreiben. Das heißt, alle Vorgänge in der Datei müssen system paging E/A verwenden, um Dateidaten zu lesen oder zu schreiben.

Der parameter ShareAccess bestimmt, ob separate Threads gleichzeitig auf dieselbe Datei zugreifen können. Wenn beide Dateiöffner über die Berechtigung verfügen, auf eine Datei auf die angegebene Weise zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von FltCreateFileEx nicht 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 dem ursprünglichen Aufrufer exklusiven Zugriff auf die Datei gewährt wird.

Damit eine freigegebene Datei erfolgreich geöffnet werden kann, muss die angeforderte DesiredAccess- mit der Datei kompatibel sein, sowohl mit der DesiredAccess als auch mit ShareAccess Spezifikationen aller vorherigen Öffnen, die noch nicht mit FltCloseveröffentlicht wurden. Das heißt, die DesiredAccess-, die 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.

Anmerkung

Wenn IO_IGNORE_SHARE_ACCESS_CHECK im parameter Flags angegeben wird, ignoriert der E/A-Manager den ShareAccess-Parameter. Das Dateisystem kann jedoch weiterhin Zugriffsprüfungen durchführen. Daher ist es wichtig, den Freigabemodus anzugeben, den Sie für den ShareAccess-parameter möchten, auch wenn Sie das IO_IGNORE_SHARE_ACCESS_CHECK-Flag verwenden. Beachten Sie außerdem, dass das Dateisystem, wenn IO_IGNORE_SHARE_ACCESS_CHECK angegeben wird, den gewünschten Zugriff oder den freigegebenen Zugriff des aktuellen Öffnens nicht nachverfolgt. Aus diesem Gründen können nachfolgende geöffnete Aufrufe für dieselbe Datei erfolgreich sein.

Der CreateDisposition Werts FILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Wenn ja, wird ein erfolgreicher Aufruf von FltCreateFileEx mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und anschließend neu erstellt. Dies bedeutet, dass die Datei, wenn die Datei bereits von einem anderen Thread geöffnet wurde, durch Angeben eines ShareAccess--Parameters mit dem FILE_SHARE_DELETE Flagsatz geöffnet wurde. Beachten Sie, dass diese Art von Löschung mit dem POSIX-Stil des Überschreibens von Dateien konsistent ist.

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

Das Überschreiben einer Datei entspricht semantisch einem Supersede-Vorgang, mit Ausnahme der folgenden Aktionen:

Der Aufrufer muss Schreibzugriff auf die Datei haben, anstatt den Zugriff zu löschen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei mit dem FILE_SHARE_WRITE Flag geöffnet wurde, das in der Eingabe ShareAccessfestgelegt ist.
Die angegebenen Dateiattribute werden logisch mit den bereits in der Datei gespeicherten Attributen versehen. Dies bedeutet, dass ein nachfolgender Aufrufer von FltCreateFileEx vorhandene FileAttributes Flags nicht deaktivieren kann, aber zusätzliche Flags für dieselbe Datei aktivieren kann, wenn die Datei bereits von einem anderen Thread geöffnet wurde. Beachten Sie, dass diese Art von Überschreiben 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 geöffnete 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 des jeweiligen Dateisystems auf dem Datenträger darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist oder wenn der Aufrufer eine inkonsistente CreateOptions oder CreateDisposition Wert angegeben hat, schlägt der Aufruf von FltCreateFileEx fehl.

Das CreateOptions FILE_NO_INTERMEDIATE_BUFFERING Flag verhindert, dass das Dateisystem im Auftrag des Aufrufers zwischenpuffert. Wenn Sie diesen Wert angeben, werden bestimmte Einschränkungen für die Parameter des Aufrufers auf andere Flt. Datei Routinen oder Zw.. Datei- Routinen, einschließlich der folgenden:

Ein Byte-Offset- Wert, der an FltReadFile, ZwReadFile, FltWriteFileoder ZwWriteFile übergeben wird, muss ein Vielfaches der Sektorgröße sein.
Die Length an FltReadFile, ZwReadFile, FltWriteFileoder ZwWriteFile muss ein Vielfaches der Sektorgröße sein. Beachten Sie, dass das Angeben eines Lesevorgangs für einen Puffer, dessen Länge genau die Sektorgröße ist, zu weniger signifikanten Bytes führen kann, die 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 durch Aufrufen von FltCreateFileEx abgerufen werden, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und dann ZwQueryInformationFile- mit diesem Handle aufrufen und FileAlignmentInformationInformation als FileInformationClassangeben. Weitere Informationen zum System FILE_XXX-_ALIGNMENT-Werten, die in ntifs.h definiert sind, finden Sie unter DEVICE_OBJECT und Initialisieren eines Device Object.
Aufrufe an FltSetInformationFile oder ZwSetInformationFile mit dem parameter FileInformationClass auf FilePositionInformationInformation muss 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 vorschlagen, geben an, dass die Datei für synchrone E/A geöffnet wird. Dies bedeutet, dass alle E/A-Vorgänge in der Datei synchron sein müssen, solange sie über das Dateiobjekt auftreten, auf das die 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. Mit einem dieser CreateOptions- festgelegt, verwaltet der E/A-Manager den aktuellen Dateipositionsoffset im CurrentByteOffset Feld des Dateiobjekts. Dieser Offset kann in Aufrufen von ZwReadFile- und ZwWriteFile-verwendet werden. Es kann auch abgefragt oder festgelegt werden, indem ZwQueryInformationFile oder ZwSetInformationFileaufgerufen wird.

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

Die CreateOptions- FILE_OPEN_REQUIRING_OPLOCK Flag beseitigt den Zeitraum zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der es einem Drittanbieter ermöglichen könnte, die Datei zu öffnen und einen Freigabeverstoß zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag für FltCreateFileEx- verwenden und dann oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die einen Freigabeverstoß verursacht.

Wenn in Windows 7 andere Handles in der Datei vorhanden sind, wenn eine Anwendung das FILE_OPEN_REQUIRING_OPLOCK Flag 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 unterbricht, der bereits in der 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 ein Oplock anfordern, nachdem dieser Aufruf erfolgreich war, oder alle späteren Versuche zum Öffnen der Datei werden blockiert, ohne dass die typische Oplock-Verarbeitung zu nutzen ist. Wenn dieser Aufruf erfolgreich ist, aber die spätere Oplock-Anforderung fehlschlägt, muss eine Anwendung, die dieses Flag verwendet, sein Handle schließen, nachdem erkannt wird, dass die Oplock-Anforderung fehlgeschlagen ist.

Anmerkung

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

Die CreateOptions Flag FILE_RESERVE_OPFILTER ermöglicht einer Anwendung das Anfordern eines Oplocks der Ebene 1, eines Batchs oder eines Filters, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. FILE_RESERVE_OPFILTER ist jedoch nur praktisch nützlich für Filter oplocks. Um sie zu verwenden, müssen Sie die folgenden Schritte ausführen:

Erstellen einer 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 das nächste angeforderte Oplock schlägt ebenfalls 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 ein Oplock an.
Öffnen Sie ein weiteres Handle für die Datei, um E/A zu erledigen.

Schritt 3 macht dies nur für Filter oplocks praktisch. Der 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 und trotzdem keinen Filter-Oplock aufheben. Alle DesiredAccess-Elemente, die größer als FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE unterbricht einen Oplock der Ebene 1 oder eines Batches und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen nutzlos.

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

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

Anmerkung

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

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONISIEREN

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

Anforderungen

Anforderung	Wert
mindestens unterstützte 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-	Universal
Header-	fltkernel.h (include FltKernel.h)
Library	Fltmgr.lib
IRQL-	PASSIVE_LEVEL