FltGetLowerInstance, fonction (fltkernel.h)

Article
02/06/2025

La routine FltGetLowerInstance retourne un pointeur d’instance opaque pour l’instance de pilote minifilter inférieure suivante, s’il en existe un, qui est attaché sous une instance de pilote minifilter donnée sur le même volume.

Syntaxe

NTSTATUS FLTAPI FltGetLowerInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *LowerInstance
);

Paramètres

[in] CurrentInstance

Pointeur d’instance opaque pour l’instance de pilote minifilter pour laquelle l’instance de pilote minifilter inférieure est demandée.

[out] LowerInstance

Pointeur vers une variable allouée par l’appelant qui reçoit un pointeur d’instance de pilote minifilter opaque pour l’instance de pilote minifilter inférieure suivante. Ce paramètre est obligatoire et ne peut pas être NULL.

Valeur de retour

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

Retourner le code	Description
STATUS_NO_MORE_ENTRIES	Aucune instance de pilote minifilter inférieure n’a été trouvée. Il s’agit d’un code d’avertissement.

Remarques

On dit qu’une instance est en dessous une autre si elle est attachée à une altitude inférieure sur le même volume. 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.

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