Fonction FltGetVolumeInstanceFromName (fltkernel.h)

Article
02/29/2024

La routine FltGetVolumeInstanceFromName retourne un pointeur de instance opaque pour le pilote de minifiltre donné instance 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 de minifiltre qui possède le instance. Ce paramètre est facultatif et peut être NULL.

[in] Volume

Pointeur opaque pour le volume auquel le instance est attaché. Doit être un handle de volume valide. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL. (Si vous définissez ce paramètre sur une valeur non valide, le système s’affirme sur une build vérifiée.)

[in, optional] InstanceName

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

[out] RetInstance

Pointeur vers une variable allouée par l’appelant qui reçoit un pointeur de instance opaque pour le instance qui correspond aux valeurs de Filter, Volume et InstanceName. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

Valeur retournée

FltGetVolumeInstanceFromName retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_FLT_DELETING_OBJECT	Le instance est en train d’être détruit. 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 de minifiltre attachées au volume spécifié dans le paramètre Volume par ordre d’altitude décroissante, en commençant par la instance supérieure. Si plusieurs instance correspondent aux valeurs données pour les paramètres Filter, Volume et InstanceName, FltGetVolumeInstanceFromName retourne la correspondance la plus élevée instance trouvée.

Le terme « altitude » fait référence à la position qu’un instance occupe (ou doit occuper) dans le pilote minifiltre instance pile pour un volume. Plus l’altitude est élevée, plus le instance est éloigné du système de fichiers de base dans la pile. Un seul instance peut être attaché à 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 plusieurs chiffres décimaux compris entre 0 et 9, et elle peut inclure une seule virgule décimale. 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, un instance dont l’altitude est « 03333 » est plus éloigné du système de fichiers de base qu’un 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 de 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.