Функция FilterFindFirst (fltuser.h)

Статья
08/23/2023

Функция FilterFindFirst возвращает сведения о драйвере фильтра (экземпляре драйвера минифильтра или устаревшем драйвере фильтра) и используется для начала сканирования фильтров в глобальном списке зарегистрированных фильтров.

Синтаксис

HRESULT FilterFindFirst(
  [in]  FILTER_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                   lpBuffer,
  [in]  DWORD                    dwBufferSize,
  [out] LPDWORD                  lpBytesReturned,
  [out] LPHANDLE                 lpFilterFind
);

Параметры

[in] dwInformationClass

Тип запрошенной информации о драйвере фильтра. Этот параметр должен иметь одно из следующих значений.

Значение	Значение
FilterFullInformation	Буфер, на который указывает параметр lpBuffer , получает структуру FILTER_FULL_INFORMATION для каждого экземпляра минифильтра. Устаревшие фильтры игнорируются.
FilterAggregateBasicInformation	Буфер, на который указывает параметр lpBuffer , получает FILTER_AGGREGATE_BASIC_INFORMATION структуру для каждого экземпляра минифильтра или устаревшего фильтра. Это значение dwInformationClass доступно начиная с Windows Server 2003 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (SP2) с накопительным пакетом обновления диспетчера фильтров. Дополнительные сведения о накопительном пакете диспетчера фильтров для Windows XP с пакетом обновления 2 (SP2) см. в статье 914882 " Накопительный пакет диспетчера фильтров для Windows XP с пакетом обновления 2 (SP2) в базе знаний Майкрософт.
FilterAggregateStandardInformation	Буфер, на который указывает параметр lpBuffer , получает структуру FILTER_AGGREGATE_STANDARD_INFORMATION для каждого экземпляра минифильтра или устаревшего фильтра. Это значение dwInformationClass доступно начиная с Windows Vista.

[out] lpBuffer

Указатель на буфер, выделенный вызывающим объектом, который получает запрошенные сведения. Тип сведений, возвращаемых в буфере, определяется параметром dwInformationClass .

[in] dwBufferSize

Размер (в байтах) буфера, на который указывает параметр lpBuffer . Вызывающий объект должен задать этот параметр в соответствии с заданным dwInformationClass.

[out] lpBytesReturned

Указатель на переменную, выделенную вызывающим объектом, которая получает количество байтов, возвращаемых в буфере, на которое указывает lpBuffer , если вызов FilterFindFirst завершается успешно. Этот параметр является обязательным и не может иметь значение NULL.

[out] lpFilterFind

Указатель на переменную, выделенную вызывающим объектом, которая получает дескриптор поиска для драйвера фильтра при успешном вызове FilterFindFirst ; в противном случае он получает INVALID_HANDLE_VALUE. Этот дескриптор поиска можно использовать в последующих вызовах FilterFindNext и FilterFindClose.

Возвращаемое значение

FilterFindFirst возвращает S_OK в случае успешного выполнения. В противном случае возвращается значение ошибки HRESULT, например одно из следующих значений:

Код возврата	Описание
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Буфер, на который указывает lpBuffer , недостаточно велик, чтобы содержать запрошенные сведения. При возвращении этого значения lpBytesReturned будет содержать размер буфера, необходимого для данной структуры dwInformationClass , в байтах.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	Для параметра dwInformationClass указано недопустимое значение. Например, если параметр FilterAggregateStandardInformation указан для операционной системы, предшествующей Windows Vista, функция FilterFindFirst возвращает это значение HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Драйвер фильтра не найден в глобальном списке зарегистрированных фильтров.

Функция FilterFindFirst открывает дескриптор поиска и возвращает сведения о первом драйвере фильтра, который находится в глобальном списке зарегистрированных фильтров. После установки дескриптора поиска вызовите функцию FilterFindNext для поиска других фильтров в глобальном списке. Если дескриптор поиска больше не требуется, закройте его, вызвав FilterFindClose.

Начиная с Microsoft Windows Server 2003 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 1 (SP1) с накопительным пакетом обновления диспетчера фильтров , FilterFindFirst и FilterFindNext могут предоставлять устаревшие сведения о драйвере фильтра и сведения об экземпляре драйвера минифильтра. В более ранних версиях Windows FilterFindFirst и FilterFindNext могут предоставлять только сведения о минифильтрах (см. описание параметра dwInformationClass выше).

FilterFindFirst и FilterFindNext возвращают сведения о драйверах фильтров в порядке уменьшения расстояния от базовой файловой системы. Сначала возвращаются сведения о фильтре, наиболее удаленном от базовой файловой системы. Сведения о втором самом дальнем фильтре возвращаются вторым. Последними возвращаются сведения о фильтре, наиболее близком к базовой файловой системе.

Если входной параметр dwBufferSize слишком мал, lpFilterFind получает INVALID_HANDLE_VALUE, а lpBytesReturned получает количество байтов, необходимое для хранения запрошенной информации.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltuser.h (включая FltUser.h)
Библиотека	FltLib.lib
DLL	FltLib.dll