Fonction FilterInstanceFindFirst (fltuser.h)

Article
08/23/2023

La fonction FilterInstanceFindFirst retourne des informations sur un pilote de minifiltre instance et est utilisée comme point de départ pour l’analyse des instances d’un minifiltre.

Syntaxe

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

Paramètres

[in] lpFilterName

Pointeur vers une chaîne de caractères larges terminée par null qui contient le nom du pilote de minifiltre qui possède le instance.

[in] dwInformationClass

Type de instance structure d’informations retournée. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
InstanceBasicInformation	Retourne une structure de INSTANCE_BASIC_INFORMATION pour le instance.
InstanceFullInformation	Retourne une structure INSTANCE_FULL_INFORMATION pour le instance.
InstancePartialInformation	Retourne une structure INSTANCE_PARTIAL_INFORMATION pour le instance.
InstanceAggregateStandardInformation	Retourne une structure INSTANCE_AGGREGATE_STANDARD_INFORMATION pour le instance. La partie LegacyFilter de la structure n’est pas utilisée. Cette structure 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 à FilterInstanceFindFirst réussit. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[out] lpFilterInstanceFind

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

Valeur retournée

FilterInstanceFindFirst 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 InstanceAggregateStandardInformation est spécifié pour les systèmes d’exploitation antérieurs à Windows Vista, la fonction retourne cette valeur HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Le minifiltre spécifié par le paramètre lpFilterName n’a pas de instance sur la pile du système de fichiers.

Notes

La fonction FilterInstanceFindFirst ouvre un handle de recherche et retourne des informations sur un instance pour le minifiltre nommé par lpFilterName. Une fois le handle de recherche établi, appelez FilterInstanceFindNext pour rechercher d’autres instances du même minifiltre. Lorsque le handle de recherche n’est plus nécessaire, fermez-le en appelant FilterInstanceFindClose.