Função FilterInstanceFindFirst (fltuser.h)

Artigo
08/23/2023

A função FilterInstanceFindFirst retorna informações sobre uma instância de driver de minifiltro e é usada como ponto de partida para verificar as instâncias de um minifiltro.

Sintaxe

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

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém o nome do driver de minifiltro que possui a instância.

[in] dwInformationClass

O tipo de estrutura de informações da instância retornada. Esse parâmetro deve usar um dos valores a seguir.

Valor	Significado
InstanceBasicInformation	Retornar uma estrutura de INSTANCE_BASIC_INFORMATION para a instância.
InstanceFullInformation	Retornar uma estrutura de INSTANCE_FULL_INFORMATION para a instância.
InstancePartialInformation	Retornar uma estrutura de INSTANCE_PARTIAL_INFORMATION para a instância.
InstanceAggregateStandardInformation	Retornar uma estrutura de INSTANCE_AGGREGATE_STANDARD_INFORMATION para a instância. A parte LegacyFilter da estrutura não é utilizada. 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 por chamador que recebe o número de bytes retornados no buffer para o qual lpBuffer aponta, se a chamada para FilterInstanceFindFirst for bem-sucedida. Esse parâmetro é necessário e não pode ser NULL.

[out] lpFilterInstanceFind

Ponteiro para uma variável alocada pelo chamador que recebe um identificador de pesquisa para o minifiltro se a chamada para FilterInstanceFindFirst for bem-sucedida; caso contrário, ele receberá INVALID_HANDLE_VALUE. Esse identificador de pesquisa pode ser usado em chamadas subsequentes para FilterInstanceFindNext e FilterInstanceFindClose.

Valor retornado

FilterInstanceFindFirst retorna 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 for 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 sistemas operacionais antes do Windows Vista, a função retornará esse valor HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	O minifiltro especificado pelo parâmetro lpFilterName não tem uma instância na pilha do sistema de arquivos.

Comentários

A função FilterInstanceFindFirst abre um identificador de pesquisa e retorna informações sobre uma instância do minifiltro chamado por lpFilterName. Depois que o identificador de pesquisa tiver sido estabelecido, chame FilterInstanceFindNext para pesquisar outras instâncias do mesmo minifiltro. Quando o identificador de pesquisa não for mais necessário, feche-o chamando FilterInstanceFindClose.