FltCancelFileOpen function (fltkernel.h)

Article
02/22/2024

A minifilter driver can use the FltCancelFileOpen routine to close a newly opened or created file.

Syntax

VOID FLTAPI FltCancelFileOpen(
  [in] PFLT_INSTANCE Instance,
  [in] PFILE_OBJECT  FileObject
);

Parameters

[in] Instance

Opaque instance pointer for the caller. This parameter is required and cannot be NULL.

[in] FileObject

File object pointer for the file. This parameter is required and cannot be NULL.

Return value

None

Remarks

If a minifilter driver determines that a file-open or file-create (IRP_MJ_CREATE) operation must fail after the file system has already completed the operation with a success NTSTATUS value such as STATUS_SUCCESS, the minifilter driver can call FltCancelFileOpen from its post-create callback routine to close the file.

Note Although STATUS_REPARSE is a success NTSTATUS value, it is not necessary to call FltCancelFileOpen for a create operation that was completed with STATUS_REPARSE, because this status value indicates that the file was not successfully opened.

A successful call to FltCancelFileOpen has the following effect: To minifilter drivers and legacy filters that are above the caller in the minifilter driver instance stack, the create request appears to have failed. To those that are below the caller, the file appears to have been opened (or created) and then closed.

Note that FltCancelFileOpen does not undo any modifications to the file. For example, FltCancelFileOpen does not delete a newly created file or restore a file that was overwritten or superseded to its previous state.

FltCancelFileOpen must be called before any handles are created for the file. Callers can check the Flags member of the FILE_OBJECT structure that the FileObject parameter points to. If the FO_HANDLE_CREATED flag is set, this means that one or more handles have been created for the file, so it is not safe to call FltCancelFileOpen.

FltCancelFileOpen sets the FO_FILE_OPEN_CANCELLED flag in the Flags member of the file object that FileObject points to. This flag indicates that the create operation has been canceled, and a close (IRP_MJ_CLOSE) request will be issued for this file object.

Once the create operation has been canceled, it cannot be reissued. For more information, see FltReissueSynchronousIo.

FltCancelFileOpen can only be called from a minifilter driver's post-create callback routine. Calling FltCancelFileOpen from a postoperation callback (PFLT_POST_OPERATION_CALLBACK) routine for any other type of I/O operation, or calling it from a preoperation callback (PFLT_PRE_OPERATION_CALLBACK) routine, is a programming error.

Callers of FltCancelFileOpen must be running at IRQL PASSIVE_LEVEL. However, it is safe for minifilter drivers to call this routine from a post-create callback routine, because post-create callback routines are guaranteed to be called at IRQL PASSIVE_LEVEL, in the context of the thread that originated the IRP_MJ_CREATE request.

Requirements

Requirement	Value
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (see Remarks section)