FltPerformAsynchronousIo function (fltkernel.h)

Article
10/21/2021

A minifilter driver calls FltPerformAsynchronousIo to initiate an asynchronous I/O operation.

Syntax

NTSTATUS FLTAPI FltPerformAsynchronousIo(
  [in, out] PFLT_CALLBACK_DATA               CallbackData,
  [in]      PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in]      PVOID                            CallbackContext
);

Parameters

[in, out] CallbackData

Pointer to a callback data (FLT_CALLBACK_DATA) structure allocated by a previous call to FltAllocateCallbackData. This parameter is required and cannot be NULL. The caller is responsible for freeing this structure when it is no longer needed by calling FltFreeCallbackData.

[in] CallbackRoutine

Pointer to a PFLT_COMPLETED_ASYNC_IO_CALLBACK-typed callback routine to be called when the I/O operation is completed. Note: The Filter Manager calls this routine after it calls the postoperation callback (PFLT_POST_OPERATION_CALLBACK) routines of any minifilter drivers whose instances are attached below the initiating instance (specified in the Instance parameter to FltAllocateCallbackData). This parameter is required and cannot be NULL. The Filter Manager always calls this routine, even when FltPerformAsynchronousIo fails.

[in] CallbackContext

Context pointer to be passed to the CallbackRoutine This parameter is optional and can be NULL.

Return value

FltPerformAsynchronousIo returns STATUS_SUCCESS to indicate that the I/O operation was completed by the file system, and the callback routine that CallbackRoutine points to has been called. Otherwise, it returns an appropriate NTSTATUS value such as one of the following:

Return code	Description
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE requests cannot be performed asynchronously. This is an error code.
STATUS_PENDING	The operation returned STATUS_PENDING. Filter Manager will call the callback routine that CallbackRoutine points to when the I/O operation is complete. This code indicates only that the operation was initiated.
STATUS_FLT_IO_COMPLETE	The operation was completed by the preoperation callback routine of the minifilter driver whose instances are attached below the initiating instance.

Remarks

A minifilter driver calls FltPerformAsynchronousIo to initiate an asynchronous I/O operation after calling FltAllocateCallbackData to allocate a callback data structure for the operation.

FltPerformAsynchronousIo sends the I/O operation only to the minifilter driver instances attached below the initiating instance (specified in the Instance parameter to FltAllocateCallbackData), and the file system. Minifilter drivers attached above the specified instance do not receive the I/O operation.

Minifilter drivers can only initiate IRP-based I/O operations. They cannot initiate fast I/O or file system filter (FSFilter) callback operations.

Minifilter drivers should use FltPerformAsynchronousIo only for asynchronous I/O operations for which routines such as the following cannot be used:

IRP_MJ_CREATE requests cannot be performed asynchronously.

The callback data (FLT_CALLBACK_DATA) structure can be freed or reused at any time after the callback routine that CallbackRoutine points to has been called. The caller can free the callback data structure by calling FltFreeCallbackData or prepare it for reuse by calling FltReuseCallbackData.

Note

STATUS_SUCCESS and STATUS_FLT_IO_COMPLETE indicate that the I/O operation was completed, but do not indicate the final status of the I/O operation. To determine the actual operation status returned by the underlying minifilter drivers, filter drivers, and file system, the CallbackRoutine should examine the IoStatus member of the callback data structure received in the CallbackRoutine's CallbackContext parameter.

Because Filter Manager always calls the callback routine that CallbackRoutine points to, even when FltPerformAsynchronousIo fails, the minifilter driver can perform the freeing or reusing operations directly in the callback routine.

The caller of FltPerformAsynchronousIo can be running at IRQL <= APC_LEVEL if the IRP_PAGING_IO flag is set in the IrpFlags member of the FLT_IO_PARAMETER_BLOCK structure for the operation. (This flag is only valid for IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_QUERY_INFORMATION, and IRP_MJ_SET_INFORMATION operations.) Otherwise, the caller must be running at IRQL PASSIVE_LEVEL.

Requirements

Requirement	Value
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
DLL	Fltmgr.sys
IRQL	See Remarks section.