FltQueueDeferredIoWorkItem function (fltkernel.h)
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 |