Fonction FltCbdqInitialize (fltkernel.h)

Article
02/29/2024

FltCbdqInitialize initialise la table de répartition de la file d’attente de données de rappel d’un pilote minifiltre.

Syntaxe

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

Paramètres

[in] Instance

Pointeur de instance opaque pour le instance dont la file d’attente de données de rappel doit être initialisée.

[in, out] Cbdq

Pointeur vers une file d’attente de données de rappel allouée par le pilote de minifiltre.

[in] CbdqInsertIo

Pointeur vers une routine de rappel d’insertion fournie par l’appelant. Le Gestionnaire de filtres appelle cette routine pour insérer la structure de données de rappel spécifiée dans la file d’attente. Cette routine est déclarée comme suit :

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

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

Cdb

Pointeur vers la structure de données de rappel à insérer dans la file d’attente.

InsertContext

Pointeur d’informations de contexte qui a été passé en tant que paramètre InsertContext à FltCbdqInsertIo.

[in] CbdqRemoveIo

Pointeur vers une routine de rappel de suppression fournie par l’appelant. Le Gestionnaire de filtres appelle cette routine pour supprimer la structure de données de rappel spécifiée de la file d’attente. Cette routine est déclarée comme suit :

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

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

Cdb

Pointeur vers la structure de données de rappel à supprimer de la file d’attente.

[in] CbdqPeekNextIo

Pointeur vers une routine de rappel fournie par l’appelant. Le Gestionnaire de filtres appelle cette fonction pour obtenir un pointeur vers l’opération d’E/S suivante correspondant à PeekContext dans la file d’attente ; ou, si Le Cbd a la valeur NULL, pour obtenir un pointeur vers la première opération d’E/S correspondante dans la file d’attente. Le pilote minifilter définit entièrement la signification de PeekContext et définit quand une opération d’E/S correspond à un PeekContext donné. Cette routine est déclarée comme suit :

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

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

Cdb

Pointeur vers la structure de données de rappel marquant la position dans la file d’attente pour commencer la recherche d’une correspondance à PeekContext. Si le Cbd a la valeur NULL, la recherche commence en tête de la file d’attente.

PeekContext

Pointeur d’informations de contexte qui a été passé en tant que paramètre PeekContext à FltCbdqRemoveNextIo.

[in] CbdqAcquire

Pointeur vers une routine de rappel de verrouillage de file d’attente d’acquisition fournie par l’appelant. Le Gestionnaire de filtres appelle cette routine pour acquérir le verrou sur la file d’attente avant de tenter d’insérer ou de supprimer un élément de la file d’attente. Cette routine est déclarée comme suit :

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

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

Irql

Pointeur vers une variable fournie par le système qui reçoit l’IRQL actuel. La même variable est passée à la routine CbdqRelease correspondante.

[in] CbdqRelease

Pointeur vers une routine de rappel de verrouillage de la file d’attente fournie par l’appelant. Le Gestionnaire de filtres appelle cette routine pour libérer le verrou qu’elle a obtenu en appelant la routine CbdqAcquire correspondante. Cette routine est déclarée comme suit :

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

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

Irql

La même variable fournie par le système qui a reçu l’IRQL actuel que le paramètre Irql de la routine CbdqAcquire correspondante.

[in] CbdqCompleteCanceledIo

Pointeur vers une routine d’annulation fournie par l’appelant. Le Gestionnaire de filtres appelle cette routine pour signaler au pilote de minifiltre l’opération d’E/S annulée. Cette routine est déclarée comme suit :

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

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

Cdb

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

Valeur retournée

FltCbdqInitialize retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée.

Remarques

La file d’attente de données de rappel nouvellement initialisée est à l’état activé, ce qui signifie que les éléments de structure de données de rappel peuvent être insérés dans la file d’attente. La file d’attente peut être désactivée en appelant FltCbdqDisable et réactivée en appelant FltCbdqEnable.

Les pilotes de minifiltre 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 minifiltre peuvent rendre leurs files d’attente annulées-sécurisées ; le système gère de manière transparente l’annulation des E/S pour les pilotes de minifiltre.

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 .

Les pilotes de minifiltre peuvent utiliser n’importe quelle implémentation interne pour la file d’attente. Le Gestionnaire de filtres interagit avec l’implémentation de file d’attente du pilote minifiltre uniquement par le biais de l’ensemble de routines de répartition fournies par FltCbdqInitialize.

Le système verrouille et déverrouille automatiquement la file d’attente si nécessaire. Les pilotes de minifiltres n’implémentent aucun verrouillage à l’intérieur de leurs routines CbdqInsertIo, CbdqRemoveIo et CbdqPeekNextIo .

Les pilotes de minifiltre peuvent utiliser n’importe quelle primitive de synchronisation du système d’exploitation comme mécanisme de verrouillage dans leurs routines CbdqAcquire et CbdqRelease , telles qu’un verrou de rotation, un objet mutex ou une variable de ressource. Notez que si un pilote de minifiltre utilise un verrou de rotation plutôt qu’un mutex ou une ressource pour protéger la file d’attente, il peut appeler les routines FltCbdqXxx à IRQL <= DISPATCH_LEVEL. Si un mutex ou une ressource est utilisé, le pilote de minifiltre doit s’exécuter à IRQL <= APC_LEVEL lorsqu’il appelle l’une de ces routines, à l’exception de FltCbdqInitialize.

Le pilote de minifiltre ne manipule pas directement la file d’attente. Au lieu de cela, il appelle FltCbdqInsertIo, FltCbdqRemoveIo et FltCbdqRemoveNextIo pour ajouter ou supprimer une structure de données de rappel. Ces routines appellent à leur tour les fonctions de rappel fournies par le pilote de minifiltre à FltCbdqInitialize.

Les pilotes de minifiltre doivent implémenter les routines de file d’attente comme suit.

Cbdq Routine	Implémentation
CbdqInsertIo	Insérez la structure de données de rappel spécifiée dans la file d’attente.
CbdqRemoveIo	Supprimez la structure de données de rappel spécifiée de la file d’attente.
CbdqPeekNextIo	Cette routine doit permettre au système de parcourir en boucle les structures de données de rappel avec PeekContext correspondant dans la file d’attente. Cdb = CbdqPeekNextIo(Cbdq, NULL, PeekContext) doit retourner la première entrée correspondante dans la file d’attente, et CbdqPeekNextIo (Cbdq, Cbd, PeekContext) doit retourner l’entrée correspondante suivante après la structure de données de rappel donnée dans la file d’attente. Le pilote de minifiltre définit entièrement la signification de PeekContext et définit quand une structure de données de rappel correspond à une valeur PeekContext .
CbdqAcquire	Cette routine doit verrouiller la file d’attente afin qu’aucun autre thread ne puisse y accéder. Les pilotes de minifiltre peuvent utiliser n’importe quel mécanisme de verrouillage pour verrouiller la file d’attente. Si le pilote de minifiltre utilise la routine KeAcquireSpinLock , le pilote de minifiltre peut utiliser l’emplacement de mémoire pointé par le paramètre Irql de la routine pour stocker l’IRQL. Sinon, les pilotes de minifiltre peuvent ignorer ce paramètre.
CbdqRelease	Cette routine doit déverrouiller la file d’attente créée par CbdqAcquire. Si le pilote minifilter a utilisé un verrou de rotation et retourné la valeur IRQL dans le paramètre Irql de CbdqAcquire, le système transmet cette valeur dans le paramètre Irql de CbdqRelease. Le pilote minifilter peut utiliser l’IRQL pour déverrouiller le verrou de rotation en appelant KeReleaseSpinLock. Sinon, les pilotes minifilter peuvent ignorer le paramètre Irql .
CbdqCompleteCanceledIo	Cette routine doit terminer une opération d’E/S annulée. Normalement, les pilotes de minifiltre peuvent simplement appeler FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). Les pilotes minifiltres n’ont pas besoin de mettre en file d’attente la structure de données de rappel : le Gestionnaire de filtres appelle automatiquement le CbdqRemoveIo de la file d’attente avant d’appeler CbdqCompleteCanceledIo.