FsRtlInsertPerFileObjectContext function (ntifs.h)

For a "legacy" file system filter driver, the FsRtlInsertPerFileObjectContext function associates context information with a file object.


NTSTATUS FsRtlInsertPerFileObjectContext(
  [in] PFILE_OBJECT                  FileObject,


[in] FileObject

A pointer to the file object for which to associate context information (given by the Ptr parameter).

[in] Ptr

A pointer to a caller-allocated and initialized FSRTL_PER_FILEOBJECT_CONTEXT structure to be associated with FileObject. The structure can be used as-is or embedded in a driver-defined, per-file-object context information structure. To initialize the structure, use the FsRtlInitPerFileObjectContext macro.

Return value

FsRtlInsertPerFileObjectContext returns an appropriate NTSTATUS value, such as one of the following:

Return code Description
The context information structure was successfully associated with the file object.
The FileObject parameter is NULL.
The system lacks sufficient resources to complete the operation. For example, a file object extension could not be allocated for FileObject.


A file system filter driver calls FsRtlInsertPerFileObjectContext to associate its own per-file-object context structure with a file object. The context structure contains context information that the filter driver maintains for the file object. The FsRtlInsertPerStreamContext function inserts the Ptr context structure into the context list for FileObject.

All per-file-object context information structures must be or contain an initialized FSRTL_PER_FILEOBJECT_CONTEXT structure. Use the FsRtlInitPerFileObjectContext macro to initialize a FSRTL_PER_FILEOBJECT_CONTEXT structure.

After a FSRTL_PER_FILEOBJECT_CONTEXT structure or filter-defined per-file-object context structure (containing an initialized FSRTL_PER_FILEOBJECT_CONTEXT structure) has been associated with a file object, it can be retrieved by calling FsRtlLookupPerFileObjectContext or removed by calling FsRtlRemovePerFileObjectContext.

Note   File system minifilter drivers must not use the FsRtlXxxPerFileObjectContext functions. Instead, minifilters can use the FltXxxContext functions to associate context information with a file object. For a complete list, see the FSRTL_PER_FILEOBJECT_CONTEXT topic.


Requirement Value
Minimum supported client Windows Vista
Target Platform Universal
Header ntifs.h (include Fltkernel.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe

See also