FltGetVolumeInstanceFromName, fonction (fltkernel.h)

Article
02/06/2025

La routine FltGetVolumeInstanceFromName retourne un pointeur d’instance opaque pour l’instance de pilote minifilter donnée sur le volume donné.

Syntaxe

NTSTATUS FLTAPI FltGetVolumeInstanceFromName(
  [in, optional] PFLT_FILTER      Filter,
  [in]           PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Paramètres

[in, optional] Filter

Pointeur de filtre opaque pour le pilote minifilter propriétaire de l’instance. Ce paramètre est facultatif et peut être NULL.

[in] Volume

Pointeur opaque pour le volume auquel l’instance est attachée. Doit être un handle de volume valide. Ce paramètre est obligatoire et ne peut pas être NULL. (La définition de ce paramètre sur une valeur non valide provoque l’assertion du système sur une build vérifiée.)

[in, optional] InstanceName

Pointeur vers une structure UNICODE_STRING allouée par l’appelant qui contient le nom d’instance de l’instance sur le volume. (Il s’agit de la valeur InstanceName passée à FltAttachVolume ou FltAttachVolumeAtAltitude lors de la création de l’instance.) Ce paramètre est facultatif et peut être NULL. S’il s’agit NULL, FltGetVolumeInstanceFromName retourne l’instance correspondante la plus élevée trouvée.

[out] RetInstance

Pointeur vers une variable allouée par l’appelant qui reçoit un pointeur d’instance opaque pour l’instance qui correspond aux valeurs de Filtre, Volumeet InstanceName. Ce paramètre est obligatoire et ne peut pas être NULL.

Valeur de retour

FltGetVolumeInstanceFromName retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes :

Retourner le code	Description
STATUS_FLT_DELETING_OBJECT	L’instance est détruite. Il s’agit d’un code d’erreur.
STATUS_FLT_INSTANCE_NOT_FOUND	Aucune instance correspondante n’a été trouvée. Il s’agit d’un code d’erreur.

Remarques

FltGetVolumeInstanceFromName recherche la liste des instances de pilote minifilter attachées au volume spécifié dans le paramètre volume dans l’ordre de diminution de l’altitude, en commençant par l’instance la plus haute. Si plusieurs instances correspondent aux valeurs données de l'filtre, de volume et paramètres instanceName, FltGetVolumeInstanceFromName retourne l’instance correspondante la plus élevée trouvée.

Le terme « altitude » fait référence à la position qu’une instance occupe (ou doit occuper) dans la pile d’instances de pilote minifilter pour un volume. Plus l’altitude est élevée, plus l’instance provient du système de fichiers de base dans la pile. Une seule instance peut être attachée à une altitude donnée sur un volume donné.

L’altitude est spécifiée par une chaîne d’altitude , qui est une chaîne Unicode comptée composée d’un ou de plusieurs chiffres décimaux compris entre 0 et 9, et peut inclure un point décimal unique. Par exemple, « 100.123456 » et « 03333 » sont des chaînes d’altitude valides.

La chaîne « 03333 » représente une altitude supérieure à « 100,123456 ». (Les zéros de début et de fin sont ignorés.) En d’autres termes, une instance dont l’altitude est « 03333 » est plus éloignée du système de fichiers de base qu’une instance dont l’altitude est « 100,123456 ». Toutefois, cette comparaison n’est significative que si les deux instances sont attachées au même volume.

FltGetVolumeInstanceFromName ajoute une référence d’exécution au pointeur d’instance opaque retourné dans le paramètre RetInstance. Lorsque ce pointeur n’est plus nécessaire, l’appelant doit le libérer en appelant FltObjectDereference. Ainsi, chaque appel réussi à FltGetVolumeInstanceFromName doit être mis en correspondance par un appel ultérieur à FltObjectDereference.