PFLT_PRE_OPERATION_CALLBACK function pointer

A minifilter driver's PFLT_PRE_OPERATION_CALLBACK routine performs pre-operation processing for I/O operations.

Syntax


typedef FLT_PREOP_CALLBACK_STATUS ( *PFLT_PRE_OPERATION_CALLBACK)(
  _Inout_  PFLT_CALLBACK_DATA Data,
  _In_     PCFLT_RELATED_OBJECTS FltObjects,
  _Out_    PVOID *CompletionContext
);

Parameters

Data [in, out]

A pointer to the callback data (FLT_CALLBACK_DATA) structure for the I/O operation.

FltObjects [in]

A pointer to an FLT_RELATED_OBJECTS structure that contains opaque pointers for the objects related to the current I/O request.

CompletionContext [out]

If this callback routine returns FLT_PREOP_SUCCESS_WITH_CALLBACK or FLT_PREOP_SYNCHRONIZE, this parameter is an optional context pointer to be passed to the corresponding post-operation callback routine. Otherwise, it must be NULL.

Return value

This callback routine returns one of the following FLT_PREOP_CALLBACK_STATUS values:

Return codeDescription
FLT_PREOP_COMPLETE

The minifilter driver is completing the I/O operation. The filter manager does not send the I/O operation to any minifilter drivers below the caller in the driver stack or to the file system. In this case, the filter manager only calls the post-operation callback routines of the minifilter drivers above the caller in the driver stack.

FLT_PREOP_DISALLOW_FASTIO

The operation is a fast I/O operation, and the minifilter driver is not allowing the fast I/O path to be used for this operation. The filter manager does not send the fast I/O operation to any minifilter drivers below the caller in the driver stack or to the file system. In this case, the filter manager only calls the post-operation callback routines of the minifilter drivers above the caller in the driver stack.

FLT_PREOP_PENDING

The minifilter driver has pended the I/O operation, and the operation is still pending. The filter manager does not process the I/O operation further until the minifilter driver calls FltCompletePendedPreOperation.

FLT_PREOP_SUCCESS_NO_CALLBACK

The minifilter driver is returning the I/O operation to the filter manager for further processing. In this case, the filter manager does not call the minifilter driver's post-operation callback, if one exists, during I/O completion.

FLT_PREOP_SUCCESS_WITH_CALLBACK

The minifilter driver is returning the I/O operation to the filter manager for further processing. In this case, the filter manager calls the minifilter driver's post-operation callback during I/O completion.

FLT_PREOP_SYNCHRONIZE

The minifilter driver is returning the I/O operation to the filter manager for further processing, but it is not completing the operation. In this case, the filter manager calls the minifilter's post-operation callback in the context of the current thread at IRQL <= APC_LEVEL.

 

Remarks

A minifilter driver's pre-operation callback routine processes one or more types of I/O operations. This callback routine is similar to a dispatch routine in the legacy filter model.

A minifilter driver registers a pre-operation callback routine for a particular type of I/O operation by storing the callback routine's entry point in the OperationRegistration array of the FLT_REGISTRATION structure. The minifilter driver passes this structure as a parameter to FltRegisterFilter in its DriverEntry routine. A minifilter driver can register a pre-operation callback routine for a given type of I/O operation without registering a post-operation callback (PFLT_POST_OPERATION_CALLBACK) routine and vice versa.

If this routine returns FLT_PREOP_COMPLETE, it must set the callback data structure's IoStatus.Status field to the final NTSTATUS value for the I/O operation. This NTSTATUS value cannot be STATUS_PENDING. For a cleanup or close operation, it must be a success NTSTATUS value other than STATUS_PENDING because cleanup and close operations cannot fail.

If this routine returns FLT_PREOP_DISALLOW_FASTIO, it should not set the callback data structure's IoStatus.Status field because the filter manager automatically sets this field to STATUS_FLT_DISALLOW_FAST_IO.

FLT_PREOP_DISALLOW_FASTIO can only be returned for a fast I/O operation. To determine whether a given callback data structure represents a fast I/O operation, use the FLT_IS_FASTIO_OPERATION macro.

FLT_PREOP_PENDING can only be returned for IRP-based I/O operations because only IRP-based I/O operations can be pended. To determine whether a given callback data structure represents an IRP-based I/O operation, use the FLT_IS_IRP_OPERATION macro.

If a minifilter driver's pre-operation callback routine returns FLT_PREOP_SYNCHRONIZE, the minifilter driver must have registered a corresponding post-operation callback for the operation.

FLT_PREOP_SYNCHRONIZE should only be returned for IRP-based I/O operations. If it is returned for an I/O operation that is not an IRP-based operation, the filter manager treats this return value as if it were FLT_PREOP_SUCCESS_WITH_CALLBACK.

Minifilter drivers should not return FLT_PREOP_SYNCHRONIZE for create operations, because these operations are already synchronized by the filter manager.

Minifilter drivers must never return FLT_PREOP_SYNCHRONIZE for asynchronous read and write operations. Doing so can severely degrade both minifilter driver and system performance.

A minifilter driver's pre-operation or post-operation callback routine can modify the contents of the callback data structure for the operation. If it does, it must then call FltSetCallbackDataDirty, unless it has changed the contents of the callback data structure's IoStatus field.

The IRQL for this generic callback routine depends on its specific IO paths.

File systems round write and read operations at end of file up to a multiple of the sector size of the underlying file storage device. When processing pre-read or pre-write operations, filters that allocate and swap buffers need to round the size of an allocated buffer up to a multiple of the sector size of the associated device. If they do not, the length of data transferred from the underlying file system will exceed the allocated length of the buffer. For more information about swapping buffers, see swapBuffers Minifilter Sample.

Starting with Windows 8, CompletionContext uses the _Flt_CompletionContext_Outptr_ annotation which defines valid context values based on the operation result. The following is a usage example for the callback with the annotation for CompletionContext.


FLT_PREOP_CALLBACK_STATUS 
SwapPreReadBuffers( 
    _Inout_ PFLT_CALLBACK_DATA Data, 
    _In_ PCFLT_RELATED_OBJECTS FltObjects, 
    _Flt_CompletionContext_Outptr_ PVOID *CompletionContext 
    ); 
  


Requirements

Version

Available in Microsoft Windows 2000 Update Rollup 1 for SP4, Windows XP SP2, Windows Server 2003 SP1, and later Windows operating systems.

Header

Fltkernel.h (include FltKernel.h)

IRQL

See Remarks section

See also

_Flt_CompletionContext_Outptr_
FLT_CALLBACK_DATA
FLT_IO_PARAMETER_BLOCK
FLT_IS_FASTIO_OPERATION
FLT_IS_IRP_OPERATION
FLT_IS_REISSUED_IO
FLT_IS_SYSTEM_BUFFER
FLT_REGISTRATION
FLT_RELATED_OBJECTS
FltCompletePendedPostOperation
FltCompletePendedPreOperation
FltQueueDeferredIoWorkItem
FltRegisterFilter
FltSetCallbackDataDirty
PFLT_POST_OPERATION_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft