Fonction FltCbdqInsertIo (fltkernel.h)

Article
02/29/2024

FltCbdqInsertIo insère la structure de données de rappel pour une opération d’E/S dans la file d’attente de données de rappel d’un pilote de filtre.

Syntaxe

NTSTATUS FLTAPI FltCbdqInsertIo(
  [in, out]      PFLT_CALLBACK_DATA_QUEUE            Cbdq,
  [in]           PFLT_CALLBACK_DATA                  Cbd,
  [in, optional] PFLT_CALLBACK_DATA_QUEUE_IO_CONTEXT Context,
  [in, optional] PVOID                               InsertContext
);

Paramètres

[in, out] Cbdq

Pointeur vers la file d’attente de données de rappel cancel-safe de l’appelant. Cette file d’attente doit avoir été initialisée en appelant FltCbdqInitialize.

[in] Cbd

Pointeur vers la structure de données de rappel (FLT_CALLBACK_DATA) pour l’opération d’E/S à mettre en file d’attente. L’opération doit être une opération d’E/S basée sur IRP.

[in, optional] Context

Variable fournie par l’appelant qui reçoit un pointeur de contexte opaque pour la demande d’E/S. Les pilotes de filtre peuvent utiliser ce pointeur pour identifier un élément spécifique dans la file d’attente afin qu’il puisse être supprimé en appelant FltCbdqRemoveIo. Si le pilote de filtre n’est pas nécessaire pour supprimer des demandes d’E/S particulières de la file d’attente, ce paramètre peut être NULL.

[in, optional] InsertContext

Pointeur de contexte à passer à la routine de rappel CbdqInsertIo du pilote de filtre.

Valeur retournée

FltCbdqInsertIo retourne STATUS_SUCCESS lorsque la structure de données de rappel a été insérée dans la file d’attente de données de rappel, ou une valeur NTSTATUS appropriée, telle que la suivante :

Code de retour	Description
STATUS_FLT_CBDQ_DISABLED	La structure des données de rappel n’a pas été insérée dans la file d’attente de données de rappel, car la file d’attente est actuellement désactivée. Pour réactiver la file d’attente, appelez FltCbdqEnable. Il s’agit d’un code d’erreur.

Notes

En cas de réussite, FltCbdqInsertIo retourne le rappel InsertIo du filtre ; par exemple, un filtre peut retourner STATUS_SUCCESS ou STATUS_PENDING pour indiquer la réussite. Il est important que le filtre soit auto-cohérent selon la valeur qu’il utilise pour indiquer la réussite.

Remarques

FltCbdqInsertIo insère la structure de données de rappel (FLT_CALLBACK_DATA) spécifiée dans la file d’attente de données de rappel d’un pilote de filtre.

Notez qu’il existe une condition de concurrence potentielle entre un pilote de filtre qui insère les données de rappel et l’IRP associé en cours d’annulation. Cela peut être évité en appelant immédiatement la routine d’annulation de la file d’attente si l’IRP a déjà été annulé.

Les pilotes de filtre peuvent utiliser les routines FltCbdqXxx pour implémenter une file d’attente de données de rappel pour les opérations d’E/S basées sur IRP. En utilisant ces routines, les pilotes de filtre peuvent rendre leurs files d’attente cancel-safe ; le système gère en toute transparence l’annulation des E/S pour les pilotes de filtre.

Les routines FltCbdqXxx ne peuvent être utilisées 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 .

Une file d’attente de données de rappel est initialisée en appelant FltCbdqInitialize. FltCbdqInsertIo utilise les fonctions fournies dans la table de répartition de la file d’attente pour verrouiller la file d’attente et insérer la structure de données de rappel dans la file d’attente. L’opération d’insertion elle-même est effectuée par la routine CbdqInsertIo de la file d’attente.

Pour plus d’informations sur la création d’une file d’attente de données de rappel, consultez FltCbdqInitialize . Utilisez FltCbdqRemoveIo pour supprimer une requête d’E/S particulière de la file d’attente, ou FltCbdqRemoveNextIo pour supprimer la requête d’E/S disponible suivante.

Si la file d’attente est protégée par un verrou de rotation plutôt qu’un objet mutex ou une variable de ressource, l’appelant de FltCbdqInsertIo peut s’exécuter sur IRQL <= DISPATCH_LEVEL. Si un mutex ou une ressource est utilisé, l’appelant doit s’exécuter sur IRQL <= APC_LEVEL.