PFLT_POST_OPERATION_CALLBACK fonction de rappel (fltkernel.h)

Article
02/06/2025

Un pilote minifilter peut inscrire une ou plusieurs routines de type PFLT_POST_OPERATION_CALLBACK pour effectuer un traitement d’achèvement pour les opérations d’E/S.

Syntaxe

PFLT_POST_OPERATION_CALLBACK PfltPostOperationCallback;

FLT_POSTOP_CALLBACK_STATUS PfltPostOperationCallback(
  [in, out]      PFLT_CALLBACK_DATA Data,
  [in]           PCFLT_RELATED_OBJECTS FltObjects,
  [in, optional] PVOID CompletionContext,
  [in]           FLT_POST_OPERATION_FLAGS Flags
)
{...}

Paramètres

[in, out] Data

Pointeur vers la structure des données de rappel FLT_CALLBACK_DATA pour l’opération d’E/S.

[in] FltObjects

Pointeur vers un gestionnaire de filtres géré FLT_RELATED_OBJECTS structure qui contient des pointeurs opaques pour les objets liés à la requête d’E/S actuelle.

[in, optional] CompletionContext

Pointeur de contexte retourné par le rappel de pré-opération du pilote minifilter PFLT_PRE_OPERATION_CALLBACK routine. Le pointeur CompletionContext permet de communiquer des informations de la routine de rappel de pré-opération à la routine de rappel post-opération.

[in] Flags

Masque de bits des indicateurs qui spécifie la façon dont le rappel post-opération doit être effectué.

Drapeau	Signification
FLTFL_POST_OPERATION_DRAINING	Le gestionnaire de filtres définit cet indicateur pour indiquer que l’instance du pilote minifilter est détachée et que cette routine de rappel post-opération est appelée pour nettoyer le contexte d’achèvement du pilote minifilter. Le rappel post-opération doit retourner FLT_POSTOP_FINISHED_PROCESSING. Si cet indicateur est défini, le paramètre Data pointe vers une copie de la structure de données de rappel d’origine pour l’opération, et non la structure de données de rappel d’origine. En outre, lorsque cet indicateur est défini, la routine de rappel post-opération est appelée au <IRQL = APC_LEVEL.

Drapeau

Signification

FLTFL_POST_OPERATION_DRAINING

Le gestionnaire de filtres définit cet indicateur pour indiquer que l’instance du pilote minifilter est détachée et que cette routine de rappel post-opération est appelée pour nettoyer le contexte d’achèvement du pilote minifilter. Le rappel post-opération doit retourner FLT_POSTOP_FINISHED_PROCESSING. Si cet indicateur est défini, le paramètre Data pointe vers une copie de la structure de données de rappel d’origine pour l’opération, et non la structure de données de rappel d’origine. En outre, lorsque cet indicateur est défini, la routine de rappel post-opération est appelée au <IRQL = APC_LEVEL.

Valeur de retour

Cette routine de rappel retourne l’une des valeurs d’état suivantes :

Retourner le code	Description
FLT_POSTOP_FINISHED_PROCESSING	Le pilote minifilter a terminé le traitement d’achèvement de l’opération d’E/S et retourne le contrôle de l’opération au gestionnaire de filtres. Une fois que le rappel post-opération retourne cette valeur d’état, le gestionnaire de filtres poursuit le traitement complet de l’opération d’E/S.
FLT_POSTOP_MORE_PROCESSING_REQUIRED	Le pilote minifilter a arrêté le traitement de l’achèvement de l’opération d’E/S, mais il ne retourne pas le contrôle de l’opération au gestionnaire de filtres. Le rappel post-opération d’un pilote minifilter ne peut retourner cette valeur d’état que si le rappel post-opération du pilote minifilter a publié l’opération d’E/S dans une file d’attente de travail. Le pilote minifilter doit finalement reprendre le traitement d’achèvement de l’opération d’E/S. Une fois le rappel post-opération retourné FLT_POSTOP_MORE_PROCESSING_REQUIRED, le gestionnaire de filtres n’effectue aucun traitement d’achèvement supplémentaire de l’opération d’E/S, sauf si les deux conditions suivantes sont remplies : Le rappel post-opération a publié l’opération d’E/S dans une file d’attente de travail. Une fois que la routine de travail effectue le traitement d’achèvement de l’opération, elle appelle FltCompletePendedPostOperation pour retourner le contrôle de l’opération au gestionnaire de filtres. Cette valeur d’état ne peut être retournée que pour les opérations d’E/S basées sur IRP. Pour déterminer si une structure de données de rappel donnée représente une opération d’E/S basée sur IRP, utilisez la macro FLT_IS_IRP_OPERATION.
FLT_POSTOP_DISALLOW_FSFILTER_IO	Le pilote minifilter désalloue une opération QueryOpen rapide et force l’opération à descendre le chemin lent. Ainsi, le gestionnaire d’E/S est chargé de traiter la requête en effectuant une ouverture/requête/fermeture du fichier. Les pilotes Minifilter ne doivent retourner cet état que pour QueryOpen.

Retourner le code

Description

FLT_POSTOP_FINISHED_PROCESSING

Le pilote minifilter a terminé le traitement d’achèvement de l’opération d’E/S et retourne le contrôle de l’opération au gestionnaire de filtres.

Une fois que le rappel post-opération retourne cette valeur d’état, le gestionnaire de filtres poursuit le traitement complet de l’opération d’E/S.

FLT_POSTOP_MORE_PROCESSING_REQUIRED

Le pilote minifilter a arrêté le traitement de l’achèvement de l’opération d’E/S, mais il ne retourne pas le contrôle de l’opération au gestionnaire de filtres.

Le rappel post-opération d’un pilote minifilter ne peut retourner cette valeur d’état que si le rappel post-opération du pilote minifilter a publié l’opération d’E/S dans une file d’attente de travail. Le pilote minifilter doit finalement reprendre le traitement d’achèvement de l’opération d’E/S.

Une fois le rappel post-opération retourné FLT_POSTOP_MORE_PROCESSING_REQUIRED, le gestionnaire de filtres n’effectue aucun traitement d’achèvement supplémentaire de l’opération d’E/S, sauf si les deux conditions suivantes sont remplies :

Le rappel post-opération a publié l’opération d’E/S dans une file d’attente de travail.
Une fois que la routine de travail effectue le traitement d’achèvement de l’opération, elle appelle FltCompletePendedPostOperation pour retourner le contrôle de l’opération au gestionnaire de filtres.

Cette valeur d’état ne peut être retournée que pour les opérations d’E/S basées sur IRP. Pour déterminer si une structure de données de rappel donnée représente une opération d’E/S basée sur IRP, utilisez la macro FLT_IS_IRP_OPERATION.

FLT_POSTOP_DISALLOW_FSFILTER_IO

Le pilote minifilter désalloue une opération QueryOpen rapide et force l’opération à descendre le chemin lent. Ainsi, le gestionnaire d’E/S est chargé de traiter la requête en effectuant une ouverture/requête/fermeture du fichier. Les pilotes Minifilter ne doivent retourner cet état que pour QueryOpen.

Remarques

La routine de rappel post-opération d’un pilote minifilter effectue un traitement d’achèvement pour un ou plusieurs types d’opérations d’E/S.

Les routines de rappel post-opération sont similaires aux routines d’achèvement utilisées par les pilotes de filtre de système de fichiers hérités.

Les routines de rappel post-opération sont appelées dans un contexte de thread arbitraire, à l'<IRQL = DISPATCH_LEVEL. Étant donné que cette routine de rappel peut être appelée au DISPATCH_LEVEL IRQL, elle est soumise aux contraintes suivantes :

Il ne peut pas appeler en toute sécurité une routine en mode noyau qui doit s’exécuter à un runtime IRQL inférieur.
Toutes les structures de données utilisées dans cette routine doivent être allouées à partir d’un pool non paginé.
Il ne peut pas être rendu paginable.
Il ne peut pas acquérir des ressources, des mutex ou des mutex rapides. Toutefois, il peut acquérir des verrous de rotation.
Il ne peut pas obtenir, définir ou supprimer des contextes, mais il peut libérer des contextes.

Tout traitement d’achèvement d’E/S qui doit être effectué au niveau de l’irQL < DISPATCH_LEVEL ne peut pas être effectué directement dans la routine de rappel postopératoire. Au lieu de cela, elle doit être publiée dans une file d’attente de travail en appelant une routine telle que FltDoCompletionProcessingWhenSafe ou FltQueueDeferredIoWorkItem.

N’oubliez pas que FltDoCompletionProcessingWhenSafe ne doit jamais être appelée si le paramètre Flags du rappel post-opération a le jeu de bits FLTFL_POST_OPERATION_DRAINING. Voici des exceptions à cette règle :

Si la routine de rappel de pré-opération d’un pilote minifilter retourne FLT_PREOP_SYNCHRONIZE pour une opération d’E/S basée sur IRP, la routine de rappel post-opération correspondante est garantie d’être appelée au <IRQL = APC_LEVEL, dans le même contexte de thread que le rappel de pré-opération.
Les routines de rappel post-création sont garanties d’être appelées au PASSIVE_LEVEL IRQL, dans le contexte du thread qui provient de l’opération de IRP_MJ_CREATE.

Un pilote minifilter inscrit une routine de rappel post-opération pour un type particulier d’opération d’E/S en stockant le point d’entrée de la routine de rappel dans le tableau OperationRegistration de la structure FLT_REGISTRATION. Le pilote minifilter transmet cette structure en tant que paramètre à FltRegisterFilter dans sa routine DriverEntry.

Un pilote minifilter peut inscrire une routine de rappel post-opération pour un type particulier d’opération d’E/S sans inscrire de routine de rappel de pré-opération (PFLT_PRE_OPERATION_CALLBACK) et vice versa.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans le correctif cumulatif 1 de Microsoft Windows 2000 pour SP4, Windows XP SP2, Windows Server 2003 SP1 et versions ultérieures.
plateforme cible	Bureau
d’en-tête	fltkernel.h (include FltKernel.h)
IRQL	Voir la section Remarques