KDEFERRED_ROUTINE fonction de rappel (wdm.h)

Article
03/08/2023

La routine de rappel effectue des actions, après le retour d’un service InterruptService , d’un DPC threadé,

La routine CustomDpc termine la maintenance d’une opération d’E/S, après le retour d’une routine InterruptService .

La routine CustomThreadedDpc effectue l’action d’un DPC threadé. Le système exécute cette routine lorsque le DPC threadé s’exécute.

La routine CustomTimerDpc s’exécute après l’expiration de l’intervalle de temps d’un objet de minuteur.

Syntaxe

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

Paramètres

[in] Dpc

Pointeur fourni par l’appelant vers une structure KDPC , qui représente l’objet DPC associé à cette routine de rappel.

[in, optional] DeferredContext

Pour CustomDpc, pointeur fourni par l’appelant vers des informations de contexte définies par le pilote qui ont été spécifiées dans un appel précédent à KeInitializeDpc.

Pour CustomThreadedDpc, spécifie des informations de contexte définies par le pilote. Quand il a initialisé l’objet DPC, le pilote a fourni cette valeur en tant que paramètre DeferredContext à KeInitializeThreadedDpc.

Pointeur fourni par l’appelant vers une structure KDPC , qui représente l’objet DPC associé à cette routine CustomTimerDpc .

[in, optional] SystemArgument1

Pointeur fourni par l’appelant vers les informations fournies par le pilote qui ont été spécifiées dans un appel précédent à KeInsertQueueDpc. Quand il a ajouté le DPC à la file d’attente DPC, le pilote a fourni cette valeur en tant que paramètre SystemArgument1 à KeInsertQueueDpc.

Pour CustomTimerDpc, cette valeur n’est pas utilisée.

[in, optional] SystemArgument2

Spécifie les informations de contexte définies par le pilote. Quand il a ajouté le DPC à la file d’attente DPC, le pilote a fourni cette valeur en tant que paramètre SystemArgument2 à KeInsertQueueDpc.

Pour CustomTimerDpc, cette valeur n’est pas utilisée.

Valeur de retour

None

Remarques

Pour créer un objet DPC et inscrire une routine CustomDpc pour cet objet, un pilote doit appeler KeInitializeDpc. (Si vous n’avez besoin que d’une seule routine DPC, vous pouvez utiliser une routine DpcForIsr et l’objet DPC alloué par le système.)

Pour mettre en file d’attente une routine CustomDpc en vue de son exécution, la routine InterruptService d’un pilote doit appeler KeInsertQueueDpc.

Une ou plusieurs routines CustomDpc peuvent être utilisées à la place ou conjointement avec une routine DpcForIsr . Un pilote qui gère plusieurs files d’attente IRP internes fournit généralement une routine CustomDpc pour chaque file d’attente. Chaque routine CustomDpc est généralement responsable au moins des tâches suivantes :

Exécution de l’opération d’E/S décrite par l’IRP actuel.
Retrait de la file d’attente IRP suivante de l’une des files d’attente IRP du pilote. (Les pilotes qui utilisent la file d’attente IRP fournie par le système avec un appel de routine StartIo IoStartNextPacket.)
Définir le bloc d’E/S status dans l’IRP actuel et appeler IoCompleteRequest pour la demande terminée.

Une routine CustomDpc peut également réessayer une opération ayant échoué ou configurer le transfert suivant pour une demande d’E/S volumineuse qui a été divisée en morceaux plus petits.

Pour plus d’informations sur les routines CustomDpc , consultez Objets DPC et DPC.

Un pilote inscrit un CustomThreadedDpc pour un objet DPC en appelant KeInitializeThreadedDpc. Pour ajouter la DPC à la file d’attente DPC afin que la routine CustomThreadedDpc soit exécutée, appelez KeInsertQueueDpc.

Pour plus d’informations sur l’utilisation des routines CustomThreadedDpc , consultez Présentation des DPC threads.

Une routine CustomThreadedDpc peut s’exécuter sur IRQL = DISPATCH_LEVEL, ou sur IRQL = PASSIVE_LEVEL dans un thread en temps réel.

Pour créer un objet DPC et inscrire une routine CustomTimerDpc pour cet objet, un pilote doit appeler KeInitializeDpc.

Pour mettre en file d’attente une routine CustomTimerDpc en vue de son exécution, une routine de pilote doit appeler KeSetTimer ou KeSetTimerEx, en fournissant un pointeur d’objet DPC retourné par KeInitializeDpc. Le système appelle la routine CustomTimerDpc lorsque l’intervalle du minuteur expire.

Pour plus d’informations sur les routines CustomTimerDpc , consultez Objets de minuteur et DPC.

Exemples

Pour définir une routine de rappel, vous devez d’abord fournir une déclaration de fonction qui identifie le type de routine de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel CustomDpc nommée MyCustomDpc, utilisez le type KDEFERRED_ROUTINE comme indiqué dans cet exemple de code :

KDEFERRED_ROUTINE MyCustomDpc;

Ensuite, implémentez votre routine de rappel comme suit :

_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }