Edit

FSRTL_PER_FILE_CONTEXT structure (ntifs.h)

  • Article

A legacy file system filter driver can use a FSRTL_PER_FILE_CONTEXT structure to associate driver-specific context information to an open file.

Syntax

typedef struct _FSRTL_PER_FILE_CONTEXT {
  LIST_ENTRY     Links;
  PVOID          OwnerId;
  PVOID          InstanceId;
  PFREE_FUNCTION FreeCallback;
} FSRTL_PER_FILE_CONTEXT, *PFSRTL_PER_FILE_CONTEXT;

Members

Links

A link for this structure in the list of all per-file context structures that are associated with the same file. FsRtlInsertPerFileContext inserts this member into the list of all per-file context structures for a file.

OwnerId

A pointer to a filter-driver-allocated buffer that uniquely identifies the owner of the per-file context structure. The format of this variable is filter-driver-specific. Filter drivers must set this member to a non-NULL value.

InstanceId

A pointer to a filter-driver-allocated buffer that can be used to distinguish among the per-file context structures that are created by the same filter driver. The format of this variable is filter-driver-specific. Filter drivers can set this member to NULL.

FreeCallback

A pointer to a callback routine that frees the per-file context structure. Filter drivers must set this member to a non-NULL value.

Remarks

In order to associate context information with a file, a legacy filter driver first allocates a FSRTL_PER_FILE_CONTEXT structure and initializes it using FsRtlInsertPerFileContext. The driver then uses FsRtlInsertPerFileContext to associate that FSRTL_PER_FILE_CONTEXT object with the file. When the system tears down the file context object for a file, it calls FsRtlTeardownPerFileContexts which calls the FreeCallback routine that is specified in the FSRTL_PER_FILE_CONTEXT object. That callback must free the driver-specific context object.

Filter writers should choose an OwnerID value that is both meaningful and convenient, such as the address of a driver object or device object.

Filter writers should choose an InstanceID value that is both meaningful and convenient, such as the address of the file context object for the file. Use the FsRtlGetPerFileContextPointer macro to retrieve that address from a file object.

The FSRTL_PER_FILE_CONTEXT structure can be used as-is, or embedded in a driver-defined, per-file context structure.

The FSRTL_PER_FILE_CONTEXT structure can be allocated from paged or nonpaged pool.

The FsRtlInitPerFileContext macro initializes a FSRTL_PER_FILE_CONTEXT structure.

Parameters

FileContext

FSRTL_PER_FILE_CONTEXT

The FSRTL_PER_FILE_CONTEXT object to be initialized.

OwnerId

PVOID

A pointer to a filter driver-allocated variable that uniquely identifies the owner of the per-file context structure. The format is filter driver-specific. This parameter must have a non-NULL value.

InstanceId

PVOID

A pointer to a filter driver-allocated variable that uniquely identifies the owner of the per-file context structure. The format is filter driver-specific. This parameter must have a non-NULL value.

FreeCallback

PFREE_FUNCTION

A pointer to a callback routine that frees the per-file context structure.

Return value

VOID

None.

This macro must be used before calling FsRtlInsertPerFileContext.

Filter writers should choose an OwnerID value that is both meaningful and convenient, such as the address of a driver object or device object.

Filter writers should use an InstanceID value that is both meaningful and convenient, such as the address of the file context object for the file. Use the FsRtlGetPerFileContextPointer macro to retrieve that address from a file object.

For more information about how to use and create context objects, see Tracking Per-File Context in a Legacy File System Filter Driver.

Requirements

Requirement Value
Minimum supported client Available starting withWindows Vista.
Header ntifs.h (include Fltkernel.h, Ntifs.h)

See also

FsRtlGetPerFileContextPointer

FsRtlInitPerFileContext

FsRtlInsertPerFileContext

FsRtlTeardownPerFileContexts

PFREE_FUNCTION

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