Expand Minimize

FltDoCompletionProcessingWhenSafe routine

If it is safe to do so, the FltDoCompletionProcessingWhenSafe function executes a minifilter driver postoperation callback routine.

Syntax


BOOLEAN FltDoCompletionProcessingWhenSafe(
  _In_     PFLT_CALLBACK_DATA           Data,
  _In_     PCFLT_RELATED_OBJECTS        FltObjects,
  _In_opt_ PVOID                        CompletionContext,
  _In_     FLT_POST_OPERATION_FLAGS     Flags,
  _In_     PFLT_POST_OPERATION_CALLBACK SafePostCallback,
  _Out_    PFLT_POSTOP_CALLBACK_STATUS  RetPostOperationStatus
);

Parameters

Data [in]

Pointer to the callback data structure (FLT_CALLBACK_DATA) for the I/O operation. Usually this is the same as the Data pointer that was passed to the postoperation callback routine (PFLT_POST_OPERATION_CALLBACK) that called FltDoCompletionProcessingWhenSafe.

FltObjects [in]

Pointer to the related objects structure (FLT_RELATED_OBJECTS) for the I/O operation. Usually this is the same as the FltObjects pointer that was passed to the postoperation callback routine that called FltDoCompletionProcessingWhenSafe.

CompletionContext [in, optional]

Pointer to a caller-supplied context information that will be passed in to the callback function that is specified in the SafePostCallback parameter.

Flags [in]

Bitmask of flags which specify how completion processing will be performed. Usually this is the same as the Flags value that was passed to the postoperation callback routine that called FltDoCompletionProcessingWhenSafe. For more information, see the following Remarks section.

SafePostCallback [in]

Pointer to a caller-supplied PFLT_POST_OPERATION_CALLBACK-typed callback routine that the operating system calls when it is safe to do so.

RetPostOperationStatus [out]

Caller-allocated variable that receives the final status value for the I/O operation. For more information on how this parameter is set, see the following Remarks section.

Return value

FltDoCompletionProcessingWhenSafe returns TRUE if completion processing for the I/O operation can be performed immediately or the I/O operation was successfully posted to a worker thread; otherwise, it returns FALSE.

Remarks

FltDoCompletionProcessingWhenSafe executes the SafePostCallback immediately if the caller is running at IRQL <= APC_LEVEL. Otherwise, if it is safe to post the operation to a worker thread, the SafePostCallback processing is deferred until it can be called in a thread context where IRQL <= APC_LEVEL.

If IRQL < DISPATCH_LEVEL:

  • FltDoCompletionProcessingWhenSafe calls the callback routine specified in SafePostCallback.

  • The RetPostOperationStatus parameter receives a FLT_POSTOP_CALLBACK_STATUS value returned by SafePostCallback.

  • FltDoCompletionProcessingWhenSafe returns TRUE.

If IRQL >= DISPATCH_LEVEL, FltDoCompletionProcessingWhenSafe attempts to post the I/O operation to a worker thread.

If the I/O operation was successfully posted:
  • FltDoCompletionProcessingWhenSafe calls the SafePostCallback routine from the worker thread.
  • Filter manager sets RetPostOperationStatus to FLT_POSTOP_MORE_PROCESSING_REQUIRED.
  • FltDoCompletionProcessingWhenSafe returns TRUE.
If the I/O operation could not be safely posted:
  • Filter manager sets RetPostOperationStatus to FLT_POSTOP_FINISHED_PROCESSING.
  • FltDoCompletionProcessingWhenSafe returns FALSE.

FltDoCompletionProcessingWhenSafe can only be called for IRP-based operations. To determine whether the operation is an IRP-based operation, use the FLT_IS_IRP_OPERATION macro.

FltDoCompletionProcessingWhenSafe cannot be used to post completion of a paging I/O operation to a worker thread.

FltDoCompletionProcessingWhenSafe can only be called from a minifilter driver's postoperation callback routine (PFLT_POST_OPERATION_CALLBACK). Note that FltDoCompletionProcessingWhenSafe should never be called if the Flags parameter of the postoperation callback has the FLTFL_POST_OPERATION_DRAINING bit set.

If a minifilter calls FltDoCompletionProcessingWhenSafe and the SafePostCallback is invoked in a worker thread because it is not safe to invoke it in the current thread context, the filter manager will resume completion processing as long as the minifilter does not return FLT_POSTOP_MORE_PROCESSING_REQUIRED from the SafePostCallback.

If the minifilter does return FLT_POSTOP_MORE_PROCESSING_REQUIRED from the SafePostCallback, the minifilter must call FltCompletePendedPostOperation to resume completion processing.

Caution   To avoid deadlocks, FltDoCompletionProcessingWhenSafe cannot be called for I/O operations that can be directly completed by a driver in the storage stack, such as the following:
  • IRP_MJ_READ
  • IRP_MJ_WRITE
  • IRP_MJ_FLUSH_BUFFERS

Requirements

Target platform

Universal

Version

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

Header

Fltkernel.h (include Fltkernel.h)

Library

Fltmgr.lib

IRQL

Any.

See also

FLT_CALLBACK_DATA
FLT_IS_IRP_OPERATION
FLT_RELATED_OBJECTS
FltCancelIo
PFLT_POST_OPERATION_CALLBACK
FltCompletePendedPostOperation

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft