Função FilterVolumeInstanceFindFirst (fltuser.h)

Artigo
08/23/2023

A função FilterVolumeInstanceFindFirst retorna informações sobre uma instância de driver de minifiltro ou driver de filtro herdado e é usada para começar a verificar os drivers de filtro anexados a um volume.

Sintaxe

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

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém o nome do volume ao qual a instância de minifiltro ou o filtro herdado está anexado.

A cadeia de caracteres de entrada lpVolumeName pode ser qualquer uma das seguintes. A barra invertida à direita (\) é opcional.

Uma letra da unidade, como D:\
Um caminho para um ponto de montagem de volume, como c:\mnt\edrive\
Um identificador de volume exclusivo (também chamado de nome GUID do volume), como \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Um nome de dispositivo não persistente (também chamado de nome de destino ou nome de dispositivo NT), como \Device\HarddiskVolume1\

[in] dwInformationClass

O tipo de estrutura de informações do driver de filtro retornado. Esse parâmetro deve conter um dos valores a seguir.

Valor	Significado
InstanceBasicInformation	Retornar uma estrutura INSTANCE_BASIC_INFORMATION para uma instância de minifiltro. Os drivers de filtro herdados são ignorados.
InstanceFullInformation	Retornar uma estrutura INSTANCE_FULL_INFORMATION para uma instância de minifiltro. Os drivers de filtro herdados são ignorados.
InstancePartialInformation	Retornar uma estrutura de INSTANCE_PARTIAL_INFORMATION para uma instância de minifiltro. Os drivers de filtro herdados são ignorados.
InstanceAggregateStandardInformation	Retornar uma estrutura de INSTANCE_AGGREGATE_STANDARD_INFORMATION para a instância. O membro LegacyFilter da estrutura não é utilizado. Essa estrutura está disponível a partir do Windows Vista.

[out] lpBuffer

Ponteiro para um buffer alocado pelo chamador que recebe as informações solicitadas. O tipo das informações retornadas no buffer é definido pelo parâmetro dwInformationClass .

[in] dwBufferSize

Tamanho, em bytes, do buffer para o qual o parâmetro lpBuffer aponta. O chamador deve definir esse parâmetro de acordo com o dwInformationClass especificado.

[out] lpBytesReturned

Ponteiro para uma variável alocada pelo chamador que recebe o número de bytes retornados no buffer para o qual lpBuffer aponta se a chamada para FilterVolumeInstanceFindFirst for bem-sucedida. Esse parâmetro é necessário e não pode ser NULL.

[out] lpVolumeInstanceFind

Ponteiro para uma variável alocada pelo chamador que recebe um identificador de pesquisa para a instância de minifiltro ou filtro herdado (somente quando InstanceAggregateStandardInformation é especificado) se a chamada para FilterVolumeInstanceFindFirst for bem-sucedida. Caso contrário, lpVolumeInstanceFind receberá INVALID_HANDLE_VALUE. Esse identificador de pesquisa pode ser usado em chamadas subsequentes para FilterVolumeInstanceFindNext e FilterVolumeInstanceFindClose.

Valor retornado

FilterVolumeInstanceFindFirst retornará S_OK se tiver êxito. Caso contrário, ele retornará um valor de erro HRESULT, como um dos seguintes:

Código de retorno	Descrição
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	O buffer apontado por lpBuffer não é grande o suficiente para conter as informações solicitadas. Quando esse valor é retornado, lpBytesReturned conterá o tamanho, em bytes, do buffer necessário para a estrutura dwInformationClass fornecida.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	Um valor inválido foi especificado para o parâmetro dwInformationClass . Por exemplo, se InstanceAggregateStandardInformation for especificado para um sistema operacional antes do Windows Vista, FilterVolumeInstanceFindFirst retornará esse valor HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Um driver de filtro não foi encontrado no volume especificado.

Comentários

A função FilterVolumeInstanceFindFirst abre um identificador de pesquisa e retorna informações sobre o primeiro driver de filtro encontrado anexado ao volume chamado por lpVolumeName. Depois que o identificador de pesquisa tiver sido estabelecido, chame FilterVolumeInstanceFindNext para pesquisar outros drivers de filtro anexados ao mesmo volume. Quando o identificador de pesquisa não for mais necessário, feche-o chamando FilterVolumeInstanceFindClose.

A partir do Windows Vista, FilterVolumeInstanceFindFirst pode retornar informações de driver de filtro herdado e informações de instância de driver de minifiltro quando o valor do parâmetro dwInformationClass é InstanceAggregateStandardInformation. Para sistemas operacionais anteriores, essa função não pode retornar informações de filtro herdadas porque a estrutura INSTANCE_AGGREGATE_STANDARD_INFORMATION não está disponível.