Download EaseFilter Filter Driver SDK Setup File Download EaseFilter Filter Driver SDK Zip File
The FltAllocateContext routine allocates a context structure for a specified context type.
NTSTATUS FLTAPI FltAllocateContext( PFLT_FILTER Filter, FLT_CONTEXT_TYPE ContextType, SIZE_T ContextSize, POOL_TYPE PoolType, PFLT_CONTEXT *ReturnedContext );
Filter
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
The type of context to allocate. ContextType can be one of the following:
ContextSize
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; for fixed-size contexts, must be less than or equal to the Size specified in the FLT_CONTEXT_REGISTRATION structure. 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
The type of pool to allocate. This parameter is required and must be one of the following:
Setting this parameter to an invalid value causes the system to execute an ASSERT on a checked build.
ReturnedContext
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.
FltAllocateContext returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following.
Return code | Description |
---|---|
|
FltAllocateContext returns this status if either of the following conditions occur:
|
|
The minifilter driver that is specified in the Filter parameter is being torn down. This is an error code. |
|
FltAllocateContext encountered a pool allocation failure. This is an error code. |
|
ContextSize cannot be greater than MAXUSHORT. This is an error code. |
|
An invalid value was specified for the ContextType or the ContextSize parameter. This is an error code. |
|
The file system does not support per-stream contexts. This is an error code. |
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 Type | Set-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 Type | Get-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 Type | Delete-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 |
Target Platform | Universal |
Header | fltkernel.h (include Fltkernel.h) |
Library | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | <= APC_LEVEL |