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.
Note The FreeCallback routine cannot recursively call down into the file system or acquire any file system resources. Also, this routine must assume that the file object for the file stream has already been freed.
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).|