FltReissueSynchronousIo function (fltkernel.h)

Article
11/30/2021

FltReissueSynchronousIo initiates a new synchronous I/O operation that uses the parameters from a previously synchronized I/O operation.

Syntax

VOID FLTAPI FltReissueSynchronousIo(
  [in] PFLT_INSTANCE      InitiatingInstance,
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parameters

[in] InitiatingInstance

An opaque instance pointer to the minifilter driver instance that is reissuing the I/O operation. Must be the same instance that initiated the previous I/O operation. This parameter is required and cannot be set to NULL.

[in] CallbackData

A pointer to the callback data (FLT_CALLBACK_DATA) structure from a previously synchronized I/O operation. This parameter is required and cannot be set to NULL.

Return value

None

Remarks

A minifilter driver calls FltReissueSynchronousIo from a postoperation callback (PFLT_POST_OPERATION_CALLBACK) routine to reissue a synchronized I/O request. It typically calls FltReissueSynchronousIo from a postoperation callback routine to reissue a failed operation with different parameters, or to handle a reparse bounce. However, it can also call FltReissueSynchronousIo to reissue I/O that the minifilter driver generated through calls to the FltAllocateCallbackData and FltPerformSynchronousIo routines. In this situation, it does not matter whether it calls FltReissueSynchronousIo in a postoperation callback routine or outside the context of an operation callback routine. For calls outside the context of a postoperation callback routine, consider using the FltReuseCallbackData and FltPerformSynchronousIo routines instead.

The caller can modify the contents of the callback data (FLT_CALLBACK_DATA) structure's I/O parameter block before reissuing the I/O request. If it does, it must call FltSetCallbackDataDirty before calling FltReissueSynchronousIo.

For example, if a minifilter driver uses reparse points, and its post-create callback routine is called for a create operation that returned STATUS_REPARSE, the minifilter driver can reissue the create operation for its own reparse points. In this case, the minifilter driver will complete the following steps:

Set the FILE_OPEN_REPARSE_POINT flag in the callback data structure's I/O parameter block.
Call FltSetCallbackDataDirty.
Call FltReissueSynchronousIo to reissue the create request.

The Filter Manager sends the reissued I/O request only to the minifilter driver instances that are attached below the initiating instance (specified in the InitiatingInstance parameter) and to the file system. Minifilter driver instances attached above the initiating instance do not receive the reissued I/O request.

Only synchronized I/O operations can be reissued. To provide the driver with the ability to reissue, by calling FltReissueSynchronousIo in the postoperation callback routine, a minifilter driver must specifically return FLT_PREOP_SYNCHRONIZE in the preoperation callback routine.

Note

The minifilter driver does not call the FltIsOperationSynchronous routine to determine whether the preoperation callback routine for this operation returned FLT_PREOP_SYNCHRONIZE. The minifilter driver calls FltIsOperationSynchronous to determine whether the operation itself is synchronous from the I/O manager's perspective.

Only IRP-based I/O operations can be reissued. Fast I/O operations and file system filter (FSFilter) callback operations cannot be reissued. To determine whether an I/O operation is IRP-based, use the FLT_IS_IRP_OPERATION macro.

A create (IRP_MJ_CREATE) operation that has been canceled cannot be reissued. Before calling FltReissueSynchronousIo for a create operation, callers should check the Flags member of the file object for the create operation. If the FO_FILE_OPEN_CANCELLED flag is set, this means that the create operation has been canceled, and a close (IRP_MJ_CLOSE) operation will be issued for this file object. If FltReissueSynchronousIo is called for a create operation that has been canceled, the Filter Manager fails the reissued I/O request with STATUS_CANCELLED.

Note

When minifilter drivers re-issue the create in the post-create callback, they do not have to release and set the buffer that is associated with their reparse point (TagData field in CallbackData) to NULL. Instead, the Filter Manager releases and sets the buffer to NULL for them.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Update Rollup 1 for SP4; Windows XP SP2
Minimum supported server	Windows Server 2003 SP1
Target Platform	Universal
Header	fltkernel.h (include FltKernel.h)
Library	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (non-paging IO can only be reissued at PASSIVE_LEVEL)