IoCancelFileOpen-Funktion (ntddk.h)

Artikel
08/07/2023

Die IoCancelFileOpen-Routine kann von einem Dateisystemfiltertreiber verwendet werden, um eine Datei zu schließen, die von einem Dateisystemtreiber im Gerätestapel des Filtertreibers geöffnet wurde.

Syntax

void IoCancelFileOpen(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PFILE_OBJECT   FileObject
);

Parameter

[in] DeviceObject

Zeiger auf den oberen Rand des Gerätestapels direkt unterhalb des Geräteobjekts des Filtertreibers.

[in] FileObject

Zeiger auf das Dateiobjekt für die zu schließende Datei.

Rückgabewert

Keine

Bemerkungen

Wenn ein Dateisystemfiltertreiber feststellt, dass eine Datei öffnen- oder Dateierstellungsanforderung fehlschlagen muss, nachdem die Treiber auf niedrigerer Ebene die Anforderung bereits mit STATUS_SUCCESS abgeschlossen haben, kann ioCancelFileOpen verwendet werden, um die datei zu schließen, die von den Treibern der niedrigeren Ebene geöffnet wurde.

Obwohl STATUS_REPARSE ein erfolgreicher NTSTATUS-Wert ist, ist es nicht erforderlich, IoCancelFileOpen für einen Erstellungsvorgang aufzurufen, der mit STATUS_REPARSE abgeschlossen wurde, da dieser status Wert angibt, dass die Datei nicht erfolgreich geöffnet wurde.

Ein erfolgreicher Aufruf von IoCancelFileOpen hat die folgende Auswirkung: Bei Minifiltern und Legacyfiltern, die sich über dem Aufrufer im Dateisystemstapel befinden, scheint die Erstellungsanforderung fehlgeschlagen zu sein. Für diejenigen, die sich unterhalb des Aufrufers befinden, scheint die Datei geöffnet (oder erstellt) und dann geschlossen zu sein.

Beachten Sie, dass IoCancelFileOpen keine Änderungen an der Datei rückgängig macht. IoCancelFileOpen löscht beispielsweise keine neu erstellte Datei oder stellt keine Datei wieder her, die überschrieben oder in ihren vorherigen Zustand ersetzt wurde.

Ein typisches Beispiel ist wie folgt:

Ein Filtertreiber ist zwischen einem Filtertreiber auf höherer Ebene und einem Dateisystemtreiber auf niedrigerer Ebene vorhanden.
Der Filtertreiber übergibt eine IRP_MJ_CREATE Anforderung im Gerätestapel an den Dateisystemtreiber, und der Dateisystemtreiber schließt die IRP_MJ_CREATE-Anforderung mit status STATUS_SUCCESS ab.
Bevor der Filtertreiber die Erstellungsanforderung abschließt, bestimmt er, dass die Datei geschlossen werden muss.
Der Filtertreiber verwendet IoCancelFileOpen , um die Datei zu schließen, die vom Dateisystemtreiber geöffnet wurde.

Nach dem Aufrufen von IoCancelFileOpen sollte der Filtertreiber die Erstellungsanforderung mit einem entsprechenden Fehlercode abschließen, z. B. STATUS_UNSUCCESSFUL oder STATUS_ACCESS_DENIED. Darüber hinaus sollte das Feld Irp-IoStatus.Information> auf 0 (null) festgelegt werden.

IoCancelFileOpen muss aufgerufen werden, bevor Handles für die Datei erstellt werden. Aufrufer können den Flags-Member der FILE_OBJECT Struktur überprüfen, auf die der FileObject-Parameter verweist. Wenn das FO_HANDLE_CREATED-Flag festgelegt ist, bedeutet dies, dass ein oder mehrere Handles für die Datei erstellt wurden, sodass es nicht sicher ist , IoCancelFileOpen aufzurufen.

IoCancelFileOpen legt das FO_FILE_OPEN_CANCELLED-Flag im Flags-Element des Dateiobjekts fest, auf das FileObject verweist. Dieses Flag gibt an, dass die IRP_MJ_CREATE-Anforderung abgebrochen wurde und eine IRP_MJ_CLOSE Anforderung für dieses Dateiobjekt ausgegeben wird. Nachdem der Erstellungsvorgang abgebrochen wurde, kann er nicht erneut ausgestellt werden, d. h. STATUS_REPARSE kann vom Legacyfiltertreiber nicht zurückgegeben werden, wenn er die IoCreateFileOpen-Routine aufgerufen hat.

Minifilter sollten FltCancelFileOpen anstelle von IoCancelFileOpen verwenden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Diese Routine ist unter Microsoft Windows 2000 und höher verfügbar.
Zielplattform	Universell
Header	ntddk.h (include Ntddk.h, Ntifs.h, Fltkernel.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL