FltAttachVolumeAtAltitude, fonction (fltkernel.h)

Article
02/06/2025

FltAttachVolumeAtAltitude est une routine de prise en charge du débogage qui attache une instance de pilote minifilter à un volume à une altitude spécifiée, en substituant tous les paramètres dans le fichier INF du pilote minifilter.

Syntaxe

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

Paramètres

[in, out] Filter

Pointeur de filtre opaque pour l’appelant. Ce paramètre est obligatoire et ne peut pas être NULL.

[in, out] Volume

Pointeur de volume opaque pour le volume auquel l’instance de pilote minifilter doit être attachée. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] Altitude

Pointeur vers une structure UNICODE_STRING contenant la chaîne d’altitude de l’instance. Ce paramètre est obligatoire et ne peut pas être NULL. (Pour plus d’informations sur ce paramètre, consultez la section Remarques suivante.)

[in, optional] InstanceName

Pointeur vers une structure UNICODE_STRING contenant le nom de l’instance pour la nouvelle instance. Ce paramètre est facultatif et peut être NULL. S’il s’agit NULL, FltAttachVolumeAtAltitude génère un nom d’instance à partir du nom du pilote minifilter et de la chaîne d’altitude vers laquelle Altitude pointe. Le nom généré est tronqué, le cas échéant, pour INSTANCE_NAME_MAX_CHARS caractères.

[out, optional] RetInstance

Pointeur vers une variable allouée par l’appelant qui reçoit un pointeur d’instance opaque pour l’instance nouvellement créée. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

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

Retourner le code	Description
STATUS_FLT_DELETING_OBJECT	Le de de filtre de* spécifié ou* volume est détruit. Il s’agit d’un code d’erreur.
STATUS_FLT_FILTER_NOT_READY	Le pilote minifilter n’a pas démarré le filtrage. Pour plus d’informations, consultez FltStartFiltering . Il s’agit d’un code d’erreur.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Une instance existe déjà à cette altitude sur le volume spécifié. Il s’agit d’un code d’erreur.
STATUS_FLT_INSTANCE_NAME_COLLISION	Une instance existe déjà avec ce nom sur le volume spécifié. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Structure UNICODE_STRING qui Altitude points pour ne pas contenir de chaîne d’altitude valide. Il s’agit d’un code d’erreur.

Remarques

Un pilote minifilter ne doit utiliser que FltAttachVolumeAtAltitude pour le débogage. Il ne doit pas appeler cette routine dans une version commerciale du pilote minifilter.

FltAttachVolumeAtAltitude est l’équivalent du noyau de la fonction Win32 FilterAttachAtAltitude.

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 un tableau à caractères larges contenant un ou plusieurs chiffres décimaux compris entre 0 et 9 ; le tableau 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.

Le nom d’instance spécifié dans le paramètre InstanceName doit être unique dans le système.

FltAttachVolumeAtAltitude retourne un pointeur d’instance opaque pour la nouvelle instance dans *RetInstance. Cette valeur de pointeur identifie de manière unique l’instance du pilote minifilter et reste constante tant que l’instance est attachée au volume.

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

Pour comparer les altitudes de deux instances de pilote minifilter attachées au même volume, appelez FltCompareInstanceAltitudes.

Pour détacher une instance de pilote minifilter d’un volume, appelez FltDetachVolume.