Filter initiated I/O in minifilter (filter self-generated I/O)

The following is taken from the filter driver developer guide:

Certain minifilters need to perform I/O of theirown. this I/O is only seen byminifilters below the current minifilter IN THE minifilter stack of thevolume. for instance, an anti-virusminifilter may wish to read a file before an open has completed. in
The new minifilter model, a minifilter willbe able to generate I/O in one of two ways: using general routines similar totoday's routines, and using simplified routines that provide an interfacesimilar to the zwxxx routines.

The general routines that the system provides tominifilters for I/O generation are:

Ntstatus

Fltapi

Fltallocatecallbackdata (

Inpflt_instance instance,

Inpfile_object fileobject optional,

Outpflt_callback_data * retnewcallbackdata

);

 

Void

Fltapi

Fltw.msynchronousio (

In pflt_callback_data callbackdata

);

 

Ntstatus

Fltapi

Fltw.masynchronousio (

In pflt_callback_data callbackdata,

In pflt_completed_async_io_callbackcallbackroutine,

In pvoid callbackcontext

);

Using the general routines, A minifilter cancall invoke () to allocate a callbackdata for the operation, and then fill in the appropriate parameters inthe callbackdata for the desired operation. The minifilter then callter ()
Or flt‑masynchronousio () to actually initiate the I/O. The instance parameter shoshould always be for the current instance doingthe I/O operation.

In addition filter manager exports some commonutility routines. Examples:

Ntstatus

Fltapi

Fltcreatefile (

In pflt_filter filter,

In pflt_instance instance optional,

Out phandle filehandle,

In access_mask desiredaccess,

Inpobject_attributes objectattributes,

Out pio_status_block iostatusblock,

In plarge_integer allocationsize optional,

In ulong fileattributes,

In ulong internal access,

In ulong createdisposition,

In ulong createoptions,

In pvoid eabuffer optional,

In ulong ealength,

In ulong flags

);

If instancehandle is omitted, the create will be sent to the top of the stack (so the minifilter initiatingthe operation will itself see the I/O recursively .) this is discouraged unlessabsolutely necessary as it can cause deadlocks and stack overflows ifminifilters
Misuse it.

If instancehandle is provided (this shoshould always be your own instance), then the CREATE is initiated withthe minifilter just below the caller of this API, by passing all legacyminifilters above the filter manager and minifilters above the caller.

The filehandle returned by this API can be usedin all ZW * cballs that accept a file handle as a parameter. if the instanceparameter is non-null in a call to fltcreatefile (), It isguaranteed that all future I/O (via the ZW APIs, fltclose () etc .), on this handle
Will only be seen by the instancesBelowThe initiatinginstance.

Fltreadfile () and fltwritefile () are support routines to allow minifilters to generate IOS that areonly seen by instances below them when they have only the fileobject torepresent the file. these routines areanalogous to "rolling an IRP" in the legacy Filter
Model.

Importantnote:Filters need not use fltreadfile ()/fltwritefile () to initiate I/O on the handle returned by fltcreatefile (). for handles created via fltcreatefile (), the normal ZW * () APIs will be targeted to the correct instancerelative
To the initiatinginstance specified.

Ntstatus

Fltapi

Fltreadfile (

Inpflt_instance initiatinginstance,

Inpfile_object fileobject,

Inplarge_integer byteoffset optional,

In ulonglength,

Out pvoidbuffer,

In flt_io_operation_flags flags,

Out pulongbytesread optional,

Inpflt_completed_async_io_callback callbackroutine optional,

In pvoidcallbackcontext optional

);

 

Ntstatus

Fltapi

Fltwritefile (

In pflt_instance initiatinginstance,

In pfile_object fileobject,

In plarge_integer byteoffset optional,

In ulong length,

In pvoid buffer,

In flt_io_operation_flags flags,

Out Pulong byteswritten optional,

In pflt_completed_async_io_callbackcallbackroutine optional,

In pvoid callbackcontext optional

);

By default, all minifilter-initiated I/O is sentto the next attached instance for the given volume, bypassing any instancesattached abve the minifilter initiating the I/O.

Minifilter initiated I/O can be synchronous or asynchronous. When the I/O is asynchronous, The minifilterprovides a callback routine that the system will call when the I/O iscompleted.

Chu's mad man, Chu Daxia, translated this part of the content in the Windows File System filtering driver development tutorial (version 2), as follows:

Some micro-filters need to execute their own I/O requests. In the microfilter stack of a volume, only the filters below this filter can receive these I/O requests. For example, a antivirus software may want to read this file before opening a file. In the new micro-filter mode, a micro-filter can generate its own request in two ways: Use a generation routine, similar to other existing routines. In addition, the old zwxxx routine is used.
 
The main I/O generation routine is as follows:

Ntstatus

Fltapi

Fltallocatecallbackdata (

Inpflt_instance instance,

Inpfile_object fileobject optional,

Outpflt_callback_data * retnewcallbackdata

);

 

Void

Fltapi

Fltw.msynchronousio (

In pflt_callback_data callbackdata

);

 

Ntstatus

Fltapi

Fltw.masynchronousio (

In pflt_callback_data callbackdata,

In pflt_completed_async_io_callbackcallbackroutine,

In pvoid callbackcontext

);

To use these routines, a micro-filter can first call fltallocatecallbackdata to allocate a callbackdata. Then fill in the appropriate parameters for different operations. Then you can call fltpolicmsynchronousio () or fltpolicmasynchronousio () to actually initiate an I/O Request. The instance parameter must always be the instance where the micro filter initiates the request. (Note: requests cannot be initiated by instance A and instance B ).
 
In addition, the filter manager exports some common Utility Routines, such:

Ntstatus

Fltapi

Fltcreatefile (

In pflt_filter filter,

In pflt_instance instance optional,

Out phandle filehandle,

In access_mask desiredaccess,

Inpobject_attributes objectattributes,

Out pio_status_block iostatusblock,

In plarge_integer allocationsize optional,

In ulong fileattributes,

In ulong internal access,

In ulong createdisposition,

In ulong createoptions,

In pvoid eabuffer optional,

In ulong ealength,

In ulong flags

);

 
If the instance parameter is ignored .), then, the CREATE request is sent to the top of the microfilter stack (this causes the microfilter to loop back to view the request sent by itself .) Unless absolutely necessary, this is unwise. If abuse occurs, it can easily lead to deadlocks and stack overflow.
 
If this parameter is specified (it should always be your current instance), then only this request is initiated downward. All the filters (including their own) above the microfilters that call this API will not receive this request.
 
The filehandle parameter returns a file handle called by ZW * series functions. if the previously specified instance is not empty, ensure other future I/O operations on the file handle (through the ZW interface, fltclose (), and so on ), can only be seen by instances under the initiator instance.
 
I/O read/write requests initiated by fltreadfile () and fltwritefile () can only be seen by lower-layer instances. When we only use fileobject without a file handle. These routines are similar to the read/write Method of Self-sent IRP in the old filter model.
 
Important: the filter does not need to use fltreadfile ()/fltwritefile () to initiate an I/O Request to the file handle returned by a fltcreatefile. in this case, you can use the ZW * () interface to send it to the appropriate instance.
 

Ntstatus

Fltapi

Fltreadfile (

Inpflt_instance initiatinginstance,

Inpfile_object fileobject,

Inplarge_integer byteoffset optional,

In ulonglength,

Out pvoidbuffer,

In flt_io_operation_flags flags,

Out pulongbytesread optional,

Inpflt_completed_async_io_callback callbackroutine optional,

In pvoidcallbackcontext optional

);

 

Ntstatus

Fltapi

Fltwritefile (

In pflt_instance initiatinginstance,

In pfile_object fileobject,

In plarge_integer byteoffset optional,

In ulong length,

In pvoid buffer,

In flt_io_operation_flags flags,

Out Pulong byteswritten optional,

In pflt_completed_async_io_callbackcallbackroutine optional,

In pvoid callbackcontext optional

);

The I/O output by the micro filter may be synchronous or asynchronous. when I/O is specified as Asynchronous, The microfilter provides a callback routine. when the system completes the I/O Request callback routine, it will be called.