Fonction FilterFindFirst (fltuser.h)

Article
02/29/2024

La fonction FilterFindFirst retourne des informations sur un pilote de filtre (pilote minifiltre instance ou pilote de filtre hérité) et est utilisée pour commencer à analyser les filtres dans la liste globale des filtres inscrits.

Syntaxe

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

Paramètres

[in] dwInformationClass

Type d’informations de pilote de filtre demandées. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
FilterFullInformation	La mémoire tampon pointée vers par le paramètre lpBuffer reçoit une structure FILTER_FULL_INFORMATION pour chaque minifiltre instance. Les filtres hérités sont ignorés.
FilterAggregateBasicInformation	La mémoire tampon pointée vers par le paramètre lpBuffer reçoit une structure FILTER_AGGREGATE_BASIC_INFORMATION pour chaque minifiltre instance ou filtre hérité. Cette valeur dwInformationClass est disponible à partir de Windows Server 2003 avec SP1 et de Windows XP avec SP2 avec le correctif cumulatif du gestionnaire de filtres. Pour plus d’informations sur le package cumulatif du gestionnaire de filtres pour Windows XP avec SP2, consultez l’article 914882, « Le package cumulatif du gestionnaire de filtres pour Windows XP SP2 », dans la Base de connaissances Microsoft.
FilterAggregateStandardInformation	La mémoire tampon pointée vers le paramètre lpBuffer reçoit une structure FILTER_AGGREGATE_STANDARD_INFORMATION pour chaque minifiltre instance ou filtre hérité. Cette valeur dwInformationClass est disponible à partir de Windows Vista.

[out] lpBuffer

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les informations demandées. Le type des informations retournées dans la mémoire tampon est défini par le paramètre dwInformationClass .

[in] dwBufferSize

Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre lpBuffer . L’appelant doit définir ce paramètre en fonction de la dwInformationClass donnée.

[out] lpBytesReturned

Pointeur vers une variable allouée à l’appelant qui reçoit le nombre d’octets retournés dans la mémoire tampon vers laquelle lpBuffer pointe si l’appel à FilterFindFirst réussit. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[out] lpFilterFind

Pointeur vers une variable allouée par l’appelant qui reçoit un handle de recherche pour le pilote de filtre si l’appel à FilterFindFirst réussit ; sinon, il reçoit INVALID_HANDLE_VALUE. Ce handle de recherche peut être utilisé dans les appels suivants à FilterFindNext et FilterFindClose.

Valeur retournée

FilterFindFirst retourne S_OK en cas de réussite. Sinon, il retourne une valeur d’erreur HRESULT, telle que l’une des valeurs suivantes :

Code de retour	Description
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	La mémoire tampon pointée par lpBuffer n’est pas assez grande pour contenir les informations demandées. Lorsque cette valeur est retournée, lpBytesReturned contient la taille, en octets, de la mémoire tampon requise pour la structure dwInformationClass donnée.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	Une valeur non valide a été spécifiée pour le paramètre dwInformationClass . Par exemple, si FilterAggregateStandardInformation est spécifié pour un système d’exploitation antérieur à Windows Vista, FilterFindFirst retourne cette valeur HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Un pilote de filtre n’a pas été trouvé dans la liste globale des filtres inscrits.

Remarques

La fonction FilterFindFirst ouvre un handle de recherche et retourne des informations sur le premier pilote de filtre qui se trouve dans la liste globale des filtres inscrits. Une fois le handle de recherche établi, appelez la fonction FilterFindNext pour rechercher d’autres filtres dans la liste globale. Lorsque le handle de recherche n’est plus nécessaire, fermez-le en appelant FilterFindClose.

À compter de Microsoft Windows Server 2003 avec SP1 et De Windows XP avec Service Pack 1 (SP1) avec le correctif cumulatif du gestionnaire de filtres, FilterFindFirst et FilterFindNext peuvent fournir des informations héritées sur le pilote de filtre et des informations de instance de pilote de minifiltre. Sur les versions antérieures de Windows, FilterFindFirst et FilterFindNext peuvent uniquement fournir des informations sur les minifiltres (voir la description du paramètre dwInformationClass ci-dessus).

FilterFindFirst et FilterFindNext retournent des informations sur les pilotes de filtre dans l’ordre de diminution de la distance par rapport au système de fichiers de base. Les informations sur le filtre le plus éloigné du système de fichiers de base sont retournées en premier. Les informations sur le filtre le plus éloigné sont retournées en deuxième position. Les informations sur le filtre le plus proche du système de fichiers de base sont retournées en dernier.

Si l’entrée dwBufferSize est trop petite, lpFilterFind reçoit INVALID_HANDLE_VALUE et lpBytesReturned reçoit le nombre d’octets requis pour stocker les informations demandées.