Expand Minimize

FltCancelFileOpen routine

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

Syntax


VOID FltCancelFileOpen(
  _In_  PFLT_INSTANCE Instance,
  _In_  PFILE_OBJECT FileObject
);

Parameters

Instance [in]

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

FileObject [in]

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

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

PASSIVE_LEVEL (see Remarks section)

See also

FILE_OBJECT
FLT_CALLBACK_DATA
FLT_IS_REISSUED_IO
FLT_PARAMETERS for IRP_MJ_CREATE
FltReissueSynchronousIo
FltSetCallbackDataDirty
IoCancelFileOpen
IRP_MJ_CLOSE
IRP_MJ_CREATE
PFLT_POST_OPERATION_CALLBACK
PFLT_PRE_OPERATION_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft