IRP_MJ_CREATE (FS- und FS-Filter)

Artikel
03/14/2023

Sendebedingungen

Der E/A-Manager sendet eine IRP_MJ_CREATE Anforderung, wenn:

Eine neue Datei oder ein neues Verzeichnis wird erstellt.
Eine vorhandene Datei, ein Gerät, ein Verzeichnis oder volume wird geöffnet.

Normalerweise wird diese IRP im Namen einer Benutzermodusanwendung gesendet, die eine Microsoft Win32-Funktion wie CreateFile aufgerufen hat, oder im Namen einer Kernelmoduskomponente, die eine Funktion wie IoCreateFile, IoCreateFileSpecifyDeviceObjectHint, ZwCreateFile oder ZwOpenFile aufgerufen hat.

Wenn die Erstellungsanforderung erfolgreich abgeschlossen wurde, erhält die Anwendung oder Kernelmoduskomponente ein Handle für das Dateiobjekt.

Vorgang: Dateisystemtreiber

Wenn das Zielgerätobjekt das Steuerungsgerätobjekt des Dateisystems ist, muss die Dispatchroutine des Dateisystemtreibers die IRP abschließen und einen entsprechenden NTSTATUS-Wert zurückgeben, nachdem Irp-IoStatus.Status> und Irp-IoStatus.Information> auf entsprechende Werte festgelegt wurden.

Andernfalls sollte der Dateisystemtreiber die Erstellungsanforderung verarbeiten.

Vorgang: Legacy-Dateisystemfiltertreiber

Wenn das Zielgerätobjekt das Objekt des Kontrollgeräts des Filtertreibers ist, muss die Dispatchroutine des Filtertreibers die IRP abschließen und einen entsprechenden NTSTATUS-Wert zurückgeben, nachdemIrp-IoStatus.Status> und Irp-IoStatus.Information> auf entsprechende Werte festgelegt wurden.

Andernfalls sollte der Filtertreiber die erforderliche Verarbeitung ausführen. Je nach Art des Filters sollte er dann entweder den IRP abschließen oder an den nächstniedrigen Treiber im Stapel übergeben.

In der Regel sollten Filtertreiber als Reaktion auf IRP_MJ_CREATE keine STATUS_PENDING zurückgeben. Wenn jedoch ein Treiber auf niedrigerer Ebene STATUS_PENDING zurückgibt, sollte der Filtertreiber diesen status Wert in der Treiberkette übergeben.

Dateisystemfiltertreiber-Autoren sollten beachten, dass IoCreateStreamFileObject bewirkt, dass eine IRP_MJ_CLEANUP Anforderung an den Dateisystemtreiberstapel für das Volume gesendet wird. Da Dateisysteme häufig Streamdateiobjekte als Nebeneffekt anderer Vorgänge als IRP_MJ_CREATE erstellen, ist es für Filtertreiber schwierig, die Erstellung von Streamdateiobjekten zuverlässig zu erkennen. Daher sollte ein Filtertreiber erwarten, dass er IRP_MJ_CLEANUP und IRP_MJ_CLOSE Anforderungen für zuvor nicht angezeigte Dateiobjekte empfängt. Für IoCreateStreamFileObjectLite wird keine IRP_MJ_CLEANUP Anforderung gesendet.

Wenn Legacyfiltertreiber eine Create-Anforderung in einem Rückruf nach der Erstellung erneut ausstellen, müssen sie den Puffer freigeben und auf NULL festlegen, der ihrem Analysepunkt (dem Hilfspuffer) zugeordnet ist. Wenn ein Legacyfiltertreiber diesen Puffer nicht freigibt und ihn auf NULL legt, wird der Speicher des Treibers verloren. Minifiltertreiber müssen dies nicht tun, da der Filter-Manager dies für sie übernimmt.

Parameter

Ein Dateisystem- oder Legacyfiltertreiber ruft IoGetCurrentIrpStackLocation mit dem angegebenen IRP auf, um einen Zeiger auf den eigenen Stapelspeicherort im IRP abzurufen. In den folgenden Parametern zeigt Irp auf den IRP und IrpSp auf den IO_STACK_LOCATION. Der Treiber kann die Informationen verwenden, die in den folgenden Elementen des IRP- und des IRP-Stapelspeicherorts festgelegt sind, um eine Erstellungsanforderung zu verarbeiten.

DeviceObject ist ein Zeiger auf das Zielgerätobjekt.
Irp->AssociatedIrp.SystemBuffer verweist auf einen FILE_FULL_EA_INFORMATION strukturierten Puffer, wenn das Dateiobjekt eine Datei mit erweiterten Attributen darstellt. Andernfalls ist dieses Element auf NULL festgelegt.
Irp->Flags ist für diese Anforderung auf die folgenden Flags festgelegt:
- IRP_CREATE_OPERATION
- IRP_DEFER_IO_COMPLETION
- IRP_SYNCHRONOUS_API
Irp->RequestorMode gibt den Ausführungsmodus des Prozesses an, der den Vorgang angefordert hat, entweder KernelMode oder UserMode. Wenn das flag SL_FORCE_ACCESS_CHECK festgelegt ist, müssen Zugriffsprüfungen durchgeführt werden, auch wenn Irp-RequestorMode>KernelMode ist.
Irp->IoStatus verweist auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum angeforderten Vorgang empfängt. Das Dateisystem legt den Informationselement dieser Struktur auf einen der folgenden Werte fest:
- FILE_CREATED
- FILE_DOES_NOT_EXIST
- FILE_EXISTS
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
Irp->Overlay.AllocationSize ist die anfängliche Zuordnungsgröße in Bytes für die Datei. Ein Wert ohne Zero hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder ersetzt.
IrpSp->FileObject verweist auf ein Dateiobjekt, das der E/A-Manager erstellt, um die zu erstellende oder zu öffnende Datei darzustellen. Wenn das Dateisystem die IRP_MJ_CREATE-Anforderung verarbeitet, legt es die Felder FsContext und möglicherweise FsContext2 in diesem Dateiobjekt auf Werte fest, die dateisystemspezifisch sind. Daher können die Werte der Felder FsContext und FsContext2 erst als gültig betrachtet werden, nachdem das Dateisystem die Erstellungsanforderung verarbeitet hat. Weitere Informationen finden Sie unter Dateistreams, Streamkontexte und Per-Stream Kontexte.

FltCancelFileOpen und IoCancelFileOpen legen das FO_FILE_OPEN_CANCELLED-Flag im Feld Flags des Dateiobjekts fest. Das Festlegen dieses Flags gibt an, dass die IRP_MJ_CREATE Anforderung abgebrochen wurde, und eine IRP_MJ_CLOSE Anforderung für dieses Dateiobjekt ausgestellt wird. Nachdem die Erstellungsanforderung abgebrochen wurde, kann sie nicht erneut ausgestellt werden.

Der Parameter IrpSp-FileObject> enthält einen Zeiger auf das Feld RelatedFileObject, das ebenfalls eine FILE_OBJECT-Struktur ist. Das Feld RelatedFileObject einer FILE_OBJECT-Struktur wird verwendet, um anzugeben, dass eine bestimmte Datei relativ zu einem bereits geöffneten Dateiobjekt geöffnet wurde. Dies gibt normalerweise an, dass es sich bei der relativen Datei um ein Verzeichnis handelt, aber streambasierte Dateien möglicherweise relativ zu einem bereits vorhandenen Datenstrom einer Datei geöffnet werden. Das Feld RelatedFileObject der FILE_OBJECT-Struktur ist nur während der Verarbeitung von IRP_MJ_CREATE gültig.

IrpSp->Flags können auf einen oder mehrere der folgenden Werte festgelegt werden:

Flag	Bedeutung
SL_FORCE_ACCESS_CHECK 0x01	Wenn dieses Flag festgelegt ist, müssen Zugriffsprüfungen auch dann durchgeführt werden, wenn der Wert von IRP-RequestorMode>KernelMode ist.
SL_OPEN_PAGING_FILE 0x02	Wenn dieses Flag festgelegt ist, handelt es sich bei der Datei um eine Auslagerungsdatei.
SL_OPEN_TARGET_DIRECTORY 0x04	Wenn dieses Flag festgelegt ist, sollte das übergeordnete Verzeichnis der Datei geöffnet werden.
SL_STOP_ON_SYMLINK 0x08	Wenn dieses Flag festgelegt ist, wird die automatische Durchquerung von Verbindungen und symbolischen Verknüpfungen im E/A-Manager unterdrückt, sodass das Öffnen von Verbindungen und symbolischen Links STATUS_REPARSE zurückgibt.
SL_IGNORE_READONLY_ATTRIBUTE 0x40	Wenn dieses Flag festgelegt ist, ermöglicht es die Erstellung einer schreibgeschützten Datei mit der Option FILE_DELETE_ON_CLOSE. Diese Option bewirkt, dass die Datei gelöscht wird, wenn das Handle geschlossen wird.
SL_CASE_SENSITIVE 0x80	Wenn festgelegt, sollte bei Dateinamenvergleichen die Groß-/Kleinschreibung beachtet werden.

IrpSp->MajorFunction ist auf IRP_MJ_CREATE festgelegt.
IrpSp->Parameters.Create.EaLength ist die Größe des Puffers in Bytes bei Irp-AssociatedIrp.SystemBuffer>. Wenn der Wert von Irp*->AssociatedIrp.SystemBufferNULL ist, muss dieser Member 0 sein.
IrpSp->Parameters.Create.FileAttributes ist eine Bitmaske von Attributflags, die beim Erstellen oder Öffnen der Datei angewendet werden sollen. Explizit angegebene Attribute werden nur angewendet, wenn die Datei erstellt, ersetzt oder in einigen Fällen überschrieben wird. Standardmäßig ist dieser Wert FILE_ATTRIBUTE_NORMAL, den jede andere Flag- oder OR'd-Kombination kompatibler Flags außer Kraft setzen kann. Dieses Element entspricht dem FileAttributes-ParameterioCreateFileSpecifyDeviceObjectHint.
IrpSp->Parameters.Create.Options ist eine Bitmaske von Flags, die die Optionen angeben, die beim Erstellen oder Öffnen der Datei angewendet werden sollen, und die Aktion, die ausgeführt werden soll, wenn die Datei bereits vorhanden ist.

Die hohen 8 Bits dieses Parameters entsprechen dem Disposition-Parameter zu IoCreateFileSpecifyDeviceObjectHint.

Die niedrigen 24 Bits dieses Members entsprechen dem CreateOptions-ParameterioCreateFileSpecifyDeviceObjectHint. Dateisystemfilter- und Minifiltertreiber, die Dateiüberprüfungen durchführen (z. B. Antivirenprogramme), sollten besonders auf das flag FILE_COMPLETE_IF_OPLOCKED achten. Wenn dieses Flag festgelegt ist, darf der Filter den IRP_MJ_CREATE Vorgang nicht blockieren oder anderweitig verzögern.

Wenn das FILE_COMPLETE_IF_OPLOCKED-Flag im Pfad vor dem Erstellen (Erstellen der Versendung) festgelegt ist, darf der Filter keine der folgenden Arten von Vorgängen initiieren, da sie oplock-Unterbrechungen verursachen können:
- IRP_MJ_CLEANUP
- IRP_MJ_CREATE
- IRP_MJ_FILE_SYSTEM_CONTROL
- IRP_MJ_FLUSH_BUFFERS
- IRP_MJ_LOCK_CONTROL
- IRP_MJ_READ
- IRP_MJ_SET_INFORMATION
- IRP_MJ_WRITE
Wenn ein Filter oder Minifilter das FILE_COMPLETE_IF_OPLOCKED-Flag nicht einhalten kann, muss er die IRP_MJ_CREATE Anforderung mit STATUS_SHARING_VIOLATION abschließen.

Wenn das FILE_COMPLETE_IF_OPLOCKED-Flag im Vervollständigungspfad (nach der Erstellung) festgelegt ist, sollte der Filter überprüfen, ob das Dateisystem Irp-IoStatus.Status> auf den STATUS_OPLOCK_BREAK_IN_PROGRESS status-Wert festgelegt hat. Wenn dieser status Wert nicht festgelegt ist, ist es sicher, dass der Filter einen der oben genannten Vorgänge für die Datei initiiert. Wenn dieser status Wert festgelegt ist, wurde der Oplock noch nicht unterbrochen, und der Filter darf keinen Vorgang initiieren, der zu einem Oplockbruch führen kann. Daher muss der Filter alle oben genannten Vorgänge für die Datei verschieben, bis eine der folgenden Bedingungen zutrifft:
- Der Besitzer des Oplock sendet eine FSCTL_OPLOCK_BREAK_ACKNOWLEDGE-Anforderung an das Dateisystem.
- Eine andere Systemkomponente als der Filter oder Minifilter sendet dem Dateisystem eine E/A-Anforderung, die warten muss, bis die Oplockunterbrechung abgeschlossen ist (z. B. IRP_MJ_READ oder IRP_MJ_WRITE). Der Filter oder Minifilter kann einen der oben genannten Vorgänge aus seiner Dispatchroutine (oder dem Präoperationsrückruf) für diesen neuen Vorgang initiieren, da die Dispatch- oder Preoperation-Rückrufroutine in einen Wartezustand versetzt wird, bis der Oplock-Umbruch abgeschlossen ist.
*IrpSp->Parameters.Create.SecurityContext-AccessState> verweist auf eine ACCESS_STATE-Struktur, die den Betreffkontext des Objekts, gewährte Zugriffstypen und die verbleibenden gewünschten Zugriffstypen enthält.
IrpSp->Parameters.Create.SecurityContext-DesiredAccess> ist eine ACCESS_MASK Struktur, die die für die Datei angeforderten Zugriffsrechte angibt. Weitere Informationen finden Sie in der Beschreibung des DesiredAccess-Parameters für IoCreateFileSpecifyDeviceObjectHint.
IrpSp->Parameters.Create.ShareAccess ist eine Bitmaske von Freigabezugriffsrechten, die für die Datei angefordert werden. Wenn dieser Member null ist, wird exklusiver Zugriff angefordert. Weitere Informationen finden Sie in der Beschreibung des ShareAccess-Parameters für IoCreateFileSpecifyDeviceObjectHint.