Expand Minimize

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.

ValueMeaning

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 codeDescription
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:

  1. The preoperation callback calls FltAllocateDeferredIoWorkItem to allocate the work item.

  2. The preoperation callback calls FltQueueDeferredIoWorkItem to post the operation to the work queue.

  3. The preoperation callback returns FLT_PREOP_PENDING.

  4. After processing the I/O operation, the work routine calls FltCompletePendedPreOperation to return the I/O operation to the Filter Manager.

  5. 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:

  1. The post-operation callback calls FltAllocateDeferredIoWorkItem to allocate the work item.

  2. The post-operation callback calls FltQueueDeferredIoWorkItem to post the operation to the work queue.

  3. The post-operation callback returns FLT_POSTOP_MORE_PROCESSING_REQUIRED.

  4. 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

Version

This routine is available in Microsoft Windows 2000 and later versions of all Windows operating systems.

Header

Fltkernel.h (include Fltkernel.h)

Library

Fltmgr.lib

IRQL

<= DISPATCH_LEVEL

See also

FLT_CALLBACK_DATA
FLT_IS_IRP_OPERATION
FltAllocateDeferredIoWorkItem
FltCompletePendedPostOperation
FltCompletePendedPreOperation
FltFreeDeferredIoWorkItem
IoGetTopLevelIrp
PFLT_POST_OPERATION_CALLBACK
PFLT_PRE_OPERATION_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft