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

Note

For optimal reliability and performance, use file system minifilter drivers with Filter Manager support instead of legacy file system filter drivers. 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.