F I L E S Y S T E M F I L T E R M A N A G E R

Filter Driver
Development Guide

Version 1.0a

Summary

This specification includes, but is not limited to, the following topic areas:

• Description of the new 'File System Filter Manager' architecture and interfaces

• Aspects of the Windows 'Memory Manager', 'I/O Manager', and 'Cache Manager' interfaces that affect the
development of file system filters using the new File System Filter Manager architecture.

Disclaimer
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of
the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a
commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date
of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR
STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part
of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any
means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written
permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject
matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this
document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people,
places and events depicted herein are fictitious, and no association with any real company, organization, product, domain
name, email address, logo, person, place or event is intended or should be inferred.

© 2004 Microsoft Corporation. All rights reserved.

Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United
States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Page 1 of 28
Table Of Contents

File System FilTer Manager............................................................................................................1

Filter Driver Development Guide....................................................................................................1
1. Overview.....................................................................................................................................3
2. Terms..........................................................................................................................................3
3. Minifilter Installation...................................................................................................................4
4. Minifilter Registration.................................................................................................................4
5. Initiating filtering........................................................................................................................4
6. Instance Notification Support......................................................................................................5
6.1. Setting up an Instance...........................................................................................................5

6.2. Controlling Instance Teardown................................................................................................6

6.3. Synchronizing Instance Detach................................................................................................6

7. Callback Support.........................................................................................................................7
7.1. Callback data........................................................................................................................7

7.2. Pre-Operation Callbacks..........................................................................................................8

7.3. Post-Operation Callbacks........................................................................................................9

8. Manipulating Callback Data Parameters....................................................................................11

8.1. I/O Parameter Block.............................................................................................................11

8.2. Accessing buffer/MDL...........................................................................................................12

8.3. Swapping buffers.................................................................................................................13

9. Context Support........................................................................................................................13
9.1. Context Registration.............................................................................................................14

9.2. Context Creation APIs...........................................................................................................14

9.3. Context Retrieval APIs..........................................................................................................17

9.4. Context Freeing APIs............................................................................................................18

10. User Mode Communication......................................................................................................19

10.1. Filter Communication Port Object.........................................................................................19

10.2. Connecting to Communication Port from User Mode................................................................20

10.3. Disconnecting from the Communication Port..........................................................................21

10.4. Unload issues ...................................................................................................................21

11. File Name Support...................................................................................................................21

11.1. Retrieving a File Name during an Operation...........................................................................21

11.2. Additional Support for File Names.........................................................................................23

11.3. Interfaces for Name Providing Filters....................................................................................23

12. Filter Initiated I/O..................................................................................................................25

13. Rules for Unload/Unregister/Detach.......................................................................................27
14. Support Routines.....................................................................................................................27
15. Building a Minifilter.................................................................................................................28

Page 2 of 28
1. Overview
This document pertains to filter drivers between the I/O manager and the base filesystem, which can be local
or remote. It does not pertain to filter drivers that sit between the filesystem and the storage driver(s), such
as FtDisk or DMIO.

We will refer to a file system filter driver written using the new model as a mini file system filter
driver/minifilter.

The existing file system filters based on the sfilter sample – using IRP and device-object based filtering will be
referred to as 'legacy filters'.

One of the key components of the new architecture is a legacy file system filter which is called 'Filter
Manager'. In future Windows operating system releases, this driver will be installed by default on the system.
This driver manages the minifilters by providing export libraries to which the minifilters link. The necessary
header files, libraries and binaries are available in the Minifilter IFSKit.

Why write a mini file system filter driver?

• Simpler, get a more reliable filter driver with less development effort.

• Dynamic load and unload, attach and detach.

• Attach at a well-defined location in the filter stack.

• Context management: fast, clean, reliable contexts for file objects, streams, files, instances, and volumes

• A host of utility routines including support for looking up names and caching them for efficient access,
communication between minifilters and user mode services, and IO queuing.

• Support non-recursive I/O so minifilter generated I/O can easily be seen only by lower minifilters and the
file system.

• Filter only operations of interest to minifilter – unlike the legacy model where a filter has to hook every
entry point to pass through operation.

2. Terms
In the Filter Manager architecture, some new objects are defined. For clarity these objects will be defined up
front.

Filter: A driver that performs some type of filtering operation on the file system.

Volume: For local file systems, the object that represents logical volume the file system manages. For
network redirectors, this represents the object to which all network requests are directed. The volume maps
directly to the file system (local or remote) DEVICE_OBJECT in the legacy filter model.

Instance: An instantiation of a filter on a volume at a unique altitude. The Filter Manager manages
presenting IOs to each instance in the stack of instances attached to a volume. There may be more than one
instance of a given minifilter for a given volume. The canonical example is a filter like FileSpy. It would be
helpful to attach FileSpy both above and below another filter on the same volume with each instance
maintaining a private context. This context could contain the log of IOs seen by the instance for later
comparison of the IO as seen above and below the filter.

File: A named object of data that could be composed of multiple streams that is stored on a disk by the file
system.

Stream: Represents a physical stream of data in a file.

FileObject: Represents a user’s open of a physical stream of data in a file.

CallbackData: The Filter Manager structure that encapsulates all the information about an operation. This
is equivalent to an IRP in the legacy filter model.

Page 3 of 28
3. Minifilter Installation
Minifilters will be installed via an INF file. The INF file indicates what instances the minifilter supports.
Instances are defined in Section 5. Each instance is also accompanied by an altitude value which indicates its
absolute position in a minifilter stack and a set of flags.

The list of instances with their altitudes in the INF is the preferred means for file system filter vendors to ship
their minifilters. The flags indicate if the minifilter needs 'automatic attachment'. If this is the case, for every
volume in the system (and for new ones as they arrive), the minifilter gets a notification that it can respond
to and attach. The altitude in the INF file determines the altitude to which the minifilter attaches if it chooses
to do so.

A file system filter vendor may also create an instance dynamically at a specified altitude at any time when
the minifilter is running via the FilterAttachAtAltitude() function. This is provided as an override and
a potential debugging and testing aid.

4. Minifilter Registration
Mini file system filter drivers are kernel-mode drivers. As such, they must export a function called
DriverEntry(), which will be the first function invoked when the driver is loaded. Most minifilters will call
FltRegisterFilter() in their DriverEntry().
FltRegisterFilter() takes as a parameter a FLT_REGISTRATION structure, which contains an unload
routine, instance notification callbacks, a list of context callback function pointers and a list of file system
operation callback pointers. In the most common case, where the minifilter hooks just a few operations, this
list can be very short.

The minifilter also can specify additional flags for each operation that controls whether it receives the
callbacks in all cases. For instance, if FLTFL_OPERATION_REGISTRATION_SKIP_PAGING_IO is supplied,
the minifilter will not receive any paging I/O operations for that particular IRP major code.

Similarly, if FLTFL_OPERATION_REGISTRATION_SKIP_CACHED_IO is specified, only the non-cached I/O

path will be seen for that operation (i.e., if it is supplied for IRP_MJ_READ, all cached read paths will be
skipped by that minifilter).

5. Initiating filtering
Once a minifilter registers itself, it should initiate filtering at some point by calling the function
FltStartFiltering(). It is not necessary to call it from DriverEntry(), though most filters will
probably prefer to.

This function will kick-off the necessary notifications that will result in the minifilter attaching to the
appropriate volumes and start filtering I/O.

For this the Filter Manager walks through the list of instances that are registered by the minifilter via its INF.

Each instance specifies an "altitude". An altitude is an infinite precision string (e.g., "100.123456") that
defines where it will be attached in a stack of minifilter instances. Altitudes for commercially released
minifilter drivers will be assigned by Microsoft.

The larger the altitude in numeric value, the higher the instance is attached in the minifilter stack for a
volume. Several sample altitudes are provided for developers to use while implementing minifilters and these
are the only altitudes an unsigned driver may use. There are two purposes for altitudes. The first is to
enforce relative minifilter ordering when it is necessary for proper functioning regardless of when the
individual drivers load. For instance, an encryption filter and an antivirus filter must attach with the antivirus
filter on top, otherwise the antivirus filter could not scan the clear text for viruses. The second purpose is to
provide a smaller test matrix for minifilter interoperability testing. Each minifilter instance will have a well-
specified altitude, therefore, when testing the interoperability between one or more minifilters, there is
exactly one well-defined configuration to test.

An INF instance specification also has associated flags. If bit 1 is set, the minifilter will not be automatically
notified when volumes appear in the system so that it can attach its instance. An instance with this flag set

Page 4 of 28
in its specification would be manually attached via a Filter Manager API. If bit 2 is set, the minifilter will not
be asked to attach this instance to a volume when a manual attachment request is made.

6. Instance Notification Support

A set of callbacks are provided to notify a minifilter when an instance is being created or torn down. Through
these callbacks, the minifilter can control when instances are attached and detached from volumes.

6.1. Setting up an Instance

The InstanceSetupCallback() routine gets called for the following reasons:

• When a minifilter is loaded it is called for each volume that currently exists in the system.

• When a new volume is mounted.

• When FltAttachVolume() is called (kernel mode).

• When FltAttachVolumeAtAltitude() is called (kernel mode).

• When FilterAttach() is called (user mode).

• When FilterAttachAtAltitude() is called (user mode).

It is during the processing of the InstanceSetupCallback() that the minifilter decides whether or not the
instance should be created on the volume specified. This callback has the following signature:
typedef NTSTATUS
(*PFLT_INSTANCE_SETUP_CALLBACK) (
IN PCFLT_RELATED_OBJECTS FltObjects,
IN FLT_INSTANCE_SETUP_FLAGS Flags,
IN DEVICE_TYPE VolumeDeviceType,
IN FLT_FILESYSTEM_TYPE VolumeFilesystemType
);
The FltObjects structure contains pointers to the minifilter, volume and instance that define the instance
being created by this InstanceSetupCallback(). The Flags explain what operation triggered this
InstanceSetupCallback():
• FLTFL_INSTANCE_SETUP_AUTOMATIC_ATTACHMENT: This is an automatic attachment that is
occurring because the minifilter has just registered; therefore the Filter Manager is enumerating all
existing volumes in the systems for the newly loaded minifilter. This flag is not set when a user
explicitly request an instance to attach to a volume.

• FLTFL_INSTANCE_SETUP_MANUAL_ATTACHMENT: A manual attachment request has been issued

via the FilterAttach() (user-mode), FilterAttachVolumeAtAltitude() (user-mode),
FltAttachVolume() (kernel-mode), or FltAttachVolumeAtAltitude() (kernel-mode) call.
• FLTFL_INSTANCE_SETUP_NEWLY_MOUNTED_VOLUME: The file system has just mounted this
volume, therefore it is calling the InstanceSetupCallback() for the minifilter to create an
instance on the volume if desired.

During the InstanceSetupCallback(), the minifilter also receives the VolumeDeviceType and the
VolumeFilesystemType to help the minifilter decide whether or not it is interested in attaching to this volume.
From the InstanceSetupCallback(), a minifilter can query the volume properties by calling
FltGetVolumeProperties() and set a context using FltSetInstanceContext() on this instance if it
plans to attach this instance to the volume. It can also open and close files on the volume.

If the minifilter returns a success code from the instance setup callback, the instance will be attached to the
given volume. If the minifilter returns a warning or an error code, the instance will not be attached to the
volume.

If a minifilter does not register an InstanceSetup() routine, the system will treat this as if the user
returned STATUS_SUCCESS and allow the instance to be created on the volume.

Page 5 of 28
6.2. Controlling Instance Teardown
The InstanceQueryTeardown() callback is called only when a manual detach request is made. The
following operations cause manual detach requests:

• FltDetachVolume() (kernel-mode)
• FilterDetach() (user-model)
If a minifilter does not provide this callback than manual detach is not supported. However, volume
dismounts and minifilter unloads will still be allowed.

If this callback is defined and a success code is returned, Filter Manager will start tearing down the given
instance. Eventually the instance's InstanceTeardownStart() and InstanceTeardownComplete()
routines will be called. If the minifilter returns a warning/error status, the manual detach will fail. The
recommended error code is STATUS_FLT_DO_NOT_DETACH but any failure status may be
returned.
The signature for the InstanceQueryTeardown() callback is as follows:
typedef NTSTATUS
(*PFLT_INSTANCE_QUERY_TEARDOWN_CALLBACK) (
IN PCFLT_RELATED_OBJECTS FltObjects,
IN FLT_INSTANCE_QUERY_TEARDOWN_FLAGS Flags
);
As in the InstanceSetupCallback(), the FltObjects specify the minifilter, volume and instance to
which this InstanceQueryTeardown() operation is related.

6.3. Synchronizing Instance Detach

Once the decision to detach has been made the InstanceTeardownStart() callback is called. This routine
must do the following things:
• Restart any pended I/O operations (both pre & post operations)
• Guarantee no new I/O operations will be pended
• Start doing minimal work on new operations as they arrive.
This routine may also do the following work:
• Close opened files
• Cancel filter initiated I/O’s
• Stop queuing new work items
The minifilter then returns control back to the Filter Manager to continue its teardown processing.
After all operations in which this instance participated have drained or completed, the
InstanceTeardownComplete() callback is called to allow the minifilter to do the final cleanup for the
teardown of this instance. When InstanceTeardownComplete() is called, the Filter Manager guarantees
that all existing operation callbacks have been completed for this instance. At this time, the minifilter must
close any files it still has open that are associated with this instance.
The InstanceTeardownStart() and InstanceTeardownComplete() callbacks have the same
signature:

typedef VOID
(*PFLT_INSTANCE_TEARDOWN_CALLBACK) (
IN PCFLT_RELATED_OBJECTS FltObjects,
IN FLT_INSTANCE_TEARDOWN_FLAGS Reason
);
The FltObjects parameter describes the minifilter, volume and instance of interest for the callback. The
Reason parameter describes the reason for this teardown callback and may be a combination of the following
flag values:

Page 6 of 28
 • FLTFL_INSTANCE_TEARDOWN_MANUAL: This teardown operation is the result of a manual request
to detach this instance (FilterDetach() or FltDetachVolume()).

• FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD: This teardown operation is the result of the

minifilter being unloaded and the minifilter could have chosen to fail the unload request.

• FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD: This teardown operation is the

result of the minifilter being unloaded and the minifilter could not have chosen to fail the unload
request.

• FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT: This teardown request is the result of the

volume being dismounted.

• FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR: This teardown request is the result of some

error that occurred while trying to setup the instance, like insufficient memory.

Notice that there is no return value — the InstanceTeardownStart() and

InstanceTeardownComplete() cannot be failed. The Filter Manager guarantees that these callbacks will
be called at passive IRQL.

7. Callback Support
7.1. Callback data
The callback data structure is the new I/O packet descriptor for the Filter Manager, and it is analogous to the
IRP in the legacy model. Minifilters talk to Filter Manager and each other via this structure. Unlike an IRP
however, minifilters do not manage stack locations but instead indicate how the callback data should be
managed via well-defined Filter Manager interfaces and return status values to the Filter Manager.

The FLT_CALLBACK_DATA type describes all the information provided to a minifilter to describe an I/O. The
following description goes through each field in this structure to describe the information it contains.

Flags: Provides information about this operation. One or more of the following flags could be set in a
callback data structure:

• FLTFL_CALLBACK_DATA_IRP_OPERATION: This callback data structure represents an IRP

operation.

• FLTFL_CALLBACK_DATA_FAST_IO_OPERATION: This callback data structure represents a FAST IO

operation.

• FLTFL_CALLBACK_DATA_FS_FILTER_OPERATION: This callback data structure represents an

FsFilter operation.

• FLTFL_CALLBACK_DATA_SYSTEM_BUFFER: The buffer for the operation described by this callback

data is a system allocated buffer.

• FLTFL_CALLBACK_DATA_GENERATED_IO: This callback data represents an operation that was

generated by another minifilter.

• FLTFL_CALLBACK_DATA_REISSUED_IO: This callback data represents an operation that has been

sent back down to the file system by a minifilter instance above the current instance in the stack.

• FLTFL_CALLBACK_DATA_DRAINING_IO: Only set for a post-operation callback, this callback data

represents an IO operation that is being drained so that the minifilter can unload.

• FLTFL_CALLBACK_DATA_POST_OPERATION: Only set for a post-operation callback, this callback

data is currently in the post-operation processing for this I/O.

• FLTFL_CALLABACK_DATA_DIRTY: This is set after a minifilter has changed one or more of the
changeable parameters for this operation. This flag is only set during pre-operation processing.
Minifilters should use FLT_SET_CALLBACK_DATA_DIRTY() and
FLT_CLEAR_CALLBACK_DATA_DIRTY() to manipulate this flag.
Thread: The address of the thread which initiated this operation.

Page 7 of 28
Iopb: Pointer to the changeable parameters for this operation. This structure is described in more detail
later in this document.

IoStatus: The IO_STATUS_BLOCK which will receive the final status for this operation. If a minifilter wants
to complete an operation, the status should be set in this field before completing the operation. For
operations that are passed through to the file system, this field contains the final status of the operation
during post-operation processing.

TagData: This field is only valid in post-callback processing for CREATE operations when the target file of
the operation has a reparse point set on it.

QueueLinks: The list entry structure used to add this callback data structure to a work queue if needed.

QueueContext[2]: An array of PVOID structures to allow additional context to be passed to the work queue
processing routine.

FilterContext[4]: An array of PVOID structures that can be used as desired by a minifilter if this callback
data has been queued in a manner that does not rely on the queuing infrastructure provided by the Filter
Manager.

RequestorMode: The requestor mode of the caller who initiated this IO operation.

The FLT_IO_PARAMETER_BLOCK is the structure pointed to by the Iopb field of the callback data structure
and contains the changeable portion of the callback data structure. To extend the IRP analogy, this is like the
“current stack location” of the IRP. Minifilters should access this structure to retrieve I/O parameters in both
pre- and post-callbacks. The following is a more detailed description of the fields this structure contains.

IrpFlags: The flags from the IRP which describe this operation. These flags begin with the IRP_ prefix.

MajorFunction: The IRP_MJ function which describes this operation.

MinorFunction: The IRP_MN function which describes this operation.

OperationFlags: The flag values in the IO_STACK_LOCATION.Flags field in the legacy filter model. These
flags being with the SL_ prefix.

TargetFileObject: The file object which represents the file stream which this operation affects.

TargetInstance: The instance to which this IO is directed.

Parameters: The FLT_PARAMETERS union describes parameters specific to the operation specified in the
MajorFunction and MinorFunction fields.

Minifilters may change any of the parameters in the FLT_IO_PARAMETER_BLOCK except the
MajorFunction in the pre-callbacks. If parameters have been changed, the minifilter should call
FLT_SET_CALLBACK_DIRTY() to indicate this change. More information regarding changing the
parameters of an operation are in Section 8.

Minifilters will see the same parameters in both their pre- and post-callback routines for the same I/O — even
though they or other minifilters below may have changed the parameters. This is guaranteed by the Filter
Manager. Although the contents of the FLT_IO_PARAMETER_BLOCK will be the same in the pre- and post-
callback routines for the same I/O, the address to the FLT_IO_PARAMETER_BLOCK may not be the same,
therefore minifilters should not rely on this.

The callback data structure also contains the IO_STATUS_BLOCK that describes the status of the operation.
A minifilter can change this value and it will be honored by the Filter Manager without marking the callback
data dirty. The minifilter should set the status for the operation if it is completing the operation in its pre-
operation callback or undoing the operation in the post-operation callback.

7.2. Pre-Operation Callbacks

All pre-operation callbacks have the same signature:
typedef FLT_PREOP_CALLBACK_STATUS
(*PFLT_PRE_OPERATION_CALLBACK) (
IN OUT PFLT_CALLBACK_DATA Data,
IN PCFLT_RELATED_OBJECTS FltObjects,

Page 8 of 28
 OUT PVOID *CompletionContext
);
All pre-operation callbacks return an FLT_PRE_OPERATION_CALLBACK_STATUS. The values are defined as
follows:

• FLT_PREOP_SUCCESS_WITH_CALLBACK: The operation succeeded and the minifilter wants to have its
post-operation callback called.

• FLT_PREOP_SUCCESS_NO_CALLBACK: The operation succeeded, but the minifilter does not want to
have its post-operation callback called.

• FLT_PREOP_PENDING: The minifilter driver will complete the operation (by calling
FltCompletePendedPreOperation()) sometime in the future. There is no need for the minifilter to
call any special preparation routine before returning this status, like IoMarkIrpPending() in the
legacy filter model. If this status is returned, all further processing on the I/O is suspended by the Filter
Manager (i.e. no pre-callbacks of lower drivers are called etc.) until
FltCompletePendedPreOperation() is called.
• FLT_PREOP_COMPLETE: The minifilter completed the operation. The minifilter sets the I/O status of the
operation in Data->IoStatus.Status. Minifilters attached below this minifilter, legacy filters, and the
base file system will not see this I/O. Minifilters attached above this minifilter will see the operation
complete with the appropriate status. For CLEANUP and CLOSE operations, it is incorrect for a minifilter
to complete these operations with a failure status since these operations cannot fail.

• FLT_PREOP_SYNCHRONIZE: This status is valid only for non-create operations (creates are automatically
synchronized). A minifilter MUST have a post-callback for the operation when this status is returned.
This indicates that the minifilter wants this I/O to be completed in the same thread context as the pre-
operation process. The post-callback will be called after the I/O is completed in this thread context.
Filter Manager guarantees this — regardless of whether a lower filter/file system may pend the I/O or
abort completion processing etc. This status should be used with care because it requires Filter Manager
tosynchronizes the entire I/O and this has negative performance impacts on the systems overall
throughput.

• FLT_PREOP_DISALLOW_FAST_IO: This status is valid only for fast I/O operations that return BOOLEAN
in the legacy model. This status indicates to I/O to retry the operation using the IRP path instead.

Filters may change the parameters for the I/O before returning from the pre-operation callback. However the
only parameters that may be changed are in the Data->Iopb structure (FLT_IO_PARAMETER_BLOCK).
When a minifilter changes any of the parameters in this structure, it needs to issue
FLT_SET_CALLBACK_DATA_DIRTY() on the passed in CallbackData, or the changes will not be honored,
and unpredictable failures may occur.

There are a couple exceptions to this. If a minifilter is completing the operation or changing the operations
status, it may set the IoStatus appropriately in the callback data structure and it is not necessary to mark
the callback data dirty for this change to be honored by the Filter Manager.

Another exception is during the post-operation processing of IRP_MJ_CREATE operations. When a reparse
point is encountered, the Data->TagData will point to the reparse data buffer. If a minifilter wishes to
change this buffer in any way, it can free the existing buffer and replace Data->TagData with a new buffer
(or NULL) without calling FLT_SET_CALLBACK_DATA_DIRTY().

7.3. Post-Operation Callbacks

All post-operation callbacks have the same signature:
typedef FLT_POSTOP_CALLBACK_STATUS
(*PFLT_POST_OPERATION_CALLBACK) (
IN OUT PFLT_CALLBACK_DATA Data,
IN PCFLT_RELATED_OBJECTS FltObjects,
IN PVOID CompletionContext,
IN FLT_POST_OPERATION_FLAGS Flags
);

Page 9 of 28
The flag FLTFL_CALLBACK_DATA_POST_OPERATION is set in the Data->Flags field for post-operation
callbacks.

If a minifilter returns FLT_PREOP_SUCCESS_WITH_CALLBACK from its pre-operation callback, it is

guaranteed to receive exactly one completion callback per pre-operation callback. Post operations can return
a status of type FLT_POSTOP_CALLBACK_STATUS. The values are:

• FLT_POSTOP_FINISHED_PROCESSING —The minifilter has completed its processing of the request and
control should be returned to whoever initiated the I/O.

• FLT_POSTOP_STATUS_MORE_PROCESSING_REQUIRED — The minifilter has not completed its

processing of the request, and will later complete the request using
FltCompletePendedPostOperation().
Like completion routines in the legacy filter model, post-operation callback routines can be called at DPC. If a
minifilter needs to do work once the operation is completed but this work cannot be performed at DPC, the
minifilter can call FltDoCompletionProcessingWhenSafe(). This routine will queue this work to a
worker thread only if it is necessary (i.e., we are at DPC_LEVEL) and it is safe to do so. This call can fail if the
completion processing must be queued to a worker thread, but this is an I/O that cannot be queued (e.g.,
paging I/Os).

For filters who want to cancel an opened file in the post-operation callback, FltCancelFileOpen() is
provided which does a cleanup and close on the specified FileObject on behalf of the minifilter. The minifilter
should fill in an appropriate error status code and return FLT_POSTOP_FINISHED_PROCESSING from its
post-operation callback.

When an instance is being torn down, the Filter Manager may call the post-operation callback before it is
actually completed by the lower filters or file system. In this case, the flag
FLTFL_POST_OPERATION_DRAINING will be set when the post-operation is called. Minimal information
about the operation will be provided, so at this time, the minifilter should cleanup any operation context
passed in from its pre-operation and return FLT_POSTOP_FINISHED_PROCESSING.

The operations defined are based on the IRP_MJ codes with the addition of some new codes to represent Fast
I/O operations that have no IRP equivalents. The goal is to present IRP-based and Fast I/O operations in a
consistent manner to the minifilter. There will be a flag in the callback data so that it can determine the
difference between an Irp-based, FsFilter based, or Fast I/O based operation, but it will not have to register
separate callbacks for operations that are similar (i.e., Reads, Writes, and Locking operations).

The operations for which pre- and post-operation callbacks can be provided are:

• All the existing IRP_MJ codes from IRP_MJ_CREATE to IRP_MJ_PNP

• IRP_MJ_FAST_IO_CHECK_IF_POSSIBLE
• IRP_MJ_NETWORK_QUERY_OPEN
• IRP_MJ_MDL_READ
• IRP_MJ_MDL_READ_COMPLETE
• IRP_MJ_PREPARE_MDL_WRITE
• IRP_MJ_MDL_WRITE_COMPLETE
• IRP_MJ_VOLUME_MOUNT
• IRP_MJ_VOLUME_DISMOUNT
• IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION
• IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION
• IRP_MJ_ACQUIRE_FOR_MOD_WRITE
• IRP_MJ_RELEASE_FOR_MOD_WRITE
• IRP_MJ_ACQUIRE_FOR_CC_FLUSH
• IRP_MJ_RELEASE_FOR_CC_FLUSH

Page 10 of 28
A few special notes for some of the IRP_MJ codes:

• The pre-operation callback for IRP_MJ_CREATE can not set or get file, stream, or streamHandle contexts
as it is not yet determined at pre-create time what file or stream (if any) is going to be created.

• The post-operation callback for IRP_MJ_CLOSE will not be able to set or get contexts for file, stream, or
stream handle, as the system-internal structures with which they are associated are freed before the
post-close routine is called.

• IRP_MJ_CLEANUP and IRP_MJ_CLOSE must never be failed by the minifilter. They can be pended,
passed on, or completed with success. It is illegal to return FLT_PREOP_COMPLETE and fill in a failure
status in the IoStatus block.

• Post callbacks cannot fail, as the operation has already taken place. If the minifilter wishes to fail an
operation from the post-operation callback, it must take the necessary action to undo the operation that
has succeeded. For failing IRP_MJ_CREATE operations, the Filter Manager provides some help with the
FltCancelFileOpen() routine to teardown the opened file object, but the filter is still responsible to restore
any file contents that were lost by CREATE operation which overwrote the original file.

Any changes made to the operation parameters in the post-operation callbacks will not be honored by the
Filter Manager.

8. Manipulating Callback Data Parameters

8.1. I/O Parameter Block
As mentioned earlier, the callback data encapsulates two important data structures for the I/O.

1.) The I/O Status Block: Data->IoStatus is used to indicate the status of the operation when the
minifilter is completing the I/O by itself (or contains the status it can read in its post-callback if a
filter/filesystem below completed the I/O)

2.) The I/O Parameter Block: Data->Iopb points to the parameters that are specific to that minifilter for
the I/O.

This section will discuss accessing/changing the parameters in more detail.

The MajorFunction and MinorFunction in the Iopb indicate the IRP/FastIo/FsFilter major/minor function
for the operation. The MajorFunction may not be changed by the filters – Filter Manager does not support
it.

The TargetFileObject indicates the stream’s file object that the I/O is targeted to. This can be changed
by the minifilter (the minifilter must call FLT_SET_CALLBACK_DATA_DIRTY()) and will be honored.

The TargetInstance parameter is different from instance to instance as the I/O is passed down, and
indicates the current instance. However, filters can change this to point to another instance that they own, at
the same altitude on another volume. Again, FLT_SET_CALLBACK_DATA_DIRTY() must be called to have this
change honored.

Minifilters are NOT allowed to change the TargetInstance to an instance on the same volume. For example
consider a minifilter that has 2 instances on volume C:, one at altitude 200 called Sample_Instance_C_200,
and another at altitude 100, called Sample_Instance_C_100

Assume it also has another instance, called Sample_Instance_D_200 at altitude 200 on volume D:

Now suppose the IRP_MJ_READ pre-callback for the instance at altitude 200 on C: is called (i.e.,
TargetInstance points to Sample_Instance_C_200.) The minifilter can change the TargetInstance
parameter to point to Sample_Instance_D_200, in which case it is re-directing I/O to the D: volume. However
it should not change it to Sample_Instance_C_100.

This is to prevent filters from illegally bypassing other filters sitting below them on the same volume.

The parameters structure in the I/O parameter block contains operation-specific parameters. Minifilters must
use the operation-appropriate union to access them. For IOCTLs and FSCTLs, there are method-specific

Page 11 of 28
unions based on the method of the control code. Minifilters should test for the method explicitly and use the
appropriate union.

8.2. Accessing buffer/MDL

In the IRP world, buffers are passed to the drivers through a number of mechanisms. For device objects
which supported ‘neither’ I/O – which is the most common for file systems – the buffer was available via
Irp->UserBuffer. For device objects which only supported buffered I/O, the buffer was buffered by the IO
Manager and supplied via Irp->AssociatedIrp.SystemBuffer. For device objects that supported direct
I/O, the buffer was supplied via Irp->MdlAddress, a locked down MDL describing the buffer.

However, there are exceptions and certain IRPs passed the buffer directly through one of the stack location
parameters. In that case it could come from either kernel memory or raw user memory, independent of the
device object’s I/O requirements. These buffers are not passed to the hardware; hence, they ignored the
device object’s I/O support.

There are also certain IRPs which are always buffered – such as IRP_MJ_QUERY/SET_INFORMATION.

For minifilters, the buffers are always passed through the appropriate operation-specific union. There is no
‘common’ place where they can grab the buffer/MDL address from. This was designed to eliminate the
confusion with the location of the buffers.

The flag FLTFL_CALLBACK_DATA_SYSTEM_BUFFER is set in the callback data’s flag field if the operation is
buffered. If this flag is set, it indicates that the buffer is from non-paged pool.

If the flag is not set, it means the IO Manager is not buffering the operation. However it is possible that a
minifilter switched the buffers (see next section), so the buffer could still be from one of the system pools.
However if the flag is not set, filters should always assume that the buffer is a raw user-buffer. We will
discuss a rule in the next section that requires that a MDL describing the locked down pages will always be
present if the buffer is not a user-buffer in such a case, and that should be used by the caller to obtain a
system address to the buffer.

Finally, for those filters which wish to locate the buffer/length/MDL for the most common operations,
FltDecodeParameters() is provided which does a fast lookup and returns the pointer to the buffer
/MDL/length fields in the Parameter structures. For operations for which buffers are not applicable, this
routine returns STATUS_INVALID_PARAMETER.
NTSTATUS
FLTAPI
FltDecodeParameters(
IN PFLT_CALLBACK_DATA CallbackData,
OUT PMDL **MdlAddressPointer OPTIONAL,
OUT PVOID **Buffer OPTIONAL,
OUT PULONG *Length OPTIONAL,
OUT LOCK_OPERATION *DesiredAcces OPTIONAL
);
The DesiredAccess field indicates the kind of access to the buffer the minifilter can assume. For instance,
for IRP_MJ_READ, the DesiredAccess can indicate IoWriteAccess, implying that the buffer can be written
to. For IRP_MJ_WRITE, it’s usually IoReadAccess indicating the minifilter can potentially only read the
contents of the buffer but not modify it, since it is legal for an application to issue a write with a buffer that
has read/only access page-level protection.

Filters that wish to ensure the buffer is locked down, should follow these guidelines: if the
FLTFL_CALLBACK_DATA_SYSTEM_BUFFER flag is set, they may assume that the buffer is already locked
down and access it safely.

If it is not set they should call FltLockUserBuffer() to lock the pages down. This API will ensure that the
pages are locked down with the right access based on the operation, and if successful, it will set the
MdlAddress field in the operation-specific parameter portion, to the MDL describing the pages.

Page 12 of 28
8.3. Swapping buffers
Certain minifilters need to swap the supplied buffer for certain operations. Consider a minifilter that
implements custom encryption. On a non-cached IRP_MJ_READ, it normally wishes to decrypt the contents of
the buffer that was read from the filesystem. Similarly on a write, it wishes to encrypt the contents. Take the
latter case: the contents cannot be encrypted in place, because for IRP_MJ_WRITE, the maximal access to the
buffer that the minifilter can assume is IoReadAccess.

Hence the minifilter needs to supplant its own buffer which has read/write access, encrypt the contents of the
original buffer into the new one, and send the I/O down.

For this scenario, the Filter Manager supports buffer-switching. However there are a few rules to which the
minifilter must adhere:

1. Minifilters that switch a buffer must supply a post-callback. This is so that the buffer can be switched
back by Filter Manager automatically.

2. If the minifilter is switching the buffer for an operation for which

FLTFL_CALLBACK_DATA_SYSTEM_BUFFER flag was set, it MUST ensure that the new buffer is from
non-paged memory (i.e. either from non-paged pool or from locked down memory).

3. If the above flag was not set, minifilter must adhere to the requirements of the device (by looking at
the DeviceObjectFlags etc. in the volume properties) when supplanting the buffer, based on the
operation. For instance if it supports direct I/O, it must supply a MDL etc.

4. If the minifilter supplants a non-paged pool buffer for an operation for which the
FLTFL_CALLBACK_DATA_SYSTEM_BUFFER flag is not set, it must also build a MDL via
MmBuildMdlForNonPagedPool() and supply it in the MdlAddress field. This is so that a
filter/filesystem below will not attempt to lock non-paged pool (which can assert on checked
Windows builds, and is also not good from a performance perspective). If a MDL is supplied,
filters/file systems will always access the buffer through the MDL (by obtaining a system address for
it).

5. When switching a buffer, the minifilter should also switch the MDL (i.e. the buffer and the MDL must
be in sync). It is fine to leave the MDL NULL subject to the usual direct I/O exceptions.

6. Minifilter should NOT free the old buffer/old MDL.

7. Minifilter should NOT attempt to switch back the old buffer /MDL in its post-callback. Filter Manager
does this automatically. In fact the buffer/MDL the minifilter sees in the Iopb in its post-callback are
the original ones. Minifilters can remember the switched buffer by passing it in via their completion
context.

8. Minifilters are expected to free the buffer they allocated (and supplanted) in the post-callback. Filter
Manager however, will automatically free the MDL for the swapped buffer if any.

9. Minifilters that do not want Filter Manager to automatically free the MDL for the swapped buffer can
call FltRetainSwappedBufferMdl().

10. Minifilters that wish to access the swapped buffer’s MDL can use FltGetSwappedBufferMdl() in
the post-callback. Since a filter/filesystem below the minifilter that swapped the new buffer in, may
potentially create a MDL for it, Filter Manager saves any such MDL for the swapped buffer before
calling the post-callback for the minifilter that swapped the buffers. This API can be used to access
the MDL in that case.

9. Context Support
All filters need to track their own state as different objects in the system are being operated on. One of the
features of the Filter Manager is the ability for it to track these contexts on behalf of a minifilter.

A context is a piece of dynamically allocated memory that is created by calling FltAllocateContext().

The caller specifies the amount of memory to allocate and is returned a pointer to this memory. The system
attaches an internal header used for tracking the context in front of the returned pointer.

Contexts can be created for the following types of objects:

Page 13 of 28
• Volume — This represents a mounted device in the system.

• Instance — This is a minifilter's attachment to a given volume. A minifilter may attach more then once
to a given volume. If a minifilter supports only once instance per volume, it is recommended that
instance contexts be used instead of volume contexts because they are more efficient.

• File — This represents all opens across all data streams of a file. Currently these contexts are not
supported.

• Stream — This represents all opens across a single data stream of a file.

• StreamHandle — This represents a single open of a file, i.e., a file object.

9.1. Context Registration

At registration time, a minifilter defines the types of contexts it will use, the size of the context and the
routine used to cleanup that context. The minifilter uses an array of FLT_CONTEXT_REGISTRATION
structures to define these parameters.

The FLT_CONTEXT_REGISTRATION structure is explained in detail below:

ContextType: The type of context this context registration describes.

Flags: The flags to denote special handling for this context. The flags currently defined are:

• FLTFL_CONTEXT_REGISTRATION_NO_EXACT_SIZE_MATCH: By default, the Filter Manager

matches exactly a given context allocation request with a size specified at context registration time.
If this flag is specified, Filter Manager will use the allocation routine specified if the requested
allocation size is less than or equal to the size specified in the registration entry. This flags is
ignored for entries where the size is specified as FLT_VARIABLE_SIZED_CONTEXTS or allocation
and free routines are specified.

CleanupContext: The routine to be called when the Filter Manager determines that it is time to cleanup this
context. This may be NULL if no cleanup is required before this context is freed.

Size: The size in bytes for this context. This is used to allow the Filter Manager to use pooling techniques
(such as look aside lists) to make the allocation and freeing of these structures more efficient. This field
is ignored if Allocate and Free routines are specified.

PoolTag: The pool tag the minifilter would like to associate with context allocations of this type. This field is
ignored if Allocate and Free routines are specified.

Allocate: This should be set to a non-NULL value if the minifilter would like to specify its own allocation
routine. If the minifilter would like to rely on the Filter Manager’s pooling techniques for allocation, this
should be set to NULL.

Free: This should be set to a non-NULL value if the minifilter would like to specify its own free routine.

If a minifilter has contexts of the same type that may be variable sizes, it can register up to 3 different
FLT_CONTEXT_REGISTRATION structures for the same context type to make use of the Filter Manager
supported memory pooling support.

9.2. Context Creation APIs

Following is the prototype definition for FltAllocateContext():
NTSTATUS
FLTAPI
FltAllocateContext (
IN PFLT_FILTER Filter,
IN FLT_CONTEXT_TYPE ContextType,
IN SIZE_T ContextSize,
IN POOL_TYPE PoolType,
OUT PFLT_CONTEXT *ReturnedContext
);

Page 14 of 28
The ContextType can be one of the following for a context on the associated object: FLT_VOLUME_CONTEXT,
FLT_INSTANCE_CONTEXT, FLT_FILE_CONTEXT, FLT_STREAM_CONTEXT, or FLT_STREAMHANDLE_CONTEXT.

The following set context routines are used to attach a context to an object. The context being attached must
match the type of the object.
NTSTATUS
FLTAPI
FltSetVolumeContext (
IN PFLT_VOLUME Volume,
IN FLT_SET_CONTEXT_OPERATION Operation,
IN PFLT_CONTEXT NewContext,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltSetInstanceContext (
IN PFLT_INSTANCE Instance,
IN FLT_SET_CONTEXT_OPERATION Operation,
IN PFLT_CONTEXT NewContext,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltSetFileContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
IN FLT_SET_CONTEXT_OPERATION Operation,
IN PFLT_CONTEXT NewContext,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltSetStreamContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
IN FLT_SET_CONTEXT_OPERATION Operation,
IN PFLT_CONTEXT NewContext,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltSetStreamHandleContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
IN FLT_SET_CONTEXT_OPERATION Operation,
IN PFLT_CONTEXT NewContext,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);
When a context is being set there are 2 types of operations that can occur. They are:

Page 15 of 28
• FLT_SET_CONTEXT_KEEP_IF_EXISTS: If there is no existing context, the new context will be set. If
there is an existing context the new context will not be set and an error will be returned. If the
OldContext parameter is defined the existing context will be returned. The caller must release the
returned context if any. If the new context was not set the caller must also release that context.

• FLT_SET_CONTEXT_REPLACE_IF_EXISTS: This will set a new context even if a context already exists.
If the OldContext parameter is defined the context being replaced will be returned. The caller must
release the returned context. If the OldContext parameter is not defined then the old context will be
released by the filter manager.

While the Filter Manager will call the minifilter at the appropriate time to cleanup a context because the object
to which it is associated has been freed by the operating system, the minifilter may want to delete a context
on an object at some other time. To do this, the minifilter should call one of the following routines to delete
the appropriate context if they already have the pointer to the context:

VOID
FLTAPI
FltDeleteContext (
IN PFLT_CONTEXT Context
);
If the minifilter does not have the context, it can also delete the context by specifying the object to which the
context is attached using the appropriate API below:

NTSTATUS
FLTAPI
FltDeleteVolumeContext (
IN PFLT_FILTER Filter,
IN PFLT_VOLUME Volume,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltDeleteInstanceContext (
IN PFLT_INSTANCE Instance,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltDeleteFileContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS
FLTAPI
FltDeleteStreamContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);

NTSTATUS

Page 16 of 28
FLTAPI
FltDeleteStreamHandleContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
OUT PFLT_CONTEXT *OldContext OPTIONAL
);
If the option OldContext parameter is NULL, the Filter Manager will release the residual reference on the
context. Otherwise, the context will be returned via the OldContext parameter and the minifilter is
responsible for calling FltReleaseContext() on this context when it has finished using it.

9.3. Context Retrieval APIs

The following routines can be used to retrieve a context for an individual object. The caller must release the
returned context by calling FltReleaseContext() when it is done using it. Contexts can not be retrieved
at DPC level so if a context is needed in a post-operation callback it may need to be passed from the pre-
operation callback.
NTSTATUS
FLTAPI
FltGetVolumeContext (
IN PFLT_FILTER Filter,
IN PFLT_VOLUME Volume,
OUT PFLT_CONTEXT *Context
);

NTSTATUS
FLTAPI
FltGetInstanceContext (
IN PFLT_INSTANCE Instance,
OUT PFLT_CONTEXT *Context
);

NTSTATUS
FLTAPI
FltGetFileContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
OUT PFLT_CONTEXT *Context
);

NTSTATUS
FLTAPI
FltGetStreamContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
OUT PFLT_CONTEXT *Context
);

NTSTATUS
FLTAPI
FltGetStreamHandleContext (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
OUT PFLT_CONTEXT *Context
);

Page 17 of 28
The following routine is used to release a context when a minifilter is done using it. It is advised that a
minifilter not hold on to contexts across operations. Context tracking is very efficient and it is intended that a
minifilter query for desired contexts on each operation.
VOID
FLTAPI
FltReleaseContext (
IN PFLT_CONTEXT Context
);
As with the Instance notification routines, each operation callback routine receives a FLT_RELATED_OBJECTS
structure. This structure contains all known objects for the given operation. To simplify context retrieval
there is an equivalent FLT_RELATED_CONTEXTS which can be used to retrieve more then one context at a
time. This structure has the following definition:
typedef struct _FLT_RELATED_CONTEXTS {

PFLT_CONTEXT VolumeContext;
PFLT_CONTEXT InstanceContext;
PFLT_CONTEXT FileContext;
PFLT_CONTEXT StreamContext;
PFLT_CONTEXT StreamHandleContext;

} FLT_RELATED_CONTEXTS, *PFLT_RELATED_CONTEXTS;
The following two routine are used to get multiple contexts at once as well as release multiple contexts at
once. For FltGetContexts() the caller specifies (with the DesiredContexts parameter) which contexts
are wanted. Internally, there are performance advantages to getting multiple contexts at once versus getting
each context individually. Of course, if the minifilter does not need a context it is best not to request it. The
FLT_ALL_CONTEXTS definition can be used to return all available contexts.
VOID
FltGetContexts (
IN PFLT_RELATED_OBJECTS FltObjects,
IN FLT_CONTEXT_TYPE DesiredContexts,
OUT PFLT_RELATED_CONTEXTS Contexts
);

VOID
FltReleaseContexts (
IN OUT PFLT_RELATED_CONTEXTS Contexts
);

9.4. Context Freeing APIs

When the Filter Manager determines it is time for a context to be freed a minifilter supplied callback routine is
called. This routine should do any necessary cleanup on the contents of the given context structure (cleanup
other allocated memory, free resource, etc.). Upon returning from this routine the Filter Manager will free the
passed in context structure.

A separate cleanup routine is defined for each type of context. These routines have the following definition:
typedef VOID
(*PFLT_CONTEXT_CLEANUP_CALLBACK) (
IN PFLT_CONTEXT Context,
IN FLT_CONTEXT_TYPE ContextType
);
The same context free routine may be registered for multiple types of contexts.

Page 18 of 28
10. User Mode Communication
10.1. Filter Communication Port Object
To implement security and enable multiple communication channels, a new object has been introduced called
a minifilter communication port. It is intended to be used for kernel-user communication and vice versa.
Kernel-kernel communication is not presently supported. A port is a named NT object, with a security
descriptor.

Filter Manager creates a new object type, FilterConnectionPort, to facilitate this. Filter Manager creates this
new object type during its driver entry initialization before any minifilters are loaded.

Only kernel-mode drivers can create a minifilter communication port, with the following API:
NTSTATUS
FltCreateCommunicationPort(
IN PFLT_FILTER Filter,
OUT PHANDLE PortHandle,
IN POBJECT_ATTRIBUTES ObjectAttributes,
IN PVOID ServerPortCookie OPTIONAL,
IN PFLT_CONNECT_NOTIFY ConnectNotifyCallback,
IN PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
IN PFLT_MESSAGE_NOTIFY MessageNotifyCallback,
IN ULONG MaxConnections
);
The Filter is the handle to the filter object of the minifilter that is creating this communication port object.
The handle created by a successful call to FltCreateCommunicationPort() is returned in the
PortHandle parameter.
As with other NT objects, the ObjectAttributes parameter defines the OBJECT_ATTRIBUTES structure to
initialize the name, object attribute flags and security descriptor for the new communication port object being
created. Note that for the communication port objects, the object attribute OBJ_KERNEL_HANDLE must be
specified since this object can only be created as kernel objects.

The ServerPortCookie is a context that minifilters can associate with the port and this context is opaque
to the Filter Manager. All connect/disconnect notifications to the minifilter for this port will be passed this
cookie. This is useful for minifilters which create an array of ports since the cookie can be used to identify
which port in the array is being accessed without defining unique port notification routines for each port in the
array.

The caller also registers three callbacks when a communication port is created:

• ConnectNotifyCallback(): This will be called whenever a user mode process tries to open the
port. The minifilter will have the option to fail the connection request. The notify routine will receive
a handle that the minifilter must use for communicating on this connection. Each connection has a
unique handle. The ServerPortCookie associated with the server port will also be passed in. The
minifilter may fill in the ConnectionCookie argument with a context that will be passed in to all
further user-kernel messages and the disconnect routine for this connection.

• DisconnectNotifyCallback(): This will be called when the port is closed by user mode (i.e. the
handle count goes to zero).

• MessageNotifyCallback(): This is called whenever a message is received.

The MaxConnections specifies the maximum number of outstanding connections that will be allowed on this
communication port. There is no default value, but this value must be greater than 0.

There is no guarantee that the object name will be created in the root of the name space – it’s possible that
the Filter Manager may map it under the \FileSystem\Filters object directory internally. If such a
mapping occurs, it will be transparent to the minifilter and the user-mode application. When referencing the
communication port by name, both components should use the same name. The Scanner minifilter example
show how this is done.

Page 19 of 28
In association with the new object type, new access types will be introduced for objects of this type. The
minimal new access types are:

• FLT_PORT_CONNECT
• FLT_PORT_ALL_ACCESS
These are the access types that callers of this API can grant to users when constructing the security
descriptor for the object via InitializeObjectAttributes().

At the moment FLT_PORT_CONNECT will be sufficient to let user mode connect to the port and both send and
receive messages.

When a minifilter creates the port, it implicitly starts listening on the port for incoming connections. It
continues to listen until it closes the handle to the port by calling ZwClose().

10.2. Connecting to Communication Port from User

Mode
The minifilter communication port model – like the legacy model – is asymmetric. The kernel-mode end
creates the communication port. The user-mode end connects to it. There is an API to open the port for the
user-mode application. When a connection is established, the ConnectNotify() routine is called notifying
the minifilter of the connection creation request as well the minifilter end of the port handle that should be
used to send messages across this connection.

The prototype of the user-mode API to connect to the port is:

HRESULT
FilterConnectCommunicationPort(
IN LPWSTR lpPortName,
IN DWORD dwOptions,
IN LPVOID lpContext,
IN WORD wSizeOfContext,
IN LPSECURITY_ATTRIBUTES lpSecurityAttributes,
OUT HANDLE *hPort
);
The lpPortName is a pointer to a wide-character string that specifies the name of the port to which to
connect. This name should be the same name used by the minifilter which created the port. The port name
may start with a ‘\’ – indicating it is in the root directory. Filter Manager may however open it relatively in
the actual appropriate directory that hosts minifilter communication ports.

The dwOptions parameter is currently unused.

The lpContext is a pointer to an opaque parameter that will be passed to the minifilter’s
ConnectNotify() routine. This can be used to authenticate that the application requesting to create the
communication channel is the expected application of the appropriate version. The wSizeOfContext
specifies the size of lpContext in bytes.

The lpSecurityAttributes specifies the security attributes for the user end of the connection, and if the
handle will be inherited.

If the call is not successful, the appropriate HRESULT will be returned.

The returned handle may be closed/duplicated etc via the usual APIs. It can also be associated with an I/O
completion port.

When this API is called, a new kernel-mode only unnamed port object is created (of type
FilterCommunicationPort) that is used to represent the connection. The minifilter will be notified by
calling the ConnectNotify() routine it supplied in the create operation for the server port, and given the
handle to the connection port which should be used for sending messages from the kernel-side.

Of course if the caller does not have sufficient access to the server port, or the maximum number of
connections are exceeded this will fail appropriately.

Page 20 of 28
10.3. Disconnecting from the Communication Port
When the user-mode calls CloseHandle() on the handle obtained for the connection or the kernel-mode
side calls ZwClose() on the connection port handle, the connection is broken.

The minifilter’s DisconnectNotify() routine will be called only when the user mode closes its handle.

Ideally the minifilter should always close its end of the connection in the DisconnectNotify() routine. If a
minifilter closes the handle at other times, it should make sure the handle will not be double-closed in its
DisconnectNotify() by using some sort of synchronization.
When a communication port is disconnected on either the kernel or user-mode end:

1. Any user-mode waiters (via FilterGetMessage()) are flushed out and completed with
STATUS_FLT_PORT_DISCONNECTED (which translates to win32 error ERROR_DISCONNECTED )
2. Any kernel mode senders that are blocked on waiters are woken up and completed with
STATUS_FLT_PORT_DISCONNECTED
3. The port is ‘invalidated’ so no more futures waiters/senders will be allowed.

The minifilter can always close the server port by calling ZwClose() on the server port handle. This does
not force existing connections to break, but simply stops the minifilter from accepting any more connections.

10.4. Unload issues

Minifilters must always close the server side port handle in their FilterUnload() routines (or earlier)
before they call FltUnregisterFilter() to avoid system hangs during the unload process.

Minifilters will be permitted to unload even though there are connections open (i.e. the user-mode side has
handles open to the connections). If this is the case, the connections will be attempted to be forcibly
terminated by Filter Manager. The Filter Manager will call the DisconnectNotify() routine. The minifilter
is expected to close the kernel side handle to the connection in the DisconnectNotify() thereby
preventing a handle leak when the minifilter unloads.

11. File Name Support

The Filter Manager provides library routines that retrieve the name of the object in the current operation
through looking at the operation parameters or querying the file system. For improved efficiency, the Filter
Manager also caches the names as they are retrieved so that the cost of generating a file name can be
amortized among all minifilters interested in that name.

The Filter Manager name APIs return names in FLT_FILE_NAME_INFORMATION structures so as to avoid
data copies when a minifilter requests a name. These structures are reference counted and possibly shared
by multiple minifilters requesting names. Only the Filter Manager APIs should ever change the data in these
structures. There is more information about these structures in the following sections.

11.1. Retrieving a File Name during an Operation

To retrieve a file name for the CallbackData->Iopb->TargetFileObject for the current operation, the
minifilter should call the following routine:
NTSTATUS
FLTAPI
FltGetFileNameInformation (
IN PFLT_CALLBACK_DATA CallbackData,
IN FLT_FILE_NAME_FORMAT NameFormat,
IN FLT_FILE_NAME_QUERY_METHOD QueryMethod,
OUT PFLT_FILE_NAME_INFORMATION *FileNameInformation
);
The CallbackData is the FLT_CALLBACK_DATA structure for the operation on the FileObject for which the
minifilter wants to query the name.

Page 21 of 28
The NameFormat is one of the following three formats:

• FLT_FILE_NAME_NORMALIZED_FORMAT: A name requested in this format contains the full path for
the name, including the volume name. All short names in the path have been expanded to their long
name. Any stream name component will have any trailing “:$DATA” removed. If this is the name
for a directory other than the root directory, the final ‘\’ in the path will be removed.

• FLT_FILE_NAME_OPENED_FORMAT: A name requested in this format contains a full path for the
name, including the volume name, but the name is in the same format that the caller used to open
this object. Therefore, it could include short names for any of the components in the path.

• FLT_FILE_NAME_SHORT_FORMAT: A name requested in this format contains the short name (DOS
name) for only the final component of the name. The full path for this object is not returned.

The QueryMethod is one of the following:

• FLT_FILE_NAME_QUERY_DEFAULT: When looking for a name, the Filter Manager will look in the
cache first to find the name, then, if possible, query the file system to retrieve the name requested.

• FLT_FILE_NAME_QUERY_CACHE_ONLY: When looking to fulfill a name request, the Filter Manager

will only look in the name cache to find the name. If the name is not found,
STATUS_FLT_NAME_CACHE_MISS will be returned.
• FLT_FILE_NAME_QUERY_FILE_SYSTEM_ONLY: When looking to fulfill a name request, the Filter
Manager will not look in the name cache and query the file system for the name if possible.

The name is returned in the final parameter, FileNameInformation. This structure is a set of Unicode
strings that share the same buffer. The various Unicode strings denote varying sections of the name.
typedef struct _FLT_FILE_NAME_INFORMATION {
USHORT Size;
FLT_FILE_NAME_FORMAT Format;
FLT_FILE_NAME_PARSED_FLAGS NamesParsed;
UNICODE_STRING Name;
UNICODE_STRING Volume;
UNICODE_STRING Share;
UNICODE_STRING Extension;
UNICODE_STRING Stream;
UNICODE_STRING FinalComponent;
UNICODE_STRING ParentDir;
} FLT_FILE_NAME_INFORMATION, *PFLT_FILE_NAME_INFORMATION;
When a file name information structure is returned from FltGetFileNameInformation(), the Name,
Volume, and Share (for remote file names) will be parsed. If a minifilter needs the other names parsed, it
should call FltParseFileNameInformation().

A minifilter can call FltGetFileNameInformation() at any point during its IO processing when it is
executing an IRQL less than DPC. If the minifilter is requesting to query the name at a time when it is
possible for the name query to cause the system to deadlock (e.g., while processing paging IO), the call will
fail if the name is not found in the cache or the caller requested to only query the file system.

A minifilter can use FltGetFileNameInformationUnsafe() to query a name for a file object if it does not
have a callback data to describe the current operation targeting this file object and the filter knows that this is
a safe time to potentially query the file system to get a name. This routine cannot detect that a file system
query could potentially deadlock the system and return a failure status as
FltGetFileNameInformation() can.
When a minifilter is finished using the name, it should be released by calling:
FLTAPI
FltReleaseFileNameInformation (
IN PFLT_FILE_NAME_INFORMATION FileNameInformation
);

Page 22 of 28
Filter Manager’s name cache is designed to be efficient enough for minifilters to query the name during the
operations it needs to process. The name cache manages the invalidation of names due to file or directory
renames. Minifilters are isolated from the complex logic necessary to maintain a name cache, but minifilters
still need to be aware that names can be invalidated by renames in the system. When a rename occurs, the
Filter Manager purges any affected cached entries, but minifilters may have outstanding references to the
now stale file name information structure. When all the references are released the stale file name
information structure will be freed. If a minifilter queries a name on an object that has been renamed, the
new name will be returned if possible.

11.2. Additional Support for File Names

The Filter Manager also provides an API to help minifilters retrieve the destination name for rename and
hardlink creation operations:
NTSTATUS
FltGetDestinationFileNameInformation (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
IN HANDLE RootDirectory OPTIONAL,
IN PWSTR FileName,
IN ULONG FileNameLength,
IN FLT_FILE_NAME_FORMAT NameFormat,
IN FLT_FILE_NAME_QUERY_METHOD QueryMethod,
OUT PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);
This API should be used during a minifilters pre-operation callback for IRP_MJ_SET_INFORMATION,
FileSetNameInformation or FileSetLinkInformation. The caller specifies the parameters from the operation,
and the Filter Manager will return a FLT_FILE_NAME_INFORMATION structure that contains the destination
name for the operation in the format requested. Just as with FltGetFileNameInformation(), the
minifilter must call FltReleaseFileNameInformation() when it is finished using the name returned.

Name tunneling is another aspect of file names where filter commonly make mistakes. The Filter Manager
provides the following API to detect and retrieve a new name when needed due to name tunneling:
NTSTATUS
FltGetTunneledName (
IN PFLT_CALLBACK_DATA CallbackData,
IN PFLT_FILE_NAME_INFORMATION FileNameInformation,
OUT PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);
Name tunneling will only affect a minifilter that is working with names in normalized format. If a minifilter
needs a normalized name in its pre-operation callback for CREATE, rename or hardlink creation operations, it
should call FltGetTunneledName() in its post-operation callback to validate that the name provided in the
pre-operation callback was not affected by name tunneling in the file system. If name tunneling did occur, a
new file name information structure is returned in RetTunneledFileNameInformation. The minifilter
should use this name for its name processing and call FltReleaseFileName() on this structure when
complete.

11.3. Interfaces for Name Providing Filters

If a filter is interested in providing a way to change the name space, it will need to register three name
additional callbacks with the Filter Manager. These callbacks allow the name providing filter to be responsible
for providing the name content for the FLT_FILE_NAME_INFORMATION structure that is returned when a higher
filter calls FltGetFileNameInformation or FltGetDestinationFileName. The name providing filter will also
be able to tell the Filter Manager whether or not the name being returned should be cached.

As a name provider, the filter needs to be able to return a name for a given file object in the opened name
format. The filter manager will do the work of iterating through the components in the name and then call
the name provider back to expand components as necessary to generate a normalized name if that format
was requested. In the process of expanding all the components for a given path, the filter’s name component
normalization routine may be called more than once. The filter is allowed to provide a context that will be

Page 23 of 28
passed to future calls of the name component normalization routine while normalizing the current file name
path. At the end of all the processing, the filter will be asked to cleanup this context if it was returned.

When the name providing filter must provide a name, its PFLT_GENERATE_FILE_NAME routine will be called.
The filter is given the parameters for this name query, such as the file object for this query, the filter’s
instance which is receiving this query, the callback data describing the operation if one is present, and the
name query options which the caller requested be used. The filter then must generate the name
typedef NTSTATUS
(*PFLT_GENERATE_FILE_NAME) (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject,
IN PFLT_CALLBACK_DATA CallbackData OPTIONAL,
IN ULONG NameOptions,
OUT PBOOLEAN CacheFileNameInformation,
OUT PFLT_NAME_CONTROL FileName
);

typedef NTSTATUS
(*PFLT_NORMALIZE_NAME_COMPONENT) (
IN PFLT_INSTANCE Instance,
IN CONST PUNICODE_STRING ParentDirectory,
IN USHORT VolumeNameLength,
IN CONST PUNICODE_STRING Component,
IN OUT PFILE_NAMES_INFORMATION ExpandComponentName,
IN ULONG ExpandComponentNameLength,
IN OUT PVOID *NormalizationContext
);

typedef VOID
(*PFLT_NORMALIZE_CONTEXT_CLEANUP) (
IN PVOID *NormalizationContext
);
If a filter which provides names needs to invalidate all cached entries that it provided, it can do so through
the following API. If other filters are still using a FLT_FILE_NAME_INFORMATION structure provided by the
name providing filter after the name provider has requested for the name to be invalidated, the memory will
be freed once the FLT_FILE_NAME_INFORMATION structure’s reference count goes to 0.,
NTSTATUS
FltPurgeFileNameInformationCache (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject OPTIONAL
);
To ensure that a name providing filter is able to unload, the Filter Manager will be responsible for managing
the caching and freeing of names that are generated by name providing filters.

The Filter Manager will do the work of initializing the FLT_FILE_NAME_INFORMATION structure returned to the
caller of FltGetFileNameInformation or FltGetDestinationFileName based on the name returned by the
name providing filter.

For efficiency reasons, the Filter Manager passes in a buffer in which the name provider is to put the name
when its PFLT_GENERATE_FILE_NAME callback is called. This buffer is a UNICODE_STRING wrapped in a
FLT_NAME_CONTROL structure which contains both public and private information. Before a filter tries to fill
this buffer with data, it must check to see if the buffer is large enough for the data by calling:
NTSTATUS
FltCheckAndGrowNameControl (
IN OUT PFLT_NAME_CONTROL NameCtrl,
IN USHORT NewSize
);

Page 24 of 28
If this routine returns STATUS_SUCCESS, the buffer in the FLT_NAME_CONTROL structure is large enough to hold
the name from the name provider.

12. Filter Initiated I/O

Certain minifilters need to perform I/O of their own. This I/O is only seen by minifilters below the current
minifilter in the minifilter stack of the Volume. For instance, an anti-virus minifilter may wish to read a file
before an open has completed. In the new minifilter model, a minifilter will be able to generate I/O in one of
two ways: using general routines similar to today's routines, and using simplified routines that provide an
interface similar to the ZwXxx routines.

The general routines that the system provides to minifilters for I/O generation are:
NTSTATUS
FLTAPI
FltAllocateCallbackData (
IN PFLT_INSTANCE Instance,
IN PFILE_OBJECT FileObject OPTIONAL,
OUT PFLT_CALLBACK_DATA *RetNewCallbackData
);

VOID
FLTAPI
FltPerformSynchronousIo (
IN PFLT_CALLBACK_DATA CallbackData
);

NTSTATUS
FLTAPI
FltPerformAsynchronousIo (
IN PFLT_CALLBACK_DATA CallbackData,
IN PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
IN PVOID CallbackContext
);
Using the general routines, a minifilter can call FltAllocateCallbackData() to allocate a
CallbackData for the operation, and then fill in the appropriate parameters in the CallbackData for the
desired operation. The minifilter then calls FltPerformSynchronousIo() or
FltPerformAsynchronousIo() to actually initiate the I/O. The instance parameter should always be for
the current instance doing the I/O operation.

In addition Filter Manager exports some common utility routines. Examples:

NTSTATUS
FLTAPI
FltCreateFile (
IN PFLT_FILTER Filter,
IN PFLT_INSTANCE Instance OPTIONAL,
OUT PHANDLE FileHandle,
IN ACCESS_MASK DesiredAccess,
IN POBJECT_ATTRIBUTES ObjectAttributes,
OUT PIO_STATUS_BLOCK IoStatusBlock,
IN PLARGE_INTEGER AllocationSize OPTIONAL,
IN ULONG FileAttributes,
IN ULONG ShareAccess,
IN ULONG CreateDisposition,
IN ULONG CreateOptions,
IN PVOID EaBuffer OPTIONAL,

Page 25 of 28
 IN ULONG EaLength,
IN ULONG Flags
);
If InstanceHandle is omitted, the CREATE will be sent to the top of the stack (so the minifilter initiating the
operation will itself see the I/O recursively.) This is discouraged unless absolutely necessary as it can cause
deadlocks and stack overflows if minifilters misuse it.

If InstanceHandle is provided (this should always be your own instance), then the create is initiated with
the minifilter just below the caller of this API, by passing all legacy minifilters above the Filter Manager and
minifilters above the caller.

The FileHandle returned by this API can be used in all Zw* calls that accept a file handle as a parameter. If
the Instance parameter is non-NULL in a call to FltCreateFile(), it is guaranteed that all future I/O (via
the Zw APIs, FltClose() etc.), on this handle will only be seen by the instances below the
InitiatingInstance.
FltReadFile() and FltWriteFile() are support routines to allow minifilters to generate IOs that are
only seen by instances below them when they have only the FileObject to represent the file. These routines
are analogous to “rolling an IRP” in the legacy filter model.

IMPORTANT NOTE: 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 instance relative to the InitiatingInstance specified.
NTSTATUS
FLTAPI
FltReadFile (
IN PFLT_INSTANCE InitiatingInstance,
IN PFILE_OBJECT FileObject,
IN PLARGE_INTEGER ByteOffset OPTIONAL,
IN ULONG Length,
OUT PVOID Buffer,
IN FLT_IO_OPERATION_FLAGS Flags,
OUT PULONG BytesRead OPTIONAL,
IN PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine OPTIONAL,
IN PVOID CallbackContext 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_CALLBACK CallbackRoutine OPTIONAL,
IN PVOID CallbackContext OPTIONAL
);
By default, all minifilter-initiated I/O is sent to the next attached instance for the given volume, bypassing
any instances attached above the minifilter initiating the I/O.

Minifilter initiated I/O can be synchronous or asynchronous. When the I/O is asynchronous, the minifilter
provides a callback routine that the system will call when the I/O is completed.

Page 26 of 28
13. Rules for Unload/Unregister/Detach
Detaching means a minifilter instance is going to be destroyed. That minifilter will no longer be called for any
operations on that volume (unless, of course, there's still another instance of that minifilter attached to that
volume).

Unloading a minifilter means its code is no longer in memory. This will most often be done at system
shutdown time and when a new version of a minifilter is being installed without shutting the system down.

A minifilter instance can be detached from a volume from within the minifilter (by calling
FltDetachVolume()) but the more common method will be via the UI. A minifilter instance can be
detached even when there is outstanding I/O. In that case, the minifilter's completion routine(s) will be
called for any outstanding I/O operations with the flag FLTFL_POST_OPERATION_DRAINING set. The
minifilter will not receive completion callbacks when those I/O operations actually complete.

When a minifilter instance is detached, the system will call the minifilter's context free routines for all
outstanding contexts for files, streams, and stream file objects associated with that instance.

14. Support Routines

In addition to the interfaces already discussed, the Filter Manager provides a number of support routines to
help minifilters perform their required tasks. Here’s a list of some of the additional routines. Please look to
the Filter Manager IFS Kit documentation for more detailed information on these routines:

Routines for name / object translation:

• FltGetFilterFromName()
• FltGetVolumeFromName()
• FltGetVolumeInstanceFromName()
Routines for volume, instance, device object translation:

• FltGetVolumeFromInstance(), FltGetFilterFromInstance()
• FltGetVolumeFromDeviceObject()
• FltGetDeviceObject()
• FltGetDiskDeviceObject()
Routines for accessing information on objects:

• FltGetVolumeProperties()
• FltIsVolumeWriteable
• FltQueryVolumeInformation(), FltSetVolumeInformation()
• FltGetInstanceInformation()
• FltGetFilterInformation()
Enumeration routines:

• FltEnumerateFilters()
• FltEnumerateVolumes()
• FltEnumerateInstances()
• FltEnumerateFilterInformation()
• FltEnumerateInstanceInformationByFilter()
• FltEnumerateInstanceInformationByVolume()
• FltEnumerateVolumeInformation()
Oplock routines:

Page 27 of 28
 • FltInitializeOplock()
• FltUninitializeOplock()
• FltOplockFsctrl()
• FltCheckOplock()
• FltOplockIsFastIoPossible()
• FltCurrentBatchOplock()
Directory Change Notification routines:

• FltNotifyFilterChangeDirectory()
Other:

• FltGetRequestorProcess(), FltGetRequestorProcessId()

15. Building a Minifilter

Everything needed to build an application that uses the minifilter architecture can be found in the Filter
Manager IFS Kit. This includes:

• The full build environment needed to build a minifilter and a user-mode application that uses the
user-mode Filter Manager interfaces

• An install package to install the Filter Manager components on a machine for development until the
version of the OS which contains the Filter Manager is released by Microsoft

• Minifilter source code samples

All minifilters include the header FltKernel.h and link with FltMgr.lib. User mode filter components will include
the header FltUser.h and link with FltLib.lib.

Page 28 of 28