Edit

FltGetContextsEx function (fltkernel.h)

  • Article

The FltGetContextsEx routine retrieves a minifilter driver's contexts for the objects related to the current operation.

Syntax

NTSTATUS FLTAPI FltGetContextsEx(
  [in]  PCFLT_RELATED_OBJECTS    FltObjects,
  [in]  FLT_CONTEXT_TYPE         DesiredContexts,
  [in]  SIZE_T                   ContextsSize,
  [out] PFLT_RELATED_CONTEXTS_EX Contexts
);

Parameters

[in] FltObjects

Pointer to a FLT_RELATED_OBJECTS structure containing opaque pointers for the objects related to the current operation. See Remarks for more information.

[in] DesiredContexts

Identifies the types of contexts to retrieve. This parameter can be a bitwise OR of the following values.

Constant Value
FLT_VOLUME_CONTEXT 0x0001
FLT_INSTANCE_CONTEXT 0x0002
FLT_FILE_CONTEXT 0x0004
FLT_STREAM_CONTEXT 0x0008
FLT_STREAMHANDLE_CONTEXT 0x0010
FLT_TRANSACTION_CONTEXT 0x0020
FLT_SECTION_CONTEXT 020040
FLT_ALL_CONTEXTS Bitwise OR of all of the context values

[in] ContextsSize

The size, in bytes, of the FLT_RELATED_CONTEXTS_EX structure pointed to by Contexts. Set to sizeof(FLT_RELATED_CONTEXTS_EX).

[out] Contexts

Pointer to a caller-allocated FLT_RELATED_CONTEXTS structure that receives the requested contexts. This parameter is required and cannot be set to NULL. FltMgr sets a structure member to zero for:

  • Contexts that the caller did not request.
  • Contexts that the caller requested but FltMgr couldn't find.

Return value

FltGetContextsEx returns STATUS_SUCCESS upon successful completion. Otherwise, it returns a status code such as one of the following.

Code Meaning
STATUS_INVALID_PARAMETER An invalid context value was input.

Remarks

For more information about contexts, see About minifilter contexts.

A minifilter driver calls FltGetContextsEx to retrieve pointers to its contexts for the objects in a FLT_RELATED_OBJECTS structure. On STATUS_SUCCESS, the minifilter will need to check that a context is not zero before using it.

The following minifilter driver callback routine types receive a pointer to a FLT_RELATED_OBJECTS structure as the FltObjects input parameter:

FltGetContextsEx increments the reference count on each of the contexts returned in the FLT_RELATED_CONTEXTS_EX structure that the Contexts parameter points to. Thus for every successful call to FltGetContextsEx, the caller must either:

  • Call FltReleaseContextsEx for the entire structure that the Contexts parameter points to.
  • Call FltReleaseContext for each of the contexts returned in the structure and set each context field returned in the structure to zero.

Requirements

Requirement Value
Minimum supported client Windows 8
Target Platform Universal
Header fltkernel.h (include Fltkernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

See also

FLT_RELATED_CONTEXTS_EX

FLT_RELATED_OBJECTS

FltRegisterFilter

FltReleaseContext

FltReleaseContextsEx

PFLT_INSTANCE_QUERY_TEARDOWN_CALLBACK

PFLT_INSTANCE_SETUP_CALLBACK

PFLT_INSTANCE_TEARDOWN_CALLBACK

PFLT_POST_OPERATION_CALLBACK

PFLT_PRE_OPERATION_CALLBACK