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

返回的筛选器驱动程序信息结构的类型。此参数必须包含以下值之一。

Value	含义
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

指向调用方分配的变量的指针，如果对 FilterVolumeInstanceFindFirst 的调用成功，该变量接收 lpBuffer 指向的缓冲区中返回的字节数。此参数是必需的，不能为 NULL。

[out] lpVolumeInstanceFind

指向调用方分配的变量的指针，该变量仅在对 FilterVolumeInstanceFindFirst 的调用成功的情况下指定 InstanceAggregateStandardInformation 时) (接收微筛选器实例或旧筛选器的搜索句柄。否则， 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 参数指定了无效值。例如，如果为 Windows Vista 之前的操作系统指定了 InstanceAggregateStandardInformation ，则 FilterVolumeInstanceFindFirst 将返回此 HRESULT 值。
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)	在给定卷上找不到筛选器驱动程序。

备注

FilterVolumeInstanceFindFirst 函数打开搜索句柄，并返回有关找到的第一个筛选器驱动程序的信息，该驱动程序附加到由 lpVolumeName 命名的卷。建立搜索句柄后，调用 FilterVolumeInstanceFindNext 以搜索附加到同一卷的其他筛选器驱动程序。如果不再需要搜索句柄，请通过调用 FilterVolumeInstanceFindClose 将其关闭。

从 Windows Vista 开始，当 dwInformationClass 参数的值为 InstanceAggregateStandardInformation 时，FilterVolumeInstanceFindFirst 可以返回旧版筛选器驱动程序信息和微筛选器驱动程序实例信息。对于早期操作系统，此函数无法返回旧筛选器信息，因为INSTANCE_AGGREGATE_STANDARD_INFORMATION结构不可用。