PFLT_POST_OPERATION_CALLBACK fonction de rappel (fltkernel.h)

Article
02/26/2024

Un pilote minifilter peut inscrire une ou plusieurs routines de type PFLT_POST_OPERATION_CALLBACK pour effectuer le traitement d’achèvement des 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 FLT_CALLBACK_DATA données de rappel 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 pré-opération à la routine de rappel post-opération.

[in] Flags

Masque de bits d’indicateurs qui spécifie comment le rappel post-opération doit être effectué.

Indicateur	Signification
FLTFL_POST_OPERATION_DRAINING	Le gestionnaire de filtres définit cet indicateur pour indiquer que le instance du pilote minifilter est en cours de détachement et que cette routine de rappel post-opération est appelée pour propre 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 vers 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 dans IRQL <= APC_LEVEL.

Indicateur

Signification

FLTFL_POST_OPERATION_DRAINING

Le gestionnaire de filtres définit cet indicateur pour indiquer que le instance du pilote minifilter est en cours de détachement et que cette routine de rappel post-opération est appelée pour propre 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 vers 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 dans IRQL <= APC_LEVEL.

Valeur retournée

Cette routine de rappel retourne l’une des valeurs status suivantes :

Code de retour	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 a retourné cette valeur status, le gestionnaire de filtres poursuit le traitement 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 renvoie pas le contrôle de l’opération au gestionnaire de filtres. Le rappel post-opération d’un pilote minifilter peut retourner cette valeur status uniquement 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 reprendre le traitement de fin 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 plus de traitement d’achèvement 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 renvoyer le contrôle de l’opération au gestionnaire de filtres. Cette valeur status peut uniquement être retournée 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 interdit une opération QueryOpen rapide et force l’opération à descendre le chemin lent. Cela amène le gestionnaire d’E/S à traiter la requête en effectuant une ouverture/requête/fermeture du fichier. Les pilotes Minifilter doivent uniquement retourner cette status pour QueryOpen.

Code de retour

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 a retourné cette valeur status, le gestionnaire de filtres poursuit le traitement 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 renvoie pas le contrôle de l’opération au gestionnaire de filtres.

Le rappel post-opération d’un pilote minifilter peut retourner cette valeur status uniquement 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 reprendre le traitement de fin 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 plus de traitement d’achèvement 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 renvoyer le contrôle de l’opération au gestionnaire de filtres.

Cette valeur status peut uniquement être retournée 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 interdit une opération QueryOpen rapide et force l’opération à descendre le chemin lent. Cela amène le gestionnaire d’E/S à traiter la requête en effectuant une ouverture/requête/fermeture du fichier. Les pilotes Minifilter doivent uniquement retourner cette status 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’adresse 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 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 de ressources, de mutex ou de 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 des E/S qui doit être effectué au niveau de l’IRQL < DISPATCH_LEVEL ne peut pas être effectué directement dans la routine de rappel post-opération. 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é si le paramètre Flags du rappel post-opération a le FLTFL_POST_OPERATION_DRAINING défini. Voici quelques exceptions à cette règle :

Si la routine de rappel avant 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 à IRQL <= APC_LEVEL, dans le même contexte de thread que le rappel de pré-opération.
Il est garanti que les routines de rappel après création soient appelées au PASSIVE_LEVEL IRQL, dans le contexte du thread à l’origine de l’opération 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 une routine de rappel pré-opération (PFLT_PRE_OPERATION_CALLBACK), et vice versa.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans microsoft Windows 2000 Update Rollup 1 pour les systèmes d’exploitation Windows SP4, Windows XP SP2, Windows Server 2003 SP1 et ultérieur.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	fltkernel.h (incluez FltKernel.h)
IRQL	Voir la section Notes