PFLT_INSTANCE_TEARDOWN_CALLBACK fonction de rappel (fltkernel.h)

Article
02/26/2024

Un pilote de minifiltre peut inscrire deux routines de type PFLT_INSTANCE_TEARDOWN_CALLBACK en tant que routines InstanceTeardownStartCallback et InstanceTeardownCompleteCallback du pilote minifiltre.

Syntaxe

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

void PfltInstanceTeardownCallback(
  [in] PCFLT_RELATED_OBJECTS FltObjects,
  [in] FLT_INSTANCE_TEARDOWN_FLAGS Reason
)
{...}

Paramètres

[in] FltObjects

Pointeur vers une structure FLT_RELATED_OBJECTS qui contient des pointeurs opaques pour les objets liés à l’opération d’E/S actuelle.

[in] Reason

Indicateur qui indique pourquoi le instance du pilote de minifiltre est en train d’être détruit. Celui-ci peut avoir l'une des valeurs suivantes :

Indicateur	Signification
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	Le instance est en cours de détachement, car une application en mode utilisateur a appelé FilterDetach ou un composant en mode noyau a appelé FltDetachVolume.
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	Le pilote de minifiltre est en cours de déchargement.
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	Le pilote de minifiltre est en cours de déchargement.
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	S’il est défini, le volume est en cours de démontation. (Ou le volume a déjà été démonté. Ou l’opération de montage de volume a échoué. Ou le pilote minifiltre instance ou le volume est en train d’être détruit. Ou le système de fichiers s’est désinscrit lui-même en tant que système de fichiers actif.)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	Le système a rencontré une erreur interne inattendue.

Valeur de retour

None

Remarques

Lorsqu’un pilote de minifiltre s’inscrit en appelant FltRegisterFilter à partir de sa routine DriverEntry , il peut inscrire deux routines de type PFLT_INSTANCE_TEARDOWN_CALLBACK en tant que routines InstanceTeardownStartCallback et InstanceTeardownCompleteCallback du pilote de minifiltre. Pour inscrire ces routines de rappel, le pilote minifiltre stocke les adresses des deux routines de type PFLT_INSTANCE_TEARDOWN_CALLBACK dans les membres InstanceTeardownStartCallback et InstanceTeardownCompleteCallback de la structure FLT_REGISTRATION que le pilote de minifiltre transmet comme paramètre Registration de FltRegisterFilter.

Les routines InstanceTeardownStartCallback et InstanceTeardownCompleteCallback sont facultatives et peuvent être NULL. Si le pilote de minifiltre spécifie NULL pour la routine InstanceTeardownStartCallback ou InstanceTeardownCompleteCallback, le instance est toujours détruit.

La routine InstanceTeardownStartCallback est appelée lorsque le gestionnaire de filtres commence à détruire un pilote de minifiltre instance pour permettre au pilote de minifiltre d’effectuer toutes les opérations d’E/S en attente et d’enregistrer les informations d’état.

La routine InstanceTeardownStartCallback doit :

Appelez FltCompletePendedPreOperation pour chaque opération d’E/S qui a été suspendu dans la routine de rappel de préopération du pilote minifiltre pour terminer l’opération ou renvoyer le contrôle de l’opération au gestionnaire de filtres.
Aucune nouvelle opération d’E/S n’est suspendu. Si le pilote de minifiltre utilise une file d’attente de données de rappel, il doit appeler FltCbdqDisable pour le désactiver.
Appelez FltCompletePendedPostOperation pour chaque opération d’E/S qui a été suspendu dans la routine de rappel de post-opération du pilote minifiltre pour renvoyer le contrôle de l’opération au gestionnaire de filtres.

La routine InstanceTeardownStartCallback peut éventuellement effectuer les opérations suivantes pour permettre au pilote de minifiltre de décharger le plus rapidement possible :

Fermez tous les fichiers ouverts.
Assurez-vous que les threads de travail effectuent uniquement le minimum nécessaire pour terminer le traitement des éléments de travail en attente.
Appelez FltCancelIo pour annuler toutes les opérations d’E/S initiées par le pilote de minifiltre.
Arrêtez la mise en file d’attente des nouveaux éléments de travail.

Une fois que la routine InstanceTeardownStartCallback du pilote minifiltre est appelée, les routines de rappel de préopération et de post-opération du pilote minifiltre ne sont pas appelées pour les nouvelles opérations d’E/S. Toutefois, ils peuvent être appelés pour les opérations d’E/S qui ont commencé avant instance démontage.

La routine InstanceTeardownCompleteCallback est appelée lorsque le processus de démontage est terminé pour permettre au pilote de minifiltre de fermer les fichiers ouverts et d’effectuer tout autre traitement de nettoyage nécessaire.

La routine InstanceTeardownCompleteCallback doit fermer tous les fichiers ouverts par le pilote de minifiltre.

Le gestionnaire de filtres appelle la routine InstanceTeardownCompleteCallback du pilote minifilter uniquement une fois que toutes les opérations d’E/S en suspens ont été terminées ou vidées.

Avertissement

La routine InstanceTeardownCompleteCallback n’est pas appelée si l’une des conditions suivantes est remplie :

Il existe des opérations d’E/S en suspens.
Il existe des opérations d’E/S en cours qui ont été initiées par le pilote de minifiltre.

Si le pilote de minifiltre instance est en cours de destruction parce que le pilote de minifiltre est en cours de déchargement, l’opération de déchargement semble se bloquer jusqu’à ce que la routine InstanceTeardownCompleteCallback retourne. Pour déboguer ces types de problèmes, vous devez activer le vérificateur de pilotes sur votre pilote de minifiltre. L’option Filtrer la vérification des E/S du vérificateur peut aider à identifier les causes possibles, telles que les références non disponibles, qui empêcheraient le déchargement du pilote de minifiltre. Pour plus d’informations, consultez Filter Verifier.

Notez que le référencement du instance (en appelant FltObjectReference) n’empêche pas l’appel de la routine InstanceTeardownCompleteCallback.

Le gestionnaire de filtres appelle les routines InstanceTeardownStartCallback et InstanceTeardownCompleteCallback au PASSIVE_LEVEL IRQL.