Funzione FilterFindFirst (fltuser.h)

Articolo
08/23/2023

La funzione FilterFindFirst restituisce informazioni su un driver di filtro (istanza del driver minifilter o driver di filtro legacy) e viene usato per avviare l'analisi dei filtri nell'elenco globale dei filtri registrati.

Sintassi

HRESULT FilterFindFirst(
  [in]  FILTER_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                   lpBuffer,
  [in]  DWORD                    dwBufferSize,
  [out] LPDWORD                  lpBytesReturned,
  [out] LPHANDLE                 lpFilterFind
);

Parametri

[in] dwInformationClass

Tipo di informazioni sul driver di filtro richieste. Questo parametro deve essere uno dei valori seguenti.

Valore	Significato
FilterFullInformation	Il buffer a cui punta il parametro lpBuffer riceve una struttura FILTER_FULL_INFORMATION per ogni istanza di minifilter. I filtri legacy vengono ignorati.
FilterAggregateBasicInformation	Il buffer a cui punta il parametro lpBuffer riceve una struttura FILTER_AGGREGATE_BASIC_INFORMATION per ogni istanza di minifilter o filtro legacy. Questo valore dwInformationClass è disponibile a partire da Windows Server 2003 con SP1 e Windows XP con SP2 con rollup del gestore filtri. Per altre informazioni sul pacchetto di rollup di Gestione filtri per Windows XP con SP2, vedere l'articolo 914882" Pacchetto di rollup di Gestione filtri per Windows XP SP2" nella Microsoft Knowledge Base.
FilterAggregateStandardInformation	Il buffer a cui punta il parametro lpBuffer riceve una struttura FILTER_AGGREGATE_STANDARD_INFORMATION per ogni istanza di minifilter o filtro legacy. Questo valore dwInformationClass è disponibile a partire da Windows Vista.

[out] lpBuffer

Puntatore a un buffer allocato dal chiamante che riceve le informazioni richieste. Il tipo di 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 FilterFindFirst ha esito positivo. Questo parametro è obbligatorio e non può essere NULL.

[out] lpFilterFind

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

Valore restituito

FilterFindFirst restituisce S_OK in caso di esito positivo. 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 filterAggregateStandardInformation viene specificato per un sistema operativo prima di Windows Vista, FilterFindFirst restituisce questo valore HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Un driver di filtro non è stato trovato nell'elenco globale dei filtri registrati.

Commenti

La funzione FilterFindFirst apre un handle di ricerca e restituisce informazioni sul primo driver di filtro presente nell'elenco globale dei filtri registrati. Dopo aver stabilito l'handle di ricerca, chiamare la funzione FilterFindNext per cercare altri filtri nell'elenco globale. Quando l'handle di ricerca non è più necessario, chiuderlo chiamando FilterFindClose.

A partire da Microsoft Windows Server 2003 con SP1 e Windows XP con Service Pack 1 (SP1) con rollup del gestore filtri, FilterFindFirst e FilterFindNext possono fornire informazioni legacy sui driver di filtro e informazioni sull'istanza del driver minifilter. Nelle versioni precedenti di Windows , FilterFindFirst e FilterFindNext possono fornire solo informazioni sui minifiltri (vedere la descrizione del parametro dwInformationClass precedente).

FilterFindFirst e FilterFindNext restituiscono informazioni sui driver di filtro in ordine di distanza decrescente dal file system di base. Le informazioni sul filtro più lontano dal file system di base vengono restituite per prime. Vengono restituite informazioni sul secondo filtro più lontano. Le informazioni sul filtro più vicino al file system di base vengono restituite per ultimo.

Se l'input dwBufferSize è troppo piccolo, lpFilterFind riceve INVALID_HANDLE_VALUE e lpBytesReturned riceve il numero di byte necessari per archiviare le informazioni richieste.