Creating a Per-Stream Context

Note

For optimal reliability and performance, use file system minifilter drivers with Filter Manager support instead of legacy file system filter drivers. To port your legacy driver to a minifilter driver, see Guidelines for Porting Legacy Filter Drivers.

Legacy file system filter drivers that use a per-stream context structure containing a FSRTL_PER_STREAM_CONTEXT structure can take advantage of built-in per-stream context support in Windows XP and later.

A file system filter driver typically creates a per-stream context structure for a file stream when the file stream is first opened. However, a per-stream context structure can be created and associated with a file stream during any operation.

Allocating the Per-Stream Context

Per-stream context structures can be allocated from paged or nonpaged pool. To allocate a per-stream context, call ExAllocatePoolWithTag as shown in the following example:

contextSize = sizeof(SPY_STREAM_CONTEXT) + fileName.Length;
ctx = ExAllocatePoolWithTag(NonPagedPool,
                            contextSize,
                            MYLEGACYFILTER_CONTEXT_TAG);

If your filter allocates the per-stream context structure from paged pool, it can't call ExAllocatePoolWithTag from its create completion routine. This is because completion routines can be called at IRQL DISPATCH_LEVEL.

Initializing the Per-Stream Context

File system filter drivers call FsRtlInitPerStreamContext to initialize a per-stream context structure. This routine initializes the FSRTL_PER_STREAM_CONTEXT portion of the context structure. (The remainder of the structure is filter-driver-specific.)

If your filter driver creates only one per-stream context structure per file stream, it should pass NULL for the InstanceId parameter to FsRtlInitPerStreamContext.

A filter driver can initialize a per-stream context at any time. However, it must do so before associating the context with a file stream.