Expand Minimize

FltAllocateContext routine

The FltAllocateContext routine allocates a context structure for a specified context type.

Syntax


NTSTATUS FltAllocateContext(
  _In_  PFLT_FILTER      Filter,
  _In_  FLT_CONTEXT_TYPE ContextType,
  _In_  SIZE_T           ContextSize,
  _In_  POOL_TYPE        PoolType,
  _Out_ PFLT_CONTEXT     *ReturnedContext
);

Parameters

Filter [in]

An opaque filter pointer for the caller. This parameter is required and cannot be NULL. (Setting this parameter to an invalid value causes the system to execute an ASSERT on a checked build.)

ContextType [in]

The type of context to allocate. One of the following:

FLT_FILE_CONTEXT (starting with Windows Vista)

FLT_INSTANCE_CONTEXT

FLT_SECTION_CONTEXT (starting with Windows 8)

FLT_STREAM_CONTEXT

FLT_STREAMHANDLE_CONTEXT

FLT_TRANSACTION_CONTEXT (starting with Windows Vista)

FLT_VOLUME_CONTEXT

ContextSize [in]

The size, in bytes, of the portion of the context defined by the minifilter driver. Must be greater than zero and less than or equal to MAXUSHORT. A minifilter driver uses this portion of the context to maintain context information specific to the minifilter driver. The filter manager treats this portion of the context structure as opaque. This parameter is required and cannot be zero.

PoolType [in]

The type of pool to allocate. This parameter is required and must be one of the following:

NonPagedPool

PagedPool

Must be NonPagedPool if ContextType is FLT_VOLUME_CONTEXT.

Setting this parameter to an invalid value causes the system to execute an ASSERT on a checked build.

ReturnedContext [out]

A pointer to a caller-allocated variable that receives the address of the newly allocated context. The caller is responsible for calling FltReleaseContext to release this context when it is no longer needed.

Return value

FltAllocateContext returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following.

Return codeDescription
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND

The allocation information for the context of the specified type was not provided at the time of filter registration. This is an error code.

STATUS_FLT_DELETING_OBJECT

The minifilter driver that is specified in the Filter parameter is being torn down. This is an error code.

STATUS_INSUFFICIENT_RESOURCES

FltAllocateContext encountered a pool allocation failure. This is an error code.

STATUS_INVALID_PARAMETER

An invalid value was specified for the ContextType or the ContextSize parameter. This is an error code.

STATUS_NOT_SUPPORTED

The file system does not support per-stream contexts. This is an error code.

 

Remarks

FltAllocateContext allocates a context of the specified type from the specified pool. The contents of the returned context are not zeroed.

After the context is allocated, it can be set on an object by passing the ReturnedContext pointer to the appropriate set-context routine from the following table.

Context TypeSet-Context Routine

FLT_FILE_CONTEXT

FltSetFileContext (starting with Windows Vista)

FLT_INSTANCE_CONTEXT

FltSetInstanceContext

FLT_SECTION_CONTEXT

FltCreateSectionForDataScan (Windows 8 and later only.)

FLT_STREAM_CONTEXT

FltSetStreamContext

FLT_STREAMHANDLE_CONTEXT

FltSetStreamHandleContext

FLT_TRANSACTION_CONTEXT

FltSetTransactionContext (starting with Windows Vista)

FLT_VOLUME_CONTEXT

FltSetVolumeContext

 

When a minifilter driver calls FltRegisterFilter from its DriverEntry routine, it must register each context type that it uses. For more information, see the reference entry for the FLT_CONTEXT_REGISTRATION structure.

FltAllocateContext does not initialize the contents of the portion of the context structure specific to the minifilter driver.

To get the context for an object, call FltGetContexts or the appropriate get-context routine from the following table.

Context TypeGet-Context Routine

FLT_FILE_CONTEXT

FltGetFileContext (starting with Windows Vista)

FLT_INSTANCE_CONTEXT

FltGetInstanceContext

FLT_SECTION_CONTEXT

FltGetSectionContext (starting with Windows 8)

FLT_STREAM_CONTEXT

FltGetStreamContext

FLT_STREAMHANDLE_CONTEXT

FltGetStreamHandleContext

FLT_TRANSACTION_CONTEXT

FltGetTransactionContext (starting with Windows Vista )

FLT_VOLUME_CONTEXT

FltGetVolumeContext

 

Contexts are reference-counted and on a successful return from FltAllocateContext, the context pointed to by ReturnedContext has a reference count of 1. A context is freed automatically when its reference count reaches zero. To increment the reference count on a context, call FltReferenceContext.

To decrement the reference count on a context, call FltReleaseContext.

Because contexts are reference-counted, it is not usually necessary to delete them. To delete a context explicitly, call FltDeleteContext or the appropriate delete-context routine from the following table.

Context TypeDelete-Context Routine

FLT_FILE_CONTEXT

FltDeleteFileContext (starting with Windows Vista)

FLT_INSTANCE_CONTEXT

FltDeleteInstanceContext

FLT_SECTION_CONTEXT

FltCloseSectionForDataScan (starting with Windows 8)

FLT_STREAM_CONTEXT

FltDeleteStreamContext

FLT_STREAMHANDLE_CONTEXT

FltDeleteStreamHandleContext

FLT_TRANSACTION_CONTEXT

FltDeleteTransactionContext (starting with Windows Vista)

FLT_VOLUME_CONTEXT

FltDeleteVolumeContext

 

Requirements

Target platform

Universal

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL

See also

FLT_CONTEXT_REGISTRATION
FltCloseSectionForDataScan
FltCreateSectionForDataScan
FltDeleteContext
FltDeleteFileContext
FltDeleteInstanceContext
FltDeleteStreamContext
FltDeleteStreamHandleContext
FltDeleteTransactionContext
FltDeleteVolumeContext
FltGetContexts
FltGetFileContext
FltGetInstanceContext
FltGetSectionContext
FltGetStreamContext
FltGetStreamHandleContext
FltGetTransactionContext
FltGetVolumeContext
FltReferenceContext
FltRegisterFilter
FltReleaseContext
FltSetFileContext
FltSetInstanceContext
FltSetStreamContext
FltSetStreamHandleContext
FltSetTransactionContext
FltSetVolumeContext

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft