FLT_CALLBACK_DATA structure (fltkernel.h)

Article
02/26/2024

La structure FLT_CALLBACK_DATA représente une opération d’E/S. Le Gestionnaire de filtres et les minifiltres utilisent cette structure pour lancer et traiter des 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 minifiltres peuvent définir l’indicateur suivant.

Indicateur	Signification
FLTFL_CALLBACK_DATA_DIRTY	Un minifiltre 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.)

Notes

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

Lorsque le Gestionnaire de filtres 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.

Indicateur	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 de minifiltre 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).

Notes

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

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

Indicateur	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 minifiltre. 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 qui est rééditée par un minifiltre. (Pour réémettre une opération d’E/S, un minifiltre appelle FltReissueSynchronousIo.) Cet indicateur est valide uniquement pour les opérations basées sur IRP.
FLTFL_CALLBACK_DATA_SYSTEM_BUFFER	La mémoire tampon pour l’opération d’E/S a été allouée à partir d’un pool non paginé. Cet indicateur peut être défini pour n’importe quel type d’opération d’E/S. Les minifiltres ne doivent jamais définir cet indicateur.

Notes

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

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

Indicateur	Signification
FLTFL_CALLBACK_DATA_DRAINING_IO	Le Gestionnaire de filtres définit cet indicateur pour indiquer qu’il est en train de vider le nœud d’achèvement pour l’opération d’E/S. Cet indicateur est valide uniquement pendant la fin des E/S.
FLTFL_CALLBACK_DATA_POST_OPERATION	Le Gestionnaire de filtres définit cet indicateur pour indiquer qu’il appelle actuellement des routines de rappel post-opération (PFLT_POST_OPERATION_CALLBACK) inscrites pour l’opération. Cet indicateur est valide uniquement pendant la fin 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 status et des informations pour l’opération d’E/S. Un minifiltre peut modifier le contenu de cette structure uniquement dans une routine de rappel 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 minifiltre peut modifier la valeur de ce membre. La routine de rappel post-création d’un minifiltre peut modifier ce membre pour qu’il pointe vers une structure de FLT_TAG_DATA_BUFFER différente. 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’éviter une fuite de mémoire de pool.

QueueLinks

Liens de file d’attente qu’un minifiltre 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 minifiltre 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 de contexte qu’un minifiltre peut utiliser lorsqu’une file d’attente autre que celle 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 minifiltre enregistre des routines de rappel pré-opération (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 filtres 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 minifiltre peut modifier le contenu de la structure de données de rappel, à l’exception des membres Thread et RequestorMode . Si c’est le cas, il doit ensuite appeler FltSetCallbackDataDirty, sauf s’il a également modifié le contenu du membre IoStatus . Sinon, les valeurs modifiées sont ignorées.

Un minifiltre peut lancer une opération d’E/S en appelant une routine de support comme 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 transmission de la structure à FltPerformSynchronousIo ou FltPerformAsynchronousIo.

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

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