FltEnumerateInstances function (fltkernel.h)

Article
10/21/2021

The FltEnumerateInstances routine enumerates minifilter driver instances for a given minifilter driver or volume.

Syntax

NTSTATUS FLTAPI FltEnumerateInstances(
  [in, optional] PFLT_VOLUME   Volume,
  [in, optional] PFLT_FILTER   Filter,
  [out]          PFLT_INSTANCE *InstanceList,
  [in]           ULONG         InstanceListSize,
  [out]          PULONG        NumberInstancesReturned
);

Parameters

[in, optional] Volume

Opaque pointer for the volume for which the caller wants to enumerate minifilter driver instances. If NULL, instances for all volumes are enumerated. Must be non-NULL if Filter is NULL.

[in, optional] Filter

Opaque filter pointer for the minifilter driver whose instances are to be enumerated. If NULL, instances for all minifilter drivers are enumerated. Must be non-NULL if Volume is NULL.

[out] InstanceList

Pointer to a caller-allocated buffer that receives an array of opaque instance pointers.

[in] InstanceListSize

Number of opaque instance pointers that the buffer that InstanceList points to can hold.

[out] NumberInstancesReturned

Pointer to a caller-allocated variable that receives the number of opaque instance pointers returned in the array that InstanceList points to. If InstanceListSize is too small, FltEnumerateInstances returns STATUS_BUFFER_TOO_SMALL and sets NumberInstancesReturned to point to the number of matching instances found.

Return value

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

Return code	Description
STATUS_BUFFER_TOO_SMALL	The buffer that the InstanceList parameter points to is not large enough to store the requested information. This is an error code.
STATUS_INVALID_PARAMETER	Volume and Filter cannot both be NULL. This is an error code.

Remarks

Because the minifilter driver instances in the instance list can change at any time, two calls to FltEnumerateInstances with the same Volume and Filter values are not guaranteed to return the same result.

FltEnumerateInstances adds a rundown reference to each of the opaque instance pointers returned in the array that the InstanceList parameter points to. When these pointers are no longer needed, the caller must release them by calling FltObjectDereference on each one. Thus every successful call to FltEnumerateInstances must be matched by a subsequent call to FltObjectDereference for each returned instance pointer.

To enumerate all registered minifilter drivers, call FltEnumerateFilters.

To enumerate all volumes that are known to the Filter Manager, call FltEnumerateVolumes.

To list filter information for all registered minifilter drivers, call FltEnumerateFilterInformation.

To get filter information for a given minifilter driver, call FltGetFilterInformation.

To enumerate all instances of a given minifilter driver, call FltEnumerateInstanceInformationByFilter.

To enumerate all minifilter driver instances on a given volume, call FltEnumerateInstanceInformationByVolume.

Requirements

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