The FsRtlInitPerStreamContext macro initializes a filter driver context structure.
VOID FsRtlInitPerStreamContext( _In_ PFSRTL_PER_STREAM_CONTEXT PerStreamContext, _In_ PVOID OwnerId, _In_ PVOID InstanceId, _In_ PFREE_FUNCTION FreeCallback );
- PerStreamContext [in]
Pointer to a caller-allocated FSRTL_PER_STREAM_CONTEXT structure to be used to maintain context information for a file stream. This structure can be used as is or embedded in a driver-defined per-stream context structure. Both structure types are commonly allocated by calling ExAllocatePoolWithTag.
- OwnerId [in]
Pointer to a caller-allocated variable that uniquely identifies the owner of the per-stream 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 a driver object or device object. Callers must specify a non-NULL value for this parameter.
- InstanceId [in]
Pointer to a filter driver − allocated variable that can be used to distinguish among per-stream 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 stream context object for the file stream. (To get this address from a file object, use the FsRtlGetPerStreamContextPointer macro.) This parameter is optional and can be NULL.
- FreeCallback [in]
Pointer to a callback routine that frees the per-stream context structure. Callers must specify a non-NULL value for this parameter. This routine and its parameters are defined as follows:
typedef VOID (*PFREE_FUNCTION) ( IN PVOID Buffer );
Pointer to the per-stream context structure to be freed. The FreeCallback routine typically casts this pointer to the appropriate structure pointer type and frees it by calling ExFreePool.
A file system filter driver uses the FsRtlInitPerStreamContext macro to initialize a newly allocated per-stream context structure before associating it with a file stream. The initialized context structure can be passed as a parameter to FsRtlInsertPerStreamContext.
FsRtlInitPerStreamContext stores the address of the FreeCallback routine in the FreeCallback member of the FSRTL_PER_STREAM_CONTEXT structure.
The FreeCallback routine is called at IRQL <= APC_LEVEL. Usually, it is called at IRQL PASSIVE_LEVEL.
To associate an initialized per-stream context structure with a file stream, call FsRtlInsertPerStreamContext.
For more information, see Tracking Per-Stream Context in a Legacy File System Filter Driver.
|The FsRtlInitPerStreamContext macro is available on Microsoft Windows XP and later, and on the Update Rollup for Windows 2000 Service Pack 4 (SP4).|