DRIVER_CONTROL fonction de rappel (wdm.h)

Cette routine démarre un transfert de données DMA ou une opération de transfert de données.

Syntaxe

DRIVER_CONTROL DriverControl;

IO_ALLOCATION_ACTION DriverControl(
  [in]      _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID Context
)
{...}

Paramètres

[in] DeviceObject

Pointeur fourni par l’appelant vers une structure DEVICE_OBJECT . Il s’agit de l’objet d’appareil pour l’appareil cible, précédemment créé par la routine AddDevice du pilote.

[in, out] Irp

Pointeur fourni par l’appelant vers une structure IRP . Irp est égal à la valeur du membre CurrentIrp de DeviceObject lorsque la routine de rappel a été inscrite.

[in] MapRegisterBase

Dans le cas d’AdapterControl, il s’agit d’une valeur opaque fournie par l’appelant qui représente les registres de carte que le système a attribués pour cette opération de transfert. Le pilote transmet cette valeur à FlushAdapterBuffers, FreeMapRegisters et MapTransfer.

Dans le cas de ControllerControl, il n’est pas utilisé.

[in] Context

Pointeur fourni par l’appelant vers les informations de contexte définies par le pilote, spécifiées dans un appel précédent à AllocateAdapterChannel.

Valeur retournée

La routine doit retourner l’une des valeurs définies par l’énumération IO_ALLOCATION_ACTION . Les pilotes des appareils master bus retournent DeallocateObject ou DeallocateObjectKeepRegisters ; les pilotes qui utilisent le système DMA retournent KeepObject.

Remarques

Pour inscrire une routine AdapterControl pour un objet d’appareil spécifique, un pilote doit appeler IoGetDmaAdapter pour obtenir un objet d’adaptateur, puis appeler AllocateAdapterChannel pour demander l’utilisation de l’adaptateur et fournir l’adresse de la routine AdapterControl . Lorsque l’adaptateur est libre, le système appelle la routine AdapterControl .

Si AdapterControl a été inscrit par une routine StartIo , il est garanti que le paramètre Irp pointe vers l’IRP en cours de traitement par la routine StartIo . Dans le cas contraire, les pilotes doivent définir le membre CurrentIrp de la structure d’objet d’appareil avant d’appeler AllocateAdapterChannel.

Pour plus d’informations sur l’implémentation d’une routine AdapterControl , consultez Écriture de routines AdapterControl.

La routine ControllerControl d’un pilote s’exécute dans un contexte de thread arbitraire à IRQL = DISPATCH_LEVEL.

Pour inscrire une routine ControllerControl pour un objet d’appareil spécifique, un pilote doit appeler IoCreateController pour obtenir un objet contrôleur, puis appeler IoAllocateController pour demander l’utilisation du contrôleur et fournir l’adresse de la routine ControllerControl . Lorsque le contrôleur est libre, le système appelle la routine ControllerControl .

Pour plus d’informations sur l’implémentation d’une routine ControllerControl , consultez Écriture de routines ControllerControl. Consultez également Objets du contrôleur.

Le type de fonction DRIVER_CONTROL est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation _Use_decl_annotations_ à votre définition de fonction. L’annotation _Use_decl_annotations_ garantit que les annotations appliquées au type de fonction DRIVER_CONTROL dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur _Use_decl_annotations_, consultez Annotating Function Behavior.

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 aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’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 AdapterControl nommée MyAdapterControl, utilisez le type DRIVER_CONTROL comme indiqué dans cet exemple de code :

DRIVER_CONTROL MyAdapterControl;

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

_Use_decl_annotations_
IO_ALLOCATION_ACTION
 MyAdapterControl(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp,
    PVOID  MapRegisterBase,
    PVOID  Context
    )
  {
      // Function body
  }

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Appelé à DISPATCH_LEVEL.

Voir aussi

AllocationAdapterChannel