FsRtlRemovePerFileContext function (ntifs.h)

The FsRtlRemovePerFileContext routine returns a pointer to a FSRTL_PER_FILE_CONTEXT object that is associated with a file. FsRtlRemovePerFileContext removes the FSRTL_PER_FILE_CONTEXT object from the list it occupies, along with the associated driver specific context information.

Syntax

PFSRTL_PER_FILE_CONTEXT FsRtlRemovePerFileContext(
  [in]           PVOID *PerFileContextPointer,
  [in, optional] PVOID OwnerId,
  [in, optional] PVOID InstanceId
);

Parameters

[in] PerFileContextPointer

A pointer to an opaque pointer that is used by the file system runtime library (FSRTL) package to track file contexts. To obtain this pointer from a file object, use the FsRtlGetPerFileContextPointer macro.

[in, optional] OwnerId

A pointer to a filter driver-allocated variable that uniquely identifies the owner of the per-file context structure. This parameter is optional, but must be non-NULL if InstanceId is non-NULL.

[in, optional] InstanceId

A pointer to a filter driver-allocated variable that can be used to distinguish among per-file context structures that are created by the same filter driver. This parameter is optional.

Return value

A pointer to the first FSRTL_PER_FILE_CONTEXT that matches the OwnerId and InstanceId, if specified. If no match is found or if the system does not support per file context information, this routine returns NULL.

Remarks

FsRtlRemovePerFileContext removes only the first matching per-file context structure that it finds. If there are additional matching per-file contexts, the filter driver must call FsRtlRemovePerFileContext as many times as required to remove them all.

The file system filter driver must free the memory that is used for this context information after the FSRTL_PER_FILE_CONTEXT has been removed.

Use this routine for your drivers to remove contexts only when the driver must discard per-file context information while the file is still open. Contexts are removed when a file is closed by using FsRtlTeardownPerFileContexts.

Don't use this routine inside your FreeCallback routine. The file system removes contexts from the list before that routine is called.

Don't use this routine inside your IRP_CLOSE handler. You will not be notified when the stream is torn down.

Requirements

See also

FSRTL_PER_FILE_CONTEXT

FsRtlGetPerFileContextPointer

FsRtlInsertPerFileContext

FsRtlLookupPerFileContext

Tracking Per-File Context in a Legacy File System Filter Driver