Função FilterVolumeFindFirst (fltuser.h)

Artigo
03/09/2023

A função FilterVolumeFindFirst retorna informações sobre um volume.

Sintaxe

HRESULT FilterVolumeFindFirst(
  [in]  FILTER_VOLUME_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                          lpBuffer,
  [in]  DWORD                           dwBufferSize,
  [out] LPDWORD                         lpBytesReturned,
  [out] PHANDLE                         lpVolumeFind
);

Parâmetros

[in] dwInformationClass

Tipo de informações solicitadas. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
FilterVolumeBasicInformation	O buffer apontado pelo parâmetro lpBuffer recebe uma estrutura FILTER_VOLUME_BASIC_INFORMATION para o volume.
FilterVolumeStandardInformation	O buffer apontado pelo parâmetro lpBuffer recebe uma estrutura FILTER_VOLUME_STANDARD_INFORMATION para o volume. 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 FilterVolumeFindFirst for bem-sucedida. Esse parâmetro é necessário e não pode ser NULL.

[out] lpVolumeFind

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

Valor retornado

FilterVolumeFindFirst retornará S_OK se retornar informações sobre um volume com ê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 FilterVolumeStandardInformation for especificado para um sistema operacional antes do Windows Vista, FilterVolumeFindFirst retornará esse valor HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Um volume não foi encontrado na lista de volumes conhecidos pelo gerenciador de filtros.

Comentários

Essa função FilterVolumeFindFirst é usada para começar a digitalizar os volumes que são conhecidos pelo gerenciador de filtros.

FilterVolumeFindFirst abre um identificador de pesquisa e retorna informações sobre o primeiro volume encontrado na lista de volumes conhecidos pelo gerenciador de filtros. Depois que o identificador de pesquisa tiver sido estabelecido, use a função FilterVolumeFindNext para pesquisar outros volumes na lista do gerenciador de filtros. Quando o identificador de pesquisa não for mais necessário, feche-o chamando FilterVolumeFindClose.

Observe que, ao usar FilterVolumeFindFirst e FilterVolumeFindNext para enumerar a lista de volumes conhecidos pelo gerenciador de filtros, é possível que dois ou mais volumes na lista tenham o mesmo nome. Para obter mais informações, consulte Noções básicas sobre enumerações de volume com nomes de volume duplicados.