FsRtlInitPerStreamContext macro (ntifs.h)

Article
11/04/2022

The FsRtlInitPerStreamContext macro initializes a filter driver context structure.

Syntax

void FsRtlInitPerStreamContext(
   _fc,
   _owner,
   _inst,
   _cb
);

Parameters

_fc

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.

_owner

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.

_inst

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.

_cb

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 );

Buffer

Return value

None

Remarks

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.

After the context structure has been associated with a file stream, it can be retrieved by calling FsRtlLookupPerStreamContext or removed by calling FsRtlRemovePerStreamContext.

For more information, see Tracking Per-Stream Context in a Legacy File System Filter Driver.

Requirements

Requirement	Value
Minimum supported client	Windows XP; Update Rollup for Windows 2000 Service Pack 4 (SP4)
Target Platform	Desktop
Header	ntifs.h (include Ntifs.h)
IRQL	Any level