Expand Minimize

FsRtlRemovePerStreamContext function

FsRtlRemovePerStreamContext removes a per-stream context structure from the list of per-stream contexts associated with a file stream.

Syntax


PFSRTL_PER_STREAM_CONTEXT FsRtlRemovePerStreamContext(
  _In_      PFSRTL_ADVANCED_FCB_HEADER StreamContext,
  _In_opt_  PVOID OwnerId,
  _In_opt_  PVOID InstanceId
);

Parameters

StreamContext [in]

Pointer to the FSRTL_ADVANCED_FCB_HEADER structure for the file stream. To get this pointer from a file object, use the FsRtlGetPerStreamContextPointer macro.

OwnerId [in, optional]

Used to identify context information as belonging to a particular filter driver.

InstanceId [in, optional]

Used to search for a particular instance of a per-stream context. If not provided, any of the contexts owned by the filter driver is removed and returned.

If neither the OwnerId nor the InstanceId is provided, any associated per-stream context will be removed and returned.

Return value

FsRtlRemovePerStreamContext returns a pointer to the per-stream context that is removed. If no match is found, or if the file system does not support filter contexts, FsRtlRemovePerStreamContext returns NULL.

Remarks

A file system filter driver calls FsRtlRemovePerStreamContext to remove its own per-stream context structure from the list of per-stream contexts associated with a file stream.

Note  FsRtlRemovePerStreamContext removes only the first matching per-stream context structure that is found. If there are additional matching per-stream contexts, the filter driver must call FsRtlRemovePerStreamContext as many times as required to remove them all.

This routine should only be used when a filter driver needs to discard the context information it has associated with a file stream while the stream is still open. For example, a filter driver might call FsRtlRemovePerStreamContext in the following cases:

  • When it receives a request from a user-mode application to stop logging I/O requests on a particular volume.

  • When it detects that a file or directory has been renamed.

When a file stream is closed, the file system is responsible for ensuring that all per-stream contexts associated with that stream are removed and freed. To do this, the file system must call FsRtlTeardownPerStreamContexts on the file control block (FCB) or other stream context object for the file stream. FsRtlTeardownPerStreamContexts walks the FilterContexts list, removing each entry and calling its FreeCallback routine.

Thus, a file system filter driver should not call FsRtlRemovePerStreamContext from within an IRP_MJ_CLOSE or IRP_MJ_PNP dispatch routine. Not only would such a call be unnecessary, but it might also interfere with the file system's call to FsRtlTeardownPerStreamContexts.

Note   A file system filter driver should not call FsRtlRemovePerStreamContext from within a per-stream context structure's FreeCallback routine. This is because the underlying file system calls the FreeCallback routine after it has already removed the context structure from the FilterContexts list.

To initialize a per-stream context structure, use the FsRtlInitPerStreamContext macro.

To associate an initialized per-stream context structure with a file stream, call FsRtlInsertPerStreamContext.

To retrieve a per-stream context structure that is associated with a file stream, call FsRtlLookupPerStreamContext.

FsRtlRemovePerStreamContext can only be used on file systems that support filter contexts.

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

Requirements

Version

This routine is available on Update Rollup for Windows 2000 Service Pack 4 (SP4) and on Microsoft Windows XP and later.

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= APC_LEVEL

See also

FSRTL_ADVANCED_FCB_HEADER
FSRTL_PER_STREAM_CONTEXT
FsRtlGetPerStreamContextPointer
FsRtlInitPerStreamContext
FsRtlInsertPerStreamContext
FsRtlLookupPerStreamContext
FsRtlSetupAdvancedHeader
FsRtlSupportsPerStreamContexts
FsRtlTeardownPerStreamContexts
IRP_MJ_CLOSE
IRP_MJ_PNP

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft