This topic has not yet been rated - Rate this topic

FltQueueDeferredIoWorkItem routine

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

Syntax


NTSTATUS 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

FltWorkItem [in]

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

Data [in]

A pointer to the callback data (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.

WorkerRoutine [in]

A pointer to a caller-supplied worker 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
      );

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

QueueType [in]

This parameter specifies the queue into which the work item that FltWorkItem points to is to be inserted. QueueType can be either of the following.

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.

Context [in]

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. Possible reasons include the following: 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.) FltQueueDeferredIoWorkItem cannot post a paging I/O operation to a worker thread. STATUS_FLT_NOT_SAFE_TO_POST_OPERATION is an error code.

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. Possible reasons include the following:

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.)
FltQueueDeferredIoWorkItem cannot post a paging I/O operation to a worker thread.

STATUS_FLT_NOT_SAFE_TO_POST_OPERATION is an error code.

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.

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.

Caution To avoid deadlocks, a minifilter must not post an I/O operation to a system work queue in the post-operation callback for any I/O operations that a driver can complete directly in the storage stack, such as the following:

IRP_MJ_READ
IRP_MJ_WRITE
IRP_MJ_FLUSH_BUFFERS

Requirements