Funzione FilterInstanceFindFirst (fltuser.h)

Articolo
08/23/2023

La funzione FilterInstanceFindFirst restituisce informazioni su un'istanza del driver minifilter e viene usata come punto di partenza per analizzare le istanze di un minifilter.

Sintassi

HRESULT FilterInstanceFindFirst(
  [in]  LPCWSTR                    lpFilterName,
  [in]  INSTANCE_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                     lpBuffer,
  [in]  DWORD                      dwBufferSize,
  [out] LPDWORD                    lpBytesReturned,
  [out] LPHANDLE                   lpFilterInstanceFind
);

Parametri

[in] lpFilterName

Puntatore a una stringa di caratteri wide-character con terminazione null contenente il nome del driver minifilter proprietario dell'istanza.

[in] dwInformationClass

Tipo di struttura delle informazioni dell'istanza restituita. Questo parametro deve essere uno dei valori seguenti.

Valore	Significato
InstanceBasicInformation	Restituisce una struttura INSTANCE_BASIC_INFORMATION per l'istanza.
InstanceFullInformation	Restituisce una struttura INSTANCE_FULL_INFORMATION per l'istanza.
InstancePartialInformation	Restituisce una struttura INSTANCE_PARTIAL_INFORMATION per l'istanza.
InstanceAggregateStandardInformation	Restituire una struttura INSTANCE_AGGREGATE_STANDARD_INFORMATION per l'istanza. La parte LegacyFilter della struttura non viene utilizzata. 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 punta lpBuffer , se la chiamata a FilterInstanceFindFirst riesce. Questo parametro è obbligatorio e non può essere NULL.

[out] lpFilterInstanceFind

Puntatore a una variabile allocata dal chiamante che riceve un handle di ricerca per il minifilter se la chiamata a FilterInstanceFindFirst ha esito positivo; in caso contrario, riceve INVALID_HANDLE_VALUE. Questo handle di ricerca può essere usato nelle chiamate successive a FilterInstanceFindNext e FilterInstanceFindClose.

Valore restituito

FilterInstanceFindFirst 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 i sistemi operativi precedenti a Windows Vista, la funzione restituisce questo valore HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Il minifilter specificato dal parametro lpFilterName non ha un'istanza nello stack del file system.

Commenti

La funzione FilterInstanceFindFirst apre un handle di ricerca e restituisce informazioni su un'istanza del minifilter denominato da lpFilterName. Dopo aver stabilito l'handle di ricerca, chiamare FilterInstanceFindNext per cercare altre istanze dello stesso minifilter. Quando l'handle di ricerca non è più necessario, chiuderlo chiamando FilterInstanceFindClose.