FsRtlInsertPerFileObjectContext function

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

FileObject [in]

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

Ptr [in]

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 codeDescription
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

Target platform

Universal

Version

Available in Windows Vista and later versions of Windows.

Header

Ntifs.h (include Fltkernel.h or Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<= APC_LEVEL

See also

FSRTL_PER_FILEOBJECT_CONTEXT
FsRtlInitPerFileObjectContext
FsRtlLookupPerFileObjectContext
FsRtlRemovePerFileObjectContext

 

 

Send comments about this topic to Microsoft

Show: