Función FilterVolumeInstanceFindFirst (fltuser.h)

Artículo
08/23/2023

La función FilterVolumeInstanceFindFirst devuelve información sobre una instancia del controlador de minifiltro o un controlador de filtro heredado y se usa para comenzar a examinar los controladores de filtro que están conectados a un volumen.

Sintaxis

HRESULT FilterVolumeInstanceFindFirst(
  [in]  LPCWSTR                    lpVolumeName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpVolumeInstanceFind
);

Parámetros

[in] lpVolumeName

Puntero a una cadena de caracteres anchos terminada en NULL que contiene el nombre del volumen al que se adjunta la instancia de minifiltro o el filtro heredado.

La cadena de entrada lpVolumeName puede ser cualquiera de las siguientes. La barra diagonal inversa final (\) es opcional.

Una letra de unidad, como D:\
Ruta de acceso a un punto de montaje de volumen, como c:\mnt\edrive\
Un identificador de volumen único (también denominado nombre GUID de volumen), como \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Un nombre de dispositivo no persistente (también denominado nombre de destino o un nombre de dispositivo NT), como \Device\HarddiskVolume1\

[in] dwInformationClass

Tipo de estructura de información del controlador de filtro devuelta. Este parámetro debe contener uno de los valores siguientes.

Valor	Significado
InstanceBasicInformation	Devuelve una estructura de INSTANCE_BASIC_INFORMATION para una instancia de minifiltro. Se omiten los controladores de filtro heredados.
InstanceFullInformation	Devuelve una estructura de INSTANCE_FULL_INFORMATION para una instancia de minifiltro. Se omiten los controladores de filtro heredados.
InstancePartialInformation	Devuelve una estructura de INSTANCE_PARTIAL_INFORMATION para una instancia de minifiltro. Se omiten los controladores de filtro heredados.
InstanceAggregateStandardInformation	Devuelve una estructura de INSTANCE_AGGREGATE_STANDARD_INFORMATION para la instancia. El miembro 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 lpBuffer apunta si la llamada a FilterVolumeInstanceFindFirst se realiza correctamente. Este parámetro es obligatorio y no puede ser NULL.

[out] lpVolumeInstanceFind

Puntero a una variable asignada por el autor de la llamada que recibe un identificador de búsqueda para la instancia de minifiltro o el filtro heredado (solo cuando se especifica InstanceAggregateStandardInformation ) si la llamada a FilterVolumeInstanceFindFirst se realiza correctamente. De lo contrario, lpVolumeInstanceFind recibe INVALID_HANDLE_VALUE. Este identificador de búsqueda se puede usar en llamadas posteriores a FilterVolumeInstanceFindNext y FilterVolumeInstanceFindClose.

Valor devuelto

FilterVolumeInstanceFindFirst 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 un sistema operativo antes de Windows Vista, FilterVolumeInstanceFindFirst devuelve este valor HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	No se encontró un controlador de filtro en el volumen especificado.

Comentarios

La función FilterVolumeInstanceFindFirst abre un identificador de búsqueda y devuelve información sobre el primer controlador de filtro encontrado que está asociado al volumen denominado por lpVolumeName. Una vez establecido el identificador de búsqueda, llame a FilterVolumeInstanceFindNext para buscar otros controladores de filtro que estén conectados al mismo volumen. Cuando el identificador de búsqueda ya no sea necesario, ciérrelo llamando a FilterVolumeInstanceFindClose.

A partir de Windows Vista, FilterVolumeInstanceFindFirst puede devolver tanto la información del controlador de filtro heredado como la información de la instancia del controlador de minifiltro cuando el valor del parámetro dwInformationClass es InstanceAggregateStandardInformation. En el caso de los sistemas operativos anteriores, esta función no puede devolver información de filtro heredada porque la estructura de INSTANCE_AGGREGATE_STANDARD_INFORMATION no está disponible.