A minifilter driver calls FltPerformAsynchronousIo to initiate an asynchronous I/O operation.
NTSTATUS FltPerformAsynchronousIo( _Inout_ PFLT_CALLBACK_DATA CallbackData, _In_ PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine, _In_ PVOID CallbackContext );
- CallbackData [in, out]
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.
- CallbackRoutine [in]
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.
- CallbackContext [in]
Context pointer to be passed to the CallbackRoutine This parameter is optional and can be NULL.
FltPerformAsynchronousIo returns STATUS_SUCCESS to indicate that the I/O operation is complete, and the callback routine that CallbackRoutine points to has been called. Otherwise, it returns an appropriate NTSTATUS value such as one of the following:
IRP_MJ_CREATE requests cannot be performed asynchronously. This is an error code.
The operation returned STATUS_PENDING. The callback routine that CallbackRoutine points to is called when the I/O operation is complete. This is a success code.
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. Because the callback routine that CallbackRoutine points to is always called by the Filter Manager, even when FltPerformAsynchronousIo fails, the minifilter driver can perform the freeing or reusing operations directly in the callback routine.
Note that the NTSTATUS value returned by FltPerformAsynchronousIo indicates only whether the I/O operation was successfully initiated. This is not the same as the final status of the I/O operation. To determine the status returned by the underlying minifilter drivers, filter drivers, and file system for the operation, the CallbackRoutine should examine the IoStatus member of the callback data structure received in the CallbackRoutine's CallbackContext parameter.
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.
|See Remarks section.|