FSRTL_PER_FILEOBJECT_CONTEXT structure (ntifs.h)
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:
- FsRtlInitPerFileObjectContext
- FsRtlInsertPerFileObjectContext
- FsRtlLookupPerFileObjectContext
- FsRtlRemovePerFileObjectContext
Instead, minifilters can use the following functions to associate context information with a file object:
- FltAllocateContext
- FltDeleteContext
- FltSetStreamHandleContext
- FltDeleteStreamHandleContext
- FltGetStreamHandleContext
- FltReleaseContext
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
FsRtlInsertPerFileObjectContext