Función FilterInstanceFindFirst (fltuser.h)

Artículo
08/23/2023

La función FilterInstanceFindFirst devuelve información sobre una instancia de controlador de minifiltro y se usa como punto de partida para examinar las instancias de un minifiltro.

Sintaxis

HRESULT FilterInstanceFindFirst(
  [in]  LPCWSTR                    lpFilterName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpFilterInstanceFind
);

Parámetros

[in] lpFilterName

Puntero a una cadena de caracteres anchos terminada en NULL que contiene el nombre del controlador de minifiltro que posee la instancia.

[in] dwInformationClass

Tipo de estructura de información de instancia devuelta. Este parámetro puede ser uno de los siguientes valores.

Value	Significado
InstanceBasicInformation	Devuelve una estructura de INSTANCE_BASIC_INFORMATION para la instancia de .
InstanceFullInformation	Devuelve una estructura de INSTANCE_FULL_INFORMATION para la instancia de .
InstancePartialInformation	Devuelve una estructura de INSTANCE_PARTIAL_INFORMATION para la instancia de .
InstanceAggregateStandardInformation	Devuelve una estructura de INSTANCE_AGGREGATE_STANDARD_INFORMATION para la instancia de . La parte LegacyFilter de la estructura no se utiliza. Esta estructura 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 apunta lpBuffer , si la llamada a FilterInstanceFindFirst se realiza correctamente. Este parámetro es obligatorio y no puede ser NULL.

[out] lpFilterInstanceFind

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

Valor devuelto

FilterInstanceFindFirst 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 instanceAggregateStandardInformation se especifica para los sistemas operativos anteriores a Windows Vista, la función devuelve este valor HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	El minifiltro especificado por el parámetro lpFilterName no tiene una instancia en la pila del sistema de archivos.

Comentarios

La función FilterInstanceFindFirst abre un identificador de búsqueda y devuelve información sobre una instancia del minifiltro denominado lpFilterName. Una vez establecido el identificador de búsqueda, llame a FilterInstanceFindNext para buscar otras instancias del mismo minifiltro. Cuando el identificador de búsqueda ya no sea necesario, ciérralo llamando a FilterInstanceFindClose.