Fonction FltAttachVolumeAtAltitude (fltkernel.h)

Article
02/26/2024

FltAttachVolumeAtAltitude est une routine de prise en charge du débogage qui attache un pilote minifilter instance à un volume à une altitude spécifiée, en remplaçant 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 le pilote minifilter instance doit être attaché. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] Altitude

Pointeur vers une structure de UNICODE_STRING contenant la chaîne d’altitude pour le 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 de UNICODE_STRING contenant le nom instance de la nouvelle instance. Ce paramètre est facultatif et peut être NULL. S’il est NULL, FltAttachVolumeAtAltitude génère un nom 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é, si nécessaire, pour INSTANCE_NAME_MAX_CHARS caractères.

[out, optional] RetInstance

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

Valeur retournée

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

Code de retour	Description
STATUS_FLT_DELETING_OBJECT	Le filtre ou le volume spécifié est en cours de démont. 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 a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	La structure UNICODE_STRING vers laquelle Altitude pointe ne contenait pas de chaîne d’altitude valide. Il s’agit d’un code d’erreur.

Remarques

Un pilote minifilter doit uniquement utiliser 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’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é.

L’altitude est spécifiée par une chaîne d’altitude, qui est un tableau de caractères larges contenant un ou plusieurs chiffres décimaux compris entre 0 et 9 ; Le tableau 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.

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

FltAttachVolumeAtAltitude retourne un pointeur de instance opaque pour le nouveau instance dans *RetInstance. Cette valeur de pointeur identifie de manière unique le pilote minifilter instance et reste constante tant que le instance est attaché au volume.

FltAttachVolumeAtAltitude ajoute une référence d’exécution au pointeur de 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 pilotes minifilter attachées au même volume, appelez FltCompareInstanceAltitudes.

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