Función FilterFindFirst (fltuser.h)

Artículo
08/23/2023

La función FilterFindFirst devuelve información sobre un controlador de filtro (instancia de controlador de minifiltro o controlador de filtro heredado) y se usa para comenzar a examinar los filtros en la lista global de filtros registrados.

Sintaxis

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

Parámetros

[in] dwInformationClass

Tipo de información del controlador de filtro solicitada. Este parámetro puede ser uno de los siguientes valores.

Value	Significado
FilterFullInformation	El búfer al que apunta el parámetro lpBuffer recibe una estructura de FILTER_FULL_INFORMATION para cada instancia de minifiltro. Se omiten los filtros heredados.
FilterAggregateBasicInformation	El búfer al que apunta el parámetro lpBuffer recibe una estructura de FILTER_AGGREGATE_BASIC_INFORMATION para cada instancia de minifiltro o filtro heredado. Este valor dwInformationClass está disponible a partir de Windows Server 2003 con SP1 y Windows XP con SP2 con el paquete acumulativo del administrador de filtros. Para obtener más información sobre el paquete acumulativo del administrador de filtros para Windows XP con SP2, vea el artículo 914882, " El paquete acumulativo del administrador de filtros para Windows XP SP2", en Microsoft Knowledge Base.
FilterAggregateStandardInformation	El búfer al que apunta el parámetro lpBuffer recibe una estructura de FILTER_AGGREGATE_STANDARD_INFORMATION para cada instancia de minifiltro o filtro heredado. Este valor dwInformationClass está disponible a partir de Windows Vista.

[out] lpBuffer

Puntero a un búfer asignado por el autor de la llamada que recibe la información solicitada. El tipo de la información devuelta en el búfer se define mediante el parámetro dwInformationClass .

[in] dwBufferSize

Tamaño, en bytes, del búfer al que apunta el parámetro lpBuffer . El autor de la llamada debe establecer este parámetro según el dwInformationClass especificado.

[out] lpBytesReturned

Puntero a una variable asignada por el autor de la llamada que recibe el número de bytes devueltos en el búfer al que lpBuffer apunta si la llamada a FilterFindFirst se realiza correctamente. Este parámetro es obligatorio y no puede ser NULL.

[out] lpFilterFind

Puntero a una variable asignada por el autor de la llamada que recibe un identificador de búsqueda para el controlador de filtro si la llamada a FilterFindFirst se realiza correctamente; de lo contrario, recibe INVALID_HANDLE_VALUE. Este identificador de búsqueda se puede usar en llamadas posteriores a FilterFindNext y FilterFindClose.

Valor devuelto

FilterFindFirst devuelve S_OK si se ejecuta correctamente. De lo contrario, devuelve un valor de error HRESULT, como uno de los siguientes:

Código devuelto	Descripción
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	El búfer al que apunta lpBuffer no es lo suficientemente grande como para contener la información solicitada. Cuando se devuelve este valor, lpBytesReturned contendrá el tamaño, en bytes, del búfer necesario para la estructura dwInformationClass especificada.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	Se especificó un valor no válido para el parámetro dwInformationClass . Por ejemplo, si se especifica FilterAggregateStandardInformation para un sistema operativo anterior a Windows Vista, FilterFindFirst devuelve este valor HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	No se encontró un controlador de filtro en la lista global de filtros registrados.

Comentarios

La función FilterFindFirst abre un identificador de búsqueda y devuelve información sobre el primer controlador de filtro que se encuentra en la lista global de filtros registrados. Una vez establecido el identificador de búsqueda, llame a la función FilterFindNext para buscar otros filtros en la lista global. Cuando el identificador de búsqueda ya no sea necesario, ciérralo llamando a FilterFindClose.

A partir de Microsoft Windows Server 2003 con SP1 y Windows XP con Service Pack 1 (SP1) con el paquete acumulativo del administrador de filtros, FilterFindFirst y FilterFindNext pueden proporcionar información del controlador de filtro heredado y la información de la instancia del controlador de minifiltro. En versiones anteriores de Windows, FilterFindFirst y FilterFindNext solo pueden proporcionar información sobre minifiltros (consulte la descripción del parámetro dwInformationClass anterior).

FilterFindFirst y FilterFindNext devuelven información sobre los controladores de filtro para reducir la distancia desde el sistema de archivos base. Primero se devuelve información sobre el filtro más alejado del sistema de archivos base. Se devuelve información sobre el segundo filtro más lejano. La información sobre el filtro más cercano al sistema de archivos base se devuelve en último lugar.

Si la entrada dwBufferSize es demasiado pequeña, lpFilterFind recibe INVALID_HANDLE_VALUE y lpBytesReturned recibe el número de bytes necesarios para almacenar la información solicitada.