IoEnumerateRegisteredFiltersList function (ntifs.h)

The IoEnumerateRegisteredFiltersList routine enumerates the file system filter drivers that have registered with the system.

Syntax

NTSTATUS IoEnumerateRegisteredFiltersList(
  [out] PDRIVER_OBJECT *DriverObjectList,
  [in]  ULONG          DriverObjectListSize,
  [out] PULONG         ActualNumberDriverObjects
);

Parameters

[out] DriverObjectList

A pointer to a caller-allocated array that receives the driver object pointers. This parameter is optional and can be NULL. (See the following Remarks section.)

[in] DriverObjectListSize

Size, in bytes, of the DriverObjectList array. Can be zero. (See the following Remarks section.)

[out] ActualNumberDriverObjects

Actual number of driver objects found. Note that if the array at DriverObjectList is too small, the number of driver object pointers that are copied into the array will be less than ActualNumberDriverObjects.

Return value

IoEnumerateRegisteredFiltersList can return one of the following:

Remarks

A file system filter driver calls IoEnumerateRegisteredFiltersList to obtain an array of pointers to the driver objects for all file system filter drivers that have called IoRegisterFsRegistrationChange.

The filter drivers are enumerated in order of decreasing distance from the base file system. The first element (index zero) in the DriverObjectList array represents the filter that is attached farthest from the file system. The second entry is for the next-farthest filter, and so on. The last entry in the array is for the filter that is closest to the base file system.

IoEnumerateRegisteredFiltersList enumerates only legacy filter drivers; it does not enumerate minifilters. To enumerate both minifilters and legacy filters, or only minifilters, call FltEnumerateFilterInformation.

The filter driver typically calls IoEnumerateRegisteredFiltersList twice: once to get the number of driver objects in the list, and once to get the driver object list itself. In the first call, the caller should set the DriverObjectList parameter to NULL and DriverObjectListSize to zero. In the second call, DriverObjectList should contain a pointer to an appropriately-sized pointer array, and DriverObjectListSize should contain the size, in bytes, of that array.

IoEnumerateRegisteredFiltersList increments the reference count on every driver object in the list pointed to by DriverObjectList. Thus every successful call to IoEnumerateRegisteredFiltersList must be matched by a subsequent call to ObDereferenceObject for each driver object in the list. Failure to do so prevents the system from freeing or deleting these driver objects because of an outstanding reference count.

Minifilters should call FltEnumerateFilterInformation or FltEnumerateFilters instead of IoEnumerateRegisteredFiltersList.

Requirements

See also

FltEnumerateFilterInformation

FltEnumerateFilters

IoRegisterFsRegistrationChange

ObDereferenceObject