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

Статья
08/23/2023

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

Синтаксис

HRESULT FilterVolumeInstanceFindFirst(
  [in]  LPCWSTR                    lpVolumeName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpVolumeInstanceFind
);

Параметры

[in] lpVolumeName

Указатель на строку расширенных символов, завершающуюся null, которая содержит имя тома, к которому присоединен экземпляр минифильтра или устаревший фильтр.

Входная строка lpVolumeName может быть любой из следующих. Обратная косая черта в конце (\) является необязательной.

Буква диска, например D:\
Путь к точке подключения тома, например c:\mnt\edrive\
Уникальный идентификатор тома (также называемый именем GUID тома), например \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Неперсистентное имя устройства (также называемое целевым именем или именем устройства NT), например \Device\HarddiskVolume1\

[in] dwInformationClass

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

Значение	Значение
InstanceBasicInformation	Возвращает структуру INSTANCE_BASIC_INFORMATION для экземпляра минифильтра. Устаревшие драйверы фильтров игнорируются.
InstanceFullInformation	Возвращает структуру INSTANCE_FULL_INFORMATION для экземпляра минифильтра. Устаревшие драйверы фильтров игнорируются.
InstancePartialInformation	Возвращает структуру INSTANCE_PARTIAL_INFORMATION для экземпляра минифильтра. Устаревшие драйверы фильтров игнорируются.
InstanceAggregateStandardInformation	Возвращает структуру INSTANCE_AGGREGATE_STANDARD_INFORMATION для экземпляра . Элемент LegacyFilter структуры не используется. Эта структура доступна начиная с Windows Vista.

[out] lpBuffer

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

[in] dwBufferSize

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

[out] lpBytesReturned

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

[out] lpVolumeInstanceFind

Указатель на переменную, выделенную вызывающим объектом, которая получает дескриптор поиска для экземпляра минифильтра или устаревшего фильтра (только при указании InstanceAggregateStandardInformation ), если вызов FilterVolumeInstanceFindFirst выполнен успешно. В противном случае lpVolumeInstanceFind получает INVALID_HANDLE_VALUE. Этот дескриптор поиска можно использовать в последующих вызовах FilterVolumeInstanceFindNext и FilterVolumeInstanceFindClose.

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

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

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

Функция FilterVolumeInstanceFindFirst открывает дескриптор поиска и возвращает сведения о первом обнаруженном драйвере фильтра, присоединенном к тому с именем lpVolumeName. После установки дескриптора поиска вызовите FilterVolumeInstanceFindNext для поиска других драйверов фильтров, подключенных к тому же. Если дескриптор поиска больше не нужен, закройте его, вызвав FilterVolumeInstanceFindClose.

Начиная с Windows Vista FilterVolumeInstanceFindFirst может возвращать как устаревшие сведения о драйвере фильтра, так и сведения об экземпляре драйвера минифильтра, если параметр dwInformationClass имеет значение InstanceAggregateStandardInformation. Для более ранних операционных систем эта функция не может возвращать устаревшие сведения о фильтре, так как структура INSTANCE_AGGREGATE_STANDARD_INFORMATION недоступна.

Требования


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