FltRegisterFilter function (fltkernel.h)

Article
02/22/2024

FltRegisterFilter registers a minifilter driver.

Syntax

NTSTATUS FLTAPI FltRegisterFilter(
  [in]  PDRIVER_OBJECT         Driver,
  [in]  const FLT_REGISTRATION *Registration,
  [out] PFLT_FILTER            *RetFilter
);

Parameters

[in] Driver

A pointer to the driver object for the minifilter driver. This should be the same driver object pointer that was passed as input to the minifilter driver's DriverEntry routine.

[in] Registration

A pointer to a caller-allocated minifilter driver registration structure (FLT_REGISTRATION).

[out] RetFilter

A pointer to a caller-allocated variable that receives an opaque filter pointer for the caller.

Return value

FltRegisterFilter returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return code	Description
STATUS_INSUFFICIENT_RESOURCES	FltRegisterFilter encountered a pool allocation failure. This is an error code.
STATUS_INVALID_PARAMETER	One of the following: The Version member of the Registration structure was not set to FLT_REGISTRATION_VERSION. One of the non-NULL name-provider routines in the Registration structure was set to an invalid value. The GenerateFileNameCallback, NormalizeNameComponentCallback, and NormalizeNameComponentExCallback members of FLT_REGISTRATION point to the name-provider routines. STATUS_INVALID_PARAMETER is an error code.
STATUS_FLT_NOT_INITIALIZED	The Filter Manager was not initialized when the filter tried to register. Make sure that the Filter Manager is loaded as a driver. This is an error code.
STATUS_OBJECT_NAME_NOT_FOUND	The filter service key is not found in the registry. -or- The filter instance is not registered.

Remarks

Every minifilter driver must call FltRegisterFilter from its DriverEntry routine to add itself to the global list of registered minifilter drivers and to provide the Filter Manager with a list of callback functions and other information about the minifilter driver.

FltRegisterFilter returns an opaque filter pointer for the minifilter driver in *RetFilter. This pointer value uniquely identifies the minifilter driver and remains constant as long as the minifilter driver is loaded. The minifilter driver should save this pointer, because it is a required parameter for FltStartFiltering and FltUnregisterFilter.

After calling FltRegisterFilter, a minifilter driver typically calls FltStartFiltering to begin filtering I/O operations.

A minifilter driver can only call FltRegisterFilter to register itself, not another minifilter driver.

To unregister itself, a minifilter driver calls FltUnregisterFilter..

Requirements

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