Référencement de contextes

Le Gestionnaire de filtres utilise le comptage de références pour gérer la durée de vie d’un contexte de minifiltre. Un nombre de références est un nombre qui indique l’état d’un contexte.

Chaque fois qu’un contexte est correctement créé, FltMgr initialise le nombre de références du contexte sur un. C’est ce qu’on appelle la référence initiale au contexte.

Chaque fois qu’un contexte est référencé, par exemple par un jeu de contexte ou une obtention réussie, FltMgr incrémente le nombre de références du contexte d’une unité.

Lorsqu’un contexte n’est plus nécessaire, son nombre de références doit être décrémenté. Un nombre de références positif signifie que le contexte est utilisable. Lorsque le nombre de références devient égal à zéro, le contexte est inutilisable et FltMgr finit par le libérer.

FltMgr libère la référence initiale au contexte (décrémente le nombre de références à zéro) lorsque l’objet est détruit, puis appelle le rappel de nettoyage de contexte facultatif du filtre. Bien que cela se produise rarement, si un minifiltre doit supprimer un contexte d’un objet avant la suppression, le minifiltre doit libérer en toute sécurité cette référence initiale au contexte en appelant FltDeleteContext.

Un minifiltre peut ajouter sa propre référence à un contexte en appelant FltReferenceContext pour incrémenter le nombre de références du contexte. Le minifilter doit finalement supprimer cette référence ajoutée en appelant FltReleaseContext.

Voici un bref exemple d’historique du nombre de références pour un objet classique. Supposons que tous les appels d’API Flt réussissent.

Rappel de filtre	API Flt appelée	Nombre de références de contexte	Description
PreCreate	FltAllocateContext	1	Le filtre traite une pré-création et décide qu’il souhaite peut-être suivre le fichier. Il alloue un contexte de flux, ce qui amène FltMgr à initialiser le nombre de références à 1. Le filtre transmet le contexte à son rappel PostCreate via le paramètre CompletionContext .
PostCréer	FltSetStreamContext	2	Le filtre a passé le contexte qu’il a alloué lors de La précréation à son rappel PostCreate . La création a réussi, de sorte que le filtre attache le contexte, ce qui amène FltMgr à incrémenter le nombre de références.
PostCréer	FltReleaseContext	1	Étant donné que FltSetStreamContext a incrémenté le nombre de références, le filtre doit supprimer le nombre supplémentaire. Le nombre de références est de 1 une fois que le filtre a libéré le contexte, de sorte que le contexte reste actif. Si le filtre avait décidé qu’il ne se souciait pas de ce fichier après tout, il aurait pu ignorer l’appel de FltSetStreamContext et simplement appelé FltReleaseContext. Dans ce cas, le décompte serait passé à 0, et le contexte aurait été libéré.
PreRead	FltGetStreamContext	2	Le filtre voit une E/S en lecture et souhaite savoir s’il effectue le suivi de ce fichier. Il demande son contexte de flux et l’obtient, afin qu’il sache qu’il souhaite suivre ce fichier. FltMgr incrémente le nombre de références.
PreRead	FltReleaseContext	1	Le filtre étant effectué à l’aide de son contexte, il le libère, ce qui entraîne la décrémentation du nombre de références. Chaque FltGet*Context doit être équilibré avec un FltReleaseContext.
Pré-nettoyage	FltGetStreamContext	2	Le filtre demande et obtient son contexte, qui incrémente le nombre de références.
Pré-nettoyage	FltReleaseContext	1	Le filtre est effectué à l’aide du contexte pour le libérer, ce qui décrémente le nombre de références.
Rappel de nettoyage de contexte		0	Le système de fichiers détruit l’objet de flux sous-jacent. (Dans le cas spécifique d’un objet de flux, la destruction est déclenchée par IRP_MJ_CLOSE). FltMgr décrémente le nombre de références sur 0, puis appelle le rappel de nettoyage de contexte du filtre. Le filtre a maintenant la possibilité de propre son contexte.