FltCreateFile-Funktion (fltkernel.h)

Artikel
08/07/2023

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

Syntax

NTSTATUS FLTAPI FltCreateFile(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [out]          PHANDLE            FileHandle,
  [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 zugewiesene Variable, die das Dateihandle empfängt, wenn der Aufruf von FltCreateFile erfolgreich ist.

[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 zu diesem Parameter finden Sie im 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

FltCreateFile 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

FltCreateFile 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 tritt nur auf, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während FltCreateFile versucht, diese Situation zu behandeln.

Hinweise

In Früheren Versionen von Windows als Microsoft Windows Update Rollup für Windows 2000 SP4 und Windows Server 2003 SP1 sollten Minifiltertreiber FltCreateFile anstelle von IoCreateFile, IoCreateFileSpecifyDeviceObjectHint oder ZwCreateFile aufrufen, um ein Dateihandle zur Verwendung mit ZwXxx-E/A-Routinen wie ZwReadFile und ZwQueryInformationFile abzurufen.

Unter Microsoft Windows Update Rollup für Windows 2000 SP4, Windows Server 2003 SP1 und höher können Minifiltertreiber FltCreateFileEx verwenden, um einen Dateiobjektzeiger für die Verwendung mit FltXxxFile-Routinen wie FltReadFile und FltWriteFile abzurufen. In früheren Versionen von Windows kann das aus FltCreateFile abgerufene Handle in einen Dateiobjektzeiger konvertiert werden, indem ObReferenceObjectByHandle wie folgt aufgerufen wird:

status = ObReferenceObjectByHandle(
           handle,                 //Handle
           0,                      //DesiredAccess
           NULL,                   //ObjectType
           KernelMode,             //AccessMode
           &handleFileObject,      //Object
           NULL);                  //HandleInformation</pre>

FltCreateFile 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 FltCreateFile 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 Handle, das von FltCreateFile abgerufen wird, muss schließlich durch Aufrufen von FltClose freigegeben werden.

Treiberroutinen, die nicht im Systemprozesskontext ausgeführt werden, müssen das attribut OBJ_KERNEL_HANDLE für den ObjectAttributes-Parameter von FltCreateFile festlegen. Das Festlegen dieses Attributs schränkt die Verwendung des von FltCreateFile 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.

Rufen Sie diese Routine nicht auf, wenn APCs deaktiviert sind (ein ausstehendes FsRtlEnterFileSystem oder KeEnterCriticalRegion, da dies zu einem Thread-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 FltCreateFile 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 fltCreateFile für eine bestimmte Datei angegeben ist, darf keinen Konflikt mit den Zugriffen führen, 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. Wenn ja, wird diese Datei bei einem erfolgreichen Aufruf von FltCreateFile 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 FltCreateFile 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 FltCreateFile 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 FltCreateFile fehl.

Das Flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING verhindert, dass das Dateisystem im Namen des Aufrufers Zwischenpufferungen ausführt. Wenn Sie diesen Wert angeben, werden bestimmte Einschränkungen für die Parameter des Aufrufers auf Zw. festgelegt. Dateiroutinen , einschließlich der folgenden:

Jeder Byteoffsetwert , der an ZwReadFile oder ZwWriteFile übergeben wird, muss ein Vielfaches der Sektorgröße sein.
Die anZwReadFile 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 FltCreateFile 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 ZwSetInformationFile , bei denen der FileInformationClass-Parameter 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 mithilfe des zurückgegebenen Handles über alle Threads serialisiert. Wenn eines dieser CreateOptions-Elemente festgelegt ist, behält der E/A-Manager den aktuellen Dateipositionsoffset im Feld CurrentByteOffset 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 FltCreateFile versucht, eine Datei mit einem Analysepunkt zu öffnen, erfolgt die normale Analysepunktverarbeitung für die Datei. Wenn hingegen das Flag FILE_OPEN_REPARSE_POINT angegeben ist, wird die normale Analyseverarbeitung nicht ausgeführt, und FltCreateFile versucht, die Analysepunktdatei direkt zu öffnen. In beiden Fällen gibt FltCreateFile STATUS_SUCCESS zurück, wenn der geöffnete Vorgang erfolgreich war. Andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. FltCreateFile gibt nie STATUS_REPARSE zurück.

Das Flag CreateOptions FILE_OPEN_REQUIRING_OPLOCK beseitigt die Zeit zwischen dem Öffnen der Datei und der Anforderung eines Oplocks, der es einem Drittanbieter möglicherweise ermöglichen könnte, die Datei zu öffnen und eine Freigabeverletzung zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag für FltCreateFile verwenden und dann einen beliebigen Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die eine Freigabeverletzung 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 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 einen Oplock anfordern, nachdem dieser Aufruf erfolgreich war, sonst werden alle späteren Versuche, die Datei zu öffnen, ohne den Vorteil der typischen Oplock-Verarbeitung 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 bei der oplock-Anforderung ein Fehler aufgetreten ist.

Hinweis

Das FILE_OPEN_REQUIRING_OPLOCK-Flag ist unter Windows 7, Windows Server 2008 R2 und höheren Windows-Betriebssystemen 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 zu verwenden, 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 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 der 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 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 und trotzdem keinen Filter oplock unterbrechen. Ein DesiredAccess 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 nutzlos.

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 FltCreateFile 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 FltCreateFile 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)	Windows 2000 Updaterollup 1 für SP4, Windows XP SP2, Windows Server 2003 SP1
Zielplattform	Universell
Header	fltkernel.h (include FltKernel.h)
Bibliothek	Fltmgr.lib
IRQL	PASSIVE_LEVEL