FSRTL_PER_FILEOBJECT_CONTEXT structure
The opaque FSRTL_PER_FILEOBJECT_CONTEXT structure is used by the operating system 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 cannot 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 FsRtlLookupPerFileObjectContextor removed by calling FsRtlRemovePerFileObjectContext(based upon the values of OwnerId and InstanceId).
Note 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:
The FsRtlInitPerFileObjectContext macro initializes a FSRTL_PER_FILEOBJECT_CONTEXT structure.
Parameters
PerFileObjectContext [in]
PFSRTL_PER_FILEOBJECT_CONTEXT
A pointer to the FSRTL_PER_FILEOBJECT_CONTEXT structure to be initialized. This structure can be used as-is or embedded in a driver-defined, per-file-object context structure. Both structure types are commonly allocated by calling ExAllocatePoolWithTag.
OwnerId [in]
PVOID
A pointer to a caller-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. This parameter cannot be NULL.
InstanceId [in]
PVOID
A pointer to a caller-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. This parameter is optional and can be NULL.
FreeCallback
PFREE_FUNCTION
A pointer to a callback routine that frees the per-file context structure.
Return value
VOID
None.
The FsRtlInitPerFileObjectContext macro must be used to initialize a FSRTL_PER_FILEOBJECT_CONTEXT structure. For information about how the FSRTL_PER_FILEOBJECT_CONTEXT structure is used in relation to associating filter-defined context information with a file object, see the FSRTL_PER_FILEOBJECT_CONTEXT topic.
To associate a FSRTL_PER_FILEOBJECT_CONTEXT structure or filter-defined per-file-object context structure (containing an initialized FSRTL_PER_FILEOBJECT_CONTEXT structure) with a file object, use the FsRtlInsertPerFileObjectContext function.
After a FSRTL_PER_FILEOBJECT_CONTEXT structure or filter-defined per-file-object 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 FsRtlXxx PerFileObjectContext 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
Version |
Available in Windows Vista and later versions of Windows. |
Header |
Ntifs.h (include Fltkernel.h or Ntifs.h) |
See also
FsRtlInsertPerFileObjectContext
FsRtlLookupPerFileObjectContext
FsRtlRemovePerFileObjectContext