structure FLT_CALLBACK_DATA (fltkernel.h)

Article
02/06/2025

La structure FLT_CALLBACK_DATA représente une opération d’E/S. Le Gestionnaire de filtres et les mini-filtres utilisent cette structure pour lancer et traiter les opérations d’E/S.

Syntaxe

typedef struct _FLT_CALLBACK_DATA {
  FLT_CALLBACK_DATA_FLAGS     Flags;
  PETHREAD                    Thread;
  PFLT_IO_PARAMETER_BLOCK     Iopb;
  IO_STATUS_BLOCK             IoStatus;
  struct _FLT_TAG_DATA_BUFFER *TagData;
  union {
    struct {
      LIST_ENTRY QueueLinks;
      PVOID      QueueContext[2];
    };
    PVOID FilterContext[4];
  };
  KPROCESSOR_MODE             RequestorMode;
} FLT_CALLBACK_DATA, *PFLT_CALLBACK_DATA;

Membres

Flags

Masque de bits des indicateurs décrivant l’opération d’E/S.

Les minifilters peuvent définir l’indicateur suivant.

Drapeau	Signification
FLTFL_CALLBACK_DATA_DIRTY	Un minifilter définit cet indicateur (en appelant FltSetCallbackDataDirty) pour indiquer qu’il a modifié le contenu de la structure de données de rappel. (Pour plus d’informations, consultez la section Remarques suivante.)

Note

Seul le Gestionnaire de filtres peut définir les indicateurs suivants.

Lorsque le Gestionnaire de filtre initialise la structure de données de rappel, il définit l’un des indicateurs suivants pour spécifier le type d’opération d’E/S que représente la structure de données de rappel.

Drapeau	Signification
FLTFL_CALLBACK_DATA_FAST_IO_OPERATION	La structure de données de rappel représente une opération d’E/S rapide.
FLTFL_CALLBACK_DATA_FS_FILTER_OPERATION	La structure de données de rappel représente une opération de rappel minifilter du système de fichiers.
FLTFL_CALLBACK_DATA_IRP_OPERATION	La structure de données de rappel représente une opération basée sur un paquet de demandes d’E/S (IRP).

Note

Seul le Gestionnaire de filtres peut définir les indicateurs suivants.

Lorsque le Gestionnaire de filtre initialise la structure de données de rappel, il peut également définir les indicateurs suivants.

Drapeau	Signification
FLTFL_CALLBACK_DATA_GENERATED_IO	La structure de données de rappel représente une opération d’E/S générée par un mini-filtre. Cet indicateur est valide uniquement pour les opérations basées sur IRP.
FLTFL_CALLBACK_DATA_REISSUED_IO	La structure de données de rappel représente une opération d’E/S en cours de réédition par un mini-filtre. (Pour réémettre une opération d’E/S, un minifilter appelle FltReissueSynchronousIo.) Cet indicateur est valide uniquement pour les opérations basées sur IRP.
FLTFL_CALLBACK_DATA_SYSTEM_BUFFER	La mémoire tampon de l’opération d’E/S a été allouée à partir du pool non paginé. Cet indicateur peut être défini pour n’importe quel type d’opération d’E/S. Les minifilters ne doivent jamais définir cet indicateur.

Note

Seul le Gestionnaire de filtres peut définir les indicateurs suivants.

Lorsque le Gestionnaire de filtres effectue le traitement complet de l’opération d’E/S que représente la structure de données de rappel, il définit l’un ou les deux indicateurs suivants.

Drapeau	Signification
FLTFL_CALLBACK_DATA_DRAINING_IO	Le Gestionnaire de filtre définit cet indicateur pour indiquer qu’il draine actuellement le nœud d’achèvement pour l’opération d’E/S. Cet indicateur est valide uniquement pendant l’achèvement des E/S.
FLTFL_CALLBACK_DATA_POST_OPERATION	Le Gestionnaire de filtre définit cet indicateur pour indiquer qu’il appelle actuellement des routines de rappel post-opération inscrite (PFLT_POST_OPERATION_CALLBACK) pour l’opération. Cet indicateur est valide uniquement pendant l’achèvement des E/S.

Thread

Pointeur vers le thread qui a lancé l’opération d’E/S. Ce champ peut être NULL.

Iopb

Pointeur vers une structure FLT_IO_PARAMETER_BLOCK qui contient les paramètres de l’opération d’E/S.

IoStatus

Structure IO_STATUS_BLOCK qui contient l’état et les informations de l’opération d’E/S. Un minifiltre peut modifier le contenu de cette structure uniquement dans une routine de rappel de pré-opération (PFLT_PRE_OPERATION_CALLBACK) à partir de laquelle il est sur le point de retourner FLT_PREOP_COMPLETE ou dans une routine de rappel post-opération (PFLT_POST_OPERATION_CALLBACK) à partir de laquelle il est sur le point de retourner FLT_POSTOP_FINISHED_PROCESSING. Sinon, le contenu de cette structure est normalement défini par le Gestionnaire de filtres.

TagData

Pointeur vers une structure FLT_TAG_DATA_BUFFER qui contient des données de point d’analyse pour l’opération d’E/S. Ce pointeur est valide uniquement dans le chemin d’accès post-création. Ainsi, seule la routine de rappel post-opération d’un minifilter peut modifier la valeur de ce membre. Une routine de rappel post-création d’un minifilter peut modifier ce membre pour qu’il pointe vers une autre structure FLT_TAG_DATA_BUFFER. Toutefois, s’il modifie le membre pour qu’il pointe vers une autre structure, il doit d’abord appeler ExFreePool pour libérer la structure existante afin d’empêcher une fuite de mémoire du pool.

QueueLinks

Liens de file d’attente qu’un minifilter peut utiliser lorsque la file d’attente de données de rappel du Gestionnaire de filtres est utilisée pour mettre en attente l’opération d’E/S.

QueueContext[2]

Tableau de pointeurs d’informations de contexte qu’un minifilter peut utiliser lorsque la file d’attente du Gestionnaire de filtres est utilisée pour mettre en attente l’opération d’E/S.

FilterContext[4]

Tableau de pointeurs d’informations contextuelles qu’un minifiltre peut utiliser lorsqu’une file d’attente autre que la file d’attente du Gestionnaire de filtres est utilisée pour mettre en attente l’opération d’E/S.

RequestorMode

Indique le mode d’exécution du processus qui a lancé l’opération d’E/S, KernelMode ou UserMode.

Remarques

Un minifilter inscrit les routines de rappel (PFLT_PRE_OPERATION_CALLBACK) et post-opération (PFLT_POST_OPERATION_CALLBACK) pour un ou plusieurs types d’opérations d’E/S. Lorsque le Gestionnaire de filtre appelle l’une de ces routines de rappel, il transmet une structure de données de rappel (FLT_CALLBACK_DATA) comme premier paramètre. Cette structure représente l’opération d’E/S.

La routine de rappel de pré-opération ou post-opération d’un minifilter peut modifier le contenu de la structure de données de rappel, à l’exception des membres thread et RequestorMode. Si c’est le cas, elle doit ensuite appeler FltSetCallbackDataDirty, sauf si elle a également modifié le contenu du membre IoStatus. Sinon, les valeurs modifiées sont ignorées.

Un minifilter peut lancer une opération d’E/S en appelant une routine de support telle que FltReadFile ou en appelant FltAllocateCallbackData pour allouer une structure de données de rappel ; initialisation des paramètres d’E/S de la structure et passage de la structure à FltPerformSynchronousIo ou FltPerformAsynchronousIo.

Une opération d’E/S initiée par minifilter n’est envoyée qu’aux instances de minifilter attachées sous l’instance appelante et au système de fichiers. Les mini-filtres attachés au-dessus de l’instance spécifiée ne reçoivent pas l’opération d’E/S.

Les minifiltres ne peuvent lancer que des opérations d’E/S basées sur IRP. Ils ne peuvent pas lancer des opérations de rappel rapides d’E/S ou de filtre de système de fichiers (FSFilter).