확장 최소화

FsRtlInitPerStreamContext function

The FsRtlInitPerStreamContext macro initializes a filter driver context structure.

Syntax


VOID FsRtlInitPerStreamContext(
  _In_  PFSRTL_PER_STREAM_CONTEXT PerStreamContext,
  _In_  PVOID OwnerId,
  _In_  PVOID InstanceId,
  _In_  PFREE_FUNCTION FreeCallback
);

Parameters

PerStreamContext [in]

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.

OwnerId [in]

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.

InstanceId [in]

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.

FreeCallback [in]

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

Pointer to the per-stream context structure to be freed. The FreeCallback routine typically casts this pointer to the appropriate structure pointer type and frees it by calling ExFreePool.

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

Version

The FsRtlInitPerStreamContext macro is available on Microsoft Windows XP and later, and on the Update Rollup for Windows 2000 Service Pack 4 (SP4).

Header

Ntifs.h (include Ntifs.h)

IRQL

Any level

See also

ExAllocatePoolWithTag
ExFreePool
FSRTL_PER_STREAM_CONTEXT
FsRtlGetPerStreamContextPointer
FsRtlInsertPerStreamContext
FsRtlLookupPerStreamContext
FsRtlRemovePerStreamContext
FsRtlSetupAdvancedHeader
FsRtlSupportsPerStreamContexts
FsRtlTeardownPerStreamContexts

 

 

Send comments about this topic to Microsoft

표시:
© 2014 Microsoft