Fonction FilterVolumeInstanceFindFirst (fltuser.h)

Article
08/23/2023

La fonction FilterVolumeInstanceFindFirst retourne des informations sur un pilote minifilter instance ou un pilote de filtre hérité et est utilisée pour commencer à analyser les pilotes de filtre attachés à un volume.

Syntaxe

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

Paramètres

[in] lpVolumeName

Pointeur vers une chaîne de caractères larges terminée par null qui contient le nom du volume auquel le minifiltre instance ou le filtre hérité est attaché.

La chaîne d’entrée lpVolumeName peut être l’une des valeurs suivantes. La barre oblique inverse de fin (\) est facultative.

Une lettre de lecteur, telle que D:\
Chemin d’accès à un point de montage de volume, tel que c:\mnt\edrive\
Un identificateur de volume unique (également appelé nom GUID de volume), tel que \?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\
Un nom d’appareil non persistant (également appelé nom de cible ou nom d’appareil NT), tel que \Device\HarddiskVolume1\

[in] dwInformationClass

Type de structure d’informations de pilote de filtre retournée. Ce paramètre doit contenir l’une des valeurs suivantes.

Valeur	Signification
InstanceBasicInformation	Retourne une structure INSTANCE_BASIC_INFORMATION pour un minifiltre instance. Les pilotes de filtre hérités sont ignorés.
InstanceFullInformation	Retourne une structure INSTANCE_FULL_INFORMATION pour un minifiltre instance. Les pilotes de filtre hérités sont ignorés.
InstancePartialInformation	Retourne une structure INSTANCE_PARTIAL_INFORMATION pour un minifiltre instance. Les pilotes de filtre hérités sont ignorés.
InstanceAggregateStandardInformation	Retourne une structure INSTANCE_AGGREGATE_STANDARD_INFORMATION pour le instance. Le membre LegacyFilter de la structure n’est pas utilisé. 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 à FilterVolumeInstanceFindFirst réussit. Ce paramètre est obligatoire et ne peut pas être NULL.

[out] lpVolumeInstanceFind

Pointeur vers une variable allouée à l’appelant qui reçoit un handle de recherche pour le minifiltre instance ou le filtre hérité (uniquement lorsque InstanceAggregateStandardInformation est spécifié) si l’appel à FilterVolumeInstanceFindFirst réussit. Sinon, lpVolumeInstanceFind reçoit INVALID_HANDLE_VALUE. Ce handle de recherche peut être utilisé dans les appels suivants à FilterVolumeInstanceFindNext et FilterVolumeInstanceFindClose.

Valeur retournée

FilterVolumeInstanceFindFirst retourne S_OK en cas de réussite. Sinon, elle retourne une valeur d’erreur HRESULT, telle que l’une des 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 un système d’exploitation antérieur à Windows Vista, FilterVolumeInstanceFindFirst retourne cette valeur HRESULT.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	Un pilote de filtre est introuvable sur le volume donné.

Notes

La fonction FilterVolumeInstanceFindFirst ouvre un handle de recherche et retourne des informations sur le premier pilote de filtre trouvé qui est attaché au volume nommé par lpVolumeName. Une fois le handle de recherche établi, appelez FilterVolumeInstanceFindNext pour rechercher d’autres pilotes de filtre attachés au même volume. Lorsque le handle de recherche n’est plus nécessaire, fermez-le en appelant FilterVolumeInstanceFindClose.

À compter de Windows Vista, FilterVolumeInstanceFindFirst peut retourner à la fois les informations sur le pilote de filtre hérité et le pilote minifilter instance des informations lorsque la valeur du paramètre dwInformationClass est InstanceAggregateStandardInformation. Pour les systèmes d’exploitation antérieurs, cette fonction ne peut pas retourner d’informations de filtre héritées, car la structure INSTANCE_AGGREGATE_STANDARD_INFORMATION n’est pas disponible.