FsRtlInsertPerFileObjectContext function (ntifs.h)

Article
11/04/2022

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

Syntax

NTSTATUS FsRtlInsertPerFileObjectContext(
  [in] PFILE_OBJECT                  FileObject,
  [in] PFSRTL_PER_FILEOBJECT_CONTEXT Ptr
);

Parameters

[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
STATUS_SUCCESS	The context information structure was successfully associated with the file object.
STATUS_INVALID_PARAMETER	The FileObject parameter is NULL.
STATUS_INSUFFICIENT_RESOURCES	The system lacks sufficient resources to complete the operation. For example, a file object extension could not be allocated for FileObject.

Remarks

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.

Requirements

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