Funzione FilterVolumeInstanceFindFirst (fltuser.h)

Articolo
08/23/2023

La funzione FilterVolumeInstanceFindFirst restituisce informazioni su un'istanza del driver minifilter o un driver di filtro legacy e viene usata per iniziare a analizzare i driver di filtro collegati a un volume.

Sintassi

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

Parametri

[in] lpVolumeName

Puntatore a una stringa di caratteri wide-carattere con terminazione null contenente il nome del volume a cui è associata l'istanza del minifilter o il filtro legacy.

La stringa di input lpVolumeName può essere una delle seguenti. La barra rovesciata finale (\) è facoltativa.

Lettera di unità, ad esempio D:\
Percorso di un punto di montaggio del volume, ad esempio c:\mnt\edrive\
Identificatore di volume univoco (denominato anche nome GUID del volume), ad esempio \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Nome del dispositivo nonpersistent (chiamato anche nome di destinazione o nome di dispositivo NT), ad esempio \Device\HarddiskVolume1\

[in] dwInformationClass

Tipo di struttura di informazioni sul driver di filtro restituito. Questo parametro deve contenere uno dei valori seguenti.

Valore	Significato
InstanceBasicInformation	Restituisce una struttura INSTANCE_BASIC_INFORMATION per un'istanza di minifilter. I driver di filtro legacy vengono ignorati.
InstanceFullInformation	Restituisce una struttura INSTANCE_FULL_INFORMATION per un'istanza di minifilter. I driver di filtro legacy vengono ignorati.
InstancePartialInformation	Restituisce una struttura INSTANCE_PARTIAL_INFORMATION per un'istanza di minifilter. I driver di filtro legacy vengono ignorati.
InstanceAggregateStandardInformation	Restituire una struttura INSTANCE_AGGREGATE_STANDARD_INFORMATION per l'istanza. Il membro LegacyFilter della struttura non viene usato. Questa struttura è disponibile a partire da Windows Vista.

[out] lpBuffer

Puntatore a un buffer allocato dal chiamante che riceve le informazioni richieste. Il tipo delle informazioni restituite nel buffer è definito dal parametro dwInformationClass .

[in] dwBufferSize

Dimensioni, in byte, del buffer a cui punta il parametro lpBuffer . Il chiamante deve impostare questo parametro in base all'oggetto dwInformationClass specificato.

[out] lpBytesReturned

Puntatore a una variabile allocata dal chiamante che riceve il numero di byte restituiti nel buffer a cui lpBuffer punta se la chiamata a FilterVolumeInstanceFindFirst riesce. Questo parametro è obbligatorio e non può essere NULL.

[out] lpVolumeInstanceFind

Puntatore a una variabile allocata dal chiamante che riceve un handle di ricerca per l'istanza di minifilter o il filtro legacy (solo quando si specifica InstanceAggregateStandardInformation ) se la chiamata a FilterVolumeInstanceFindFirst riesce. In caso contrario, lpVolumeInstanceFind riceve INVALID_HANDLE_VALUE. Questo handle di ricerca può essere usato nelle chiamate successive a FilterVolumeInstanceFindNext e FilterVolumeInstanceFindClose.

Valore restituito

FilterVolumeInstanceFindFirst restituisce S_OK se riuscito. In caso contrario, restituisce un valore di errore HRESULT, ad esempio uno dei seguenti:

Codice restituito	Descrizione
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	Il buffer a cui punta lpBuffer non è sufficiente per contenere le informazioni richieste. Quando viene restituito questo valore, lpBytesReturned conterrà le dimensioni, in byte, del buffer necessario per la struttura dwInformationClass specificata.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	È stato specificato un valore non valido per il parametro dwInformationClass . Ad esempio, se InstanceAggregateStandardInformation viene specificato per un sistema operativo prima di Windows Vista, FilterVolumeInstanceFindFirst restituisce questo valore HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Un driver di filtro non è stato trovato nel volume specificato.

Commenti

La funzione FilterVolumeInstanceFindFirst apre un handle di ricerca e restituisce informazioni sul primo driver di filtro trovato collegato al volume denominato da lpVolumeName. Dopo aver stabilito l'handle di ricerca, chiamare FilterVolumeInstanceFindNext per cercare altri driver di filtro collegati allo stesso volume. Quando l'handle di ricerca non è più necessario, chiuderlo chiamando FilterVolumeInstanceFindClose.

A partire da Windows Vista, FilterVolumeInstanceFindFirst può restituire informazioni sul driver di filtro legacy e informazioni sull'istanza del driver minifilter quando il valore del parametro dwInformationClass è InstanceAggregateStandardInformation. Per i sistemi operativi precedenti, questa funzione non può restituire informazioni sul filtro legacy perché la struttura INSTANCE_AGGREGATE_STANDARD_INFORMATION non è disponibile.