Tracking Per-File Context in a Legacy File System Filter Driver

Note For optimal reliability and performance, we recommend using file system minifilter drivers instead of legacy file system filter drivers. Also, legacy file system filter drivers can’t attach to direct access (DAX) volumes. For more about file system minifilter drivers, see Advantages of the Filter Manager Model. To port your legacy driver to a minifilter driver, see Guidelines for Porting Legacy Filter Drivers.

A legacy file system filter driver can record context information for a file by associating a FSRTL_PER_FILE_CONTEXT object with a user-defined context information structure.

Note Not all file systems support per-file context objects. To find out whether a file is associated with a file system that supports them, use the FsRtlSupportsPerFileContexts macro.

Use the FsRtlInitPerFileContext macro to initialize the FSRTL_PER_FILE_CONTEXT object. Then use the FsRtlInsertPerFileContext routine to associate the file with an arbitrary context object.

Use the FsRtlGetPerFileContextPointer macro to get a pointer that is used by the file system runtime library (FSRTL) package to track file contexts.

A filter driver can use the FsRtlLookupPerFileContext routine to find a file context object that is associated with a file. The routine can specify the owner of a structure or an instance of a structure to narrow the search.

The filter driver can remove a context object by using FsRtlRemovePerFileContext. The routine can specify the owner of a structure or an instance of a structure to narrow the search.

Note Only use the FsRtlRemovePerFileContext routine to remove context objects while the file is still open. Do not confuse it with FsRtlTeardownPerFileContexts.

File systems call FsRtlTeardownPerFileContexts to free any filter contexts that are still associated with a per-file control block structure (FCB) that they are tearing down. The FsRtlTeardownPerFileContexts routine calls the FreeCallback routine that is specified in the FSRTL_PER_FILE_CONTEXT object for each filter context.