FltQueueDeferredIoWorkItem function (fltkernel.h)

Article
04/18/2022

The FltQueueDeferredIoWorkItem routine posts an IRP-based I/O operation to a work queue.

Syntax

NTSTATUS FLTAPI FltQueueDeferredIoWorkItem(
  [in] PFLT_DEFERRED_IO_WORKITEM         FltWorkItem,
  [in] PFLT_CALLBACK_DATA                Data,
  [in] PFLT_DEFERRED_IO_WORKITEM_ROUTINE WorkerRoutine,
  [in] WORK_QUEUE_TYPE                   QueueType,
  [in] PVOID                             Context
);

Parameters

[in] FltWorkItem

A pointer to the work item to add to the work queue. The work item must have been allocated by calling FltAllocateDeferredIoWorkItem.

[in] Data

A pointer to the FLT_CALLBACK_DATA structure for the I/O operation. The operation must be an IRP-based I/O operation. To determine whether a given callback data structure represents an IRP-based I/O operation, use the FLT_IS_IRP_OPERATION macro.

[in] WorkerRoutine

A pointer to a caller-supplied worker callback routine. This routine is declared as follows:

typedef VOID
(*PFLT_DEFERRED_IO_WORKITEM_ROUTINE) (
    _In_ PFLT_DEFERRED_IO_WORKITEM FltWorkItem,
    _In_ PFLT_CALLBACK_DATA CallbackData,
    _In_opt_ PVOID Context
    );

where:

FltWorkItem is an opaque pointer to a deferred work item structure.
CallbackData is a pointer to the callback data structure for the I/O operation.
Context is an optional context information pointer that was passed as the Context parameter of FltQueueDeferredIoWorkItem.

[in] QueueType

Specifies the queue into which the work item that FltWorkItem points to is to be inserted. QueueType can be one of the following values.

Value	Meaning
CriticalWorkQueue	Insert the work item into the queue from which a system thread with a real-time priority attribute processes the work item.
DelayedWorkQueue	Insert the work item into the queue from which a system thread with a variable priority attribute processes the work item.

The QueueType value HyperCriticalWorkQueue is reserved for system use.

[in] Context

A pointer to caller-defined context information to be passed as the Context parameter of the callback routine specified in the WorkerRoutine parameter.

Return value

The FltQueueDeferredIoWorkItem routine returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return code	Description
STATUS_FLT_DELETING_OBJECT	The target instance for the I/O operation (Data->Iopb->TargetInstance) is being torn down. This is an error code.
STATUS_FLT_NOT_SAFE_TO_POST_OPERATION	The I/O operation cannot be posted safely to a worker thread. See Remarks for possible reasons why this error code is returned.

Remarks

The FltQueueDeferredIoWorkItem routine posts an I/O operation to a system work queue. The specified WorkerRoutine callback routine is called in the context of a system thread, at IRQL PASSIVE_LEVEL.

The operation must be an IRP-based I/O operation. To determine whether a given callback data structure represents an IRP-based I/O operation, use the FLT_IS_IRP_OPERATION macro.

FltQueueDeferredIoWorkItem returns STATUS_FLT_NOT_SAFE_TO_POST_OPERATION when the I/O operation cannot be posted safely to a worker thread. Possible reasons include the following:

FltQueueDeferredIoWorkItem cannot post a paging I/O operation to a worker thread.
FltQueueDeferredIoWorkItem cannot post an I/O operation to a worker thread if the TopLevelIrp field of the current thread is not NULL, because the resulting file system recursion could cause deadlocks or stack overflows. For more information, see IoGetTopLevelIrp.

A minifilter driver can use FltQueueDeferredIoWorkItem in a preoperation callback (PFLT_PRE_OPERATION_CALLBACK) routine as follows:

The preoperation callback calls FltAllocateDeferredIoWorkItem to allocate the work item.
The preoperation callback calls FltQueueDeferredIoWorkItem to post the operation to the work queue.
The preoperation callback returns FLT_PREOP_PENDING.
After processing the I/O operation, the work routine calls FltCompletePendedPreOperation to return the I/O operation to the Filter Manager.
The work routine calls FltFreeDeferredIoWorkItem to free the work item.

A minifilter driver can use FltQueueDeferredIoWorkItem in a post-operation callback (PFLT_POST_OPERATION_CALLBACK) routine as follows:

The post-operation callback calls FltAllocateDeferredIoWorkItem to allocate the work item.
The post-operation callback calls FltQueueDeferredIoWorkItem to post the operation to the work queue.
The post-operation callback returns FLT_POSTOP_MORE_PROCESSING_REQUIRED.
After processing the I/O operation, the work routine calls FltCompletePendedPostOperation to return the I/O operation to the Filter Manager.
The work routine calls FltFreeDeferredIoWorkItem to free the work item.

Requirements

Requirement	Value
Minimum supported client	Windows 2000
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= DISPATCH_LEVEL