FilterVolumeFindFirst 函数 (fltuser.h)

项目
08/23/2023

FilterVolumeFindFirst 函数返回有关卷的信息。

语法

HRESULT FilterVolumeFindFirst(
  [in]  FILTER_VOLUME_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                          lpBuffer,
  [in]  DWORD                           dwBufferSize,
  [out] LPDWORD                         lpBytesReturned,
  [out] PHANDLE                         lpVolumeFind
);

参数

[in] dwInformationClass

请求的信息类型。此参数的取值可为下列值之一：

值	含义
FilterVolumeBasicInformation	lpBuffer 参数指向的缓冲区接收卷的FILTER_VOLUME_BASIC_INFORMATION结构。
FilterVolumeStandardInformation	lpBuffer 参数指向的缓冲区接收卷的FILTER_VOLUME_STANDARD_INFORMATION结构。此结构从 Windows Vista 开始可用。

[out] lpBuffer

指向调用方分配的缓冲区的指针，该缓冲区接收请求的信息。缓冲区中返回的信息的类型由 dwInformationClass 参数定义。

[in] dwBufferSize

lpBuffer 参数指向的缓冲区的大小（以字节为单位）。调用方应根据给定的 dwInformationClass 设置此参数。

[out] lpBytesReturned

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

[out] lpVolumeFind

指向调用方分配的变量的指针，如果对 FilterVolumeFindFirst 的调用成功，该变量接收微筛选器的搜索句柄;否则，它将接收INVALID_HANDLE_VALUE。此搜索句柄可用于对 FilterVolumeFindNext 和 FilterVolumeFindClose 的后续调用。

返回值

如果 FilterVolumeFindFirst 成功返回有关卷的信息，则返回S_OK。否则，它将返回 HRESULT 错误值，如以下值之一：

返回代码	说明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	lpBuffer 指向的缓冲区不够大，无法包含请求的信息。返回此值时， lpBytesReturned 将包含给定 dwInformationClass 结构所需的缓冲区大小（以字节为单位）。
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	为 dwInformationClass 参数指定了无效值。例如，如果为 Windows Vista 之前的操作系统指定了 FilterVolumeStandardInformation ，则 FilterVolumeFindFirst 将返回此 HRESULT 值。
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)	在筛选器管理器已知的卷列表中找不到卷。

备注

此 FilterVolumeFindFirst 函数用于开始扫描筛选器管理器已知的卷。

FilterVolumeFindFirst 打开一个搜索句柄，并返回有关筛选器管理器已知卷列表中找到的第一个卷的信息。建立搜索句柄后，使用 FilterVolumeFindNext 函数搜索筛选器管理器列表中的其他卷。如果不再需要搜索句柄，请通过调用 FilterVolumeFindClose 将其关闭。

请注意，使用 FilterVolumeFindFirst 和 FilterVolumeFindNext 枚举筛选器管理器已知的卷列表时，列表中的两个或更多卷可能具有相同的名称。有关详细信息，请参阅了解具有重复卷名称的卷枚举。