FsRtlInitPerFileObjectContext macro

The FsRtlInitPerFileObjectContext macro initializes a FSRTL_PER_FILEOBJECT_CONTEXT structure.

Syntax

VOID FsRtlInitPerFileObjectContext(
  [in] PFSRTL_PER_FILEOBJECT_CONTEXT PerFileObjectContext,
  [in] PVOID                         OwnerId,
  [in] PVOID                         InstanceId
);

Parameters

• PerFileObjectContext [in]
  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]
  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]
  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.

Return value

None

Remarks

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

See also

FSRTL_PER_FILEOBJECT_CONTEXT

FsRtlInsertPerFileObjectContext

FsRtlLookupPerFileObjectContext

FsRtlRemovePerFileObjectContext

Send comments about this topic to Microsoft