Fonction FltGetLowerInstance (fltkernel.h)

Article
08/07/2023

La routine FltGetLowerInstance retourne un pointeur de instance opaque pour le instance de pilote minifilter inférieur suivant, le cas échéant, qui est attaché sous un pilote minifilter donné instance sur le même volume.

Syntaxe

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

Paramètres

[in] CurrentInstance

Pointeur de instance opaque pour le pilote minifilter instance pour lequel le instance de pilote minifilter inférieur est demandé.

[out] LowerInstance

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

Valeur retournée

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

Code de retour	Description
STATUS_NO_MORE_ENTRIES	Aucun instance de pilote minifilter inférieur n’a été trouvé. Il s’agit d’un code d’avertissement.

Remarques

Une instance est dite inférieure à 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’un instance occupe (ou doit occuper) dans le pilote minifilter 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. Une seule instance peut être attachée à une altitude donnée sur un volume donné.

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.

FltGetLowerInstance ajoute une référence d’arrêt au pointeur de 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.