Modifying Parameters

A minifilter driver can modify certain parameters associated with an I/O operation, such as the target instance, target file object, and operation-specific parameters including buffer address and memory descriptor list (MDL) address. The minifilter driver usually modifies parameters in its preoperation callback for the I/O request. If the minifilter driver modifies parameters, it must call FltSetCallbackDataDirty to notify the filter manager that the parameters have changed. It should also record changes in the context passed from its preoperation callback so they are available to its postoperation callback.

A minifilter driver can change the I/O status for an operation when completing the operation in its preoperation callback or failing the operation in its postoperation callback (such as changing a STATUS_SUCCESS to an error status). It is not necessary to call FltSetCallbackDataDirty in this case.

For more information about modifying parameters, see Modifying the Parameters for an I/O Operation.

A minifilter driver can "swap buffers" by replacing the buffer field of an I/O request with its own buffer. Such a minifilter driver is responsible for keeping the MDL and buffer fields of the I/O request in sync. The filter manager sets the FLTFL_CALLBACK_DATA_SYSTEM_BUFFER_FLAG in the FLT_CALLBACK_DATA structure to indicate whether a buffer is a system buffer; if so, the minifilter driver must allocate the replacement buffer from nonpaged pool and set the MDL field to NULL. Otherwise, the buffer can be allocated from either paged or nonpaged pool, and the minifilter driver must always create and set an MDL. (In the case of a fast I/O operation, the new buffer can be allocated from either paged or nonpaged pool and the MDL should be NULL.) The minifilter driver must not free the buffer or MDL it is replacing, and it must not free any MDL it has successfully inserted into a callback data structure (the filter manager will free the MDL on behalf of the minifilter driver). After making a change to an MDL or buffer, the minifilter driver must call FltSetCallbackDataDirty.

A minifilter driver must register a postoperation callback for any operation in which it swaps buffers. In this callback routine, the minifilter driver must free any buffers it allocated. The filter manager will free the MDL unless the minifilter driver calls FltRetainSwappedBufferMdlAddress; in this case, the minifilter driver is responsible for freeing the MDL. The minifilter driver can call FltGetSwappedBufferMdlAddress to get the MDL for the buffer set in its preoperation callback.

If the minifilter driver is unloaded during an operation in which it has swapped buffers, the operation cannot be "drained"; instead, the operation is canceled and the filter manager waits for the operation to complete before unloading the minifilter driver.

See the SwapBuffers sample for an example of a minifilter driver that swaps buffers.

Filter Manager Routines for Modifying Parameters

The filter manager provides the following support routines for modifying I/O operation parameters in preoperation and postoperation callback routines:

FltClearCallbackDataDirty

FltIsCallbackDataDirty

FltSetCallbackDataDirty

The following routines provide support for swapping buffers:

FltGetSwappedBufferMdlAddress

FltRetainSwappedBufferMdlAddress