Edit

FSRTL_PER_FILEOBJECT_CONTEXT structure (ntifs.h)

  • Article

The OS uses the opaque FSRTL_PER_FILEOBJECT_CONTEXT structure to track file system filter-driver-defined context information structures for a file object.

Syntax

typedef struct _FSRTL_PER_FILEOBJECT_CONTEXT {
  LIST_ENTRY Links;
  PVOID      OwnerId;
  PVOID      InstanceId;
} FSRTL_PER_FILEOBJECT_CONTEXT, *PFSRTL_PER_FILEOBJECT_CONTEXT;

Members

Links

Link for this structure in the list of all per-file-object context structures associated with the same file object. FsRtlInsertPerFileObjectContext inserts this member into the list of all per-file-object context structures for the file object.

OwnerId

A pointer to a filter-driver-allocated variable that uniquely identifies the owning filter of the per-file-object context structure. The format of this variable is filter-driver-specific. Filter writers should choose a value that is both meaningful and convenient, such as the address of the filter's device object or driver object. Note that the value of this member can't be NULL.

InstanceId

A pointer to a filter-driver-allocated variable that can be used to distinguish among per-file-object context structures created by the same filter driver. The format of this variable is filter-driver-specific. Filter writers should choose a value that is both meaningful and convenient, such as the address of the file object itself. Note that the value of this member can be NULL.

Remarks

File system filter drivers can use the opaque FSRTL_PER_FILEOBJECT_CONTEXT structure to maintain context information for a file object. This structure can be used as-is or embedded in a driver-defined, per-file-object context structure.

Each file object can have one per-file-object context structure list associated with it. Each member of this list (that is, a particular per-file-object context structure) is owned by a filter driver. From the perspective of a filter driver, each filter driver can associate multiple per-file-object context structures for the same file object.

Each filter-defined per-file-object context structure must include an initialized FSRTL_PER_FILEOBJECT_CONTEXT structure. The FSRTL_PER_FILEOBJECT_CONTEXT structure can be allocated from paged or nonpage pool and must be initialized using the FsRtlInitPerFileObjectContext macro.

To insert a FSRTL_PER_FILEOBJECT_CONTEXT structure or a filter-defined per-file-object context structure (containing an initialized FSRTL_PER_FILEOBJECT_CONTEXT structure) into the list of all context structures for a file object, use the FsRtlInsertPerFileObjectContext function.

After a FSRTL_PER_FILEOBJECT_CONTEXT or per-file-object context structure has been associated with a file object, it can be retrieved by calling FsRtlLookupPerFileObjectContext or removed by calling FsRtlRemovePerFileObjectContext (based upon the values of OwnerId and InstanceId).

File system minifilter drivers must not use the following functions:

Instead, minifilters can use the following functions to associate context information with a file object:

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
Header ntifs.h (include Fltkernel.h, Ntifs.h)

See also

DEVICE_OBJECT

DRIVER_OBJECT

FILE_OBJECT

FltAllocateContext

FltDeleteContext

FltDeleteStreamHandleContext

FltGetStreamHandleContext

FltReleaseContext

FltSetStreamHandleContext

FsRtlInitPerFileObjectContext

FsRtlInsertPerFileObjectContext

FsRtlLookupPerFileObjectContext

FsRtlRemovePerFileObjectContext