FilterFindFirst 函数 (fltuser.h)

项目
03/05/2024

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 SP1 开始可用，使用带有筛选器管理器汇总的 SP2 的 Windows XP 可用。有关带有 SP2 的 Windows XP 筛选器管理器汇总包的详细信息，请参阅 Microsoft 知识库中的文章914882“ 适用于 Windows XP SP2 的筛选器管理器汇总包”。
FilterAggregateStandardInformation	lpBuffer 参数指向的缓冲区接收每个微筛选器实例或旧筛选器的FILTER_AGGREGATE_STANDARD_INFORMATION结构。此 dwInformationClass 值从 Windows Vista 开始可用。

[out] lpBuffer

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

[in] dwBufferSize

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

[out] lpBytesReturned

指向调用方分配的变量的指针，如果对 FilterFindFirst 的调用成功，该变量接收 lpBuffer 指向的缓冲区中返回的字节数。此参数是必需的，不能为 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 参数指定了无效值。例如，如果为 Windows Vista 之前的操作系统指定了 FilterAggregateStandardInformation ，则 FilterFindFirst 将返回此 HRESULT 值。
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)	在已注册的筛选器的全局列表中找不到筛选器驱动程序。

注解

FilterFindFirst 函数打开一个搜索句柄，并返回有关在已注册筛选器的全局列表中找到的第一个筛选器驱动程序的信息。建立搜索句柄后，调用 FilterFindNext 函数以搜索全局列表中的其他筛选器。如果不再需要搜索句柄，请通过调用 FilterFindClose 将其关闭。

从具有 SP1 的 Microsoft Windows Server 2003 和具有 Service Pack 1 的 Windows XP 开始， (SP1) 筛选器管理器汇总， FilterFindFirst 和 FilterFindNext 可以提供旧版筛选器驱动程序信息和微筛选器驱动程序实例信息。在早期版本的 Windows 上， FilterFindFirst 和 FilterFindNext 只能提供有关微筛选器的信息 (请参阅上述 dwInformationClass 参数的说明) 。

FilterFindFirst 和 FilterFindNext 按与基本文件系统的距离减小的顺序返回有关筛选器驱动程序的信息。首先返回离基本文件系统最远的筛选器的信息。有关第二远筛选器的信息将返回第二个。最后返回最靠近基本文件系统的筛选器的信息。

如果输入 dwBufferSize 太小，lpFilterFind 接收INVALID_HANDLE_VALUE，lpBytesReturned 接收存储所请求信息所需的字节数。