DRIVER_DISPATCH fonction de rappel (wdm.h)

La routine de rappel prend en compte différents IRPs. Pour obtenir la liste des codes de fonction, consultez Remarques.

Syntaxe

DRIVER_DISPATCH DriverDispatch;

NTSTATUS DriverDispatch(
  [in, out] _DEVICE_OBJECT *DeviceObject,
  [in, out] _IRP *Irp
)
{...}

Paramètres

[in, out] 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 qui décrit l’opération d’E/S demandée.

Valeur retournée

Si la routine réussit, elle doit retourner STATUS_SUCCESS. Sinon, il doit retourner l’une des valeurs d’erreur status définies dans Ntstatus.h.

Remarques

Les paramètres d’entrée de toutes les routines Dispatch sont fournis dans la structure IRP pointée par Irp. Des paramètres supplémentaires sont fournis dans l’emplacement de pile d’E/S associé au pilote, qui est décrit par la structure IO_STACK_LOCATION et peut être obtenu en appelant IoGetCurrentIrpStackLocation.

En règle générale, toutes les routines dispatch s’exécutent dans un contexte de thread arbitraire à IRQL = PASSIVE_LEVEL, mais il existe des exceptions. Pour plus d’informations, consultez Dispatch Routines and IRQLs.

Pour plus d’informations sur les routines de répartition, consultez Écriture de routines de répartition. Pour plus d’informations sur les IRPs, consultez Gestion des IRPs.

IRP À propos de l’implémentation du rappel
IRP_MJ_CLEANUP La routine DispatchCleanup d’un pilote doit être nommée XxxDispatchCleanup, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchCleanup dans DriverObject-MajorFunction>[IRP_MJ_CLEANUP].
IRP_MJ_CLOSE La routine DispatchClose d’un pilote doit être nommée XxxDispatchClose, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchClose dans DriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_CREATE La routine DispatchCreate d’un pilote doit être nommée XxxDispatchCreate, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchCreate dans DriverObject-MajorFunction>[IRP_MJ_CREATE].
IRP_MJ_CREATE ou IRP_MJ_CLOSE Un pilote peut fournir une seule routine DispatchCreateClose au lieu de deux routines DispatchCreate et DispatchClose distinctes.

La routine DispatchCreateClose d’un pilote doit être nommée XxxDispatchCreateClose, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchCreateClose dans DriverObject-MajorFunction>[IRP_MJ_CREATE] et dansDriverObject-MajorFunction>[IRP_MJ_CLOSE].
IRP_MJ_DEVICE_CONTROL La routine DispatchDeviceControl d’un pilote doit être nommée XxxDispatchDeviceControl, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchDeviceControl dans DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL].

Le système utilise les indicateurs FILE_XXX dans le code de contrôle d’E/S pour déterminer si l’expéditeur IRP dispose des privilèges nécessaires pour envoyer l’IRP à l’objet d’appareil. Les pilotes pour Windows Server 2003 et les versions ultérieures de Windows peuvent utiliser la routine IoValidateDeviceIoControlAccess pour effectuer des vérifications d’accès plus strictes dans DispatchDeviceControl.
IRP_MJ_FLUSH_BUFFERS La routine DispatchFlushBuffers d’un pilote doit être nommée XxxDispatchFlushBuffers, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchFlushBuffers dans DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS].
IRP_MJ_INTERNAL_DEVICE_CONTROL La routine DispatchInternalDeviceControl d’un pilote doit être nommée XxxDispatchInternalDeviceControl, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchInternalDeviceControl dans DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL].
IRP_MJ_PNP La routine DispatchPnP d’un pilote doit être nommée XxxDispatchPnP, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchPnP dans DriverObject-MajorFunction>[IRP_MJ_PNP].
IRP_MJ_POWER La routine DispatchPower d’un pilote doit être nommée XxxDispatchPower, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchPower dans DriverObject-MajorFunction>[IRP_MJ_POWER].
IRP_MJ_QUERY_INFORMATION La routine DispatchQueryInformation d’un pilote doit être nommée XxxDispatchQueryInformation, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchQueryInformation dans DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION].
IRP_MJ_READ La routine DispatchRead d’un pilote doit être nommée XxxDispatchRead, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchRead dans DriverObject-MajorFunction>[IRP_MJ_READ].
IRP_MJ_READ ou IRP_MJ_WRITE Un pilote peut fournir une seule routine DispatchReadWrite au lieu de routines DispatchRead et DispatchWrite distinctes.

La routine DispatchReadWrite d’un pilote doit être nommée XxxDispatchReadWrite, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchReadWrite dans DriverObject-MajorFunction>[IRP_MJ_READ] et dansDriverObject-MajorFunction>[IRP_MJ_WRITE].
IRP_MJ_SET_INFORMATION La routine DispatchSetInformation d’un pilote doit être nommée XxxDispatchSetInformation, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchSetInformation dans DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION].
IRP_MJ_SHUTDOWN La routine DispatchShutdown d’un pilote doit être nommée XxxDispatchShutdown, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du conducteur doit stocker l’adresse de la routine DispatchShutdown dans DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN].

En outre, pour recevoir IRP_MJ_SHUTDOWN demandes, un pilote doit appeler IoRegisterShutdownNotification ou IoRegisterLastChanceShutdownNotification pour inscrire sa routine DispatchShutdown auprès du système.
IRP_MJ_SYSTEM_CONTROL La routine DispatchSystemControl d’un pilote doit être nommée XxxDispatchSystemControl, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchSystemControl dans DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL].
IRP_MJ_WRITE La routine DispatchWrite d’un pilote doit être nommée XxxDispatchWrite, où Xxx est un préfixe spécifique au pilote. La routine DriverEntry du pilote doit stocker l’adresse de la routine DispatchWrite dans DriverObject-MajorFunction>[IRP_MJ_WRITE].

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 DispatchCleanup nommée MyDispatchCleanup, utilisez le type DRIVER_DISPATCH comme indiqué dans cet exemple de code :

DRIVER_DISPATCH MyDispatchCleanup;

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

_Use_decl_annotations_
NTSTATUS
  MyDispatchCleanup(
    struct _DEVICE_OBJECT  *DeviceObject,
    struct _IRP  *Irp
    )
  {
      // Function body
  }

Le type de fonction DRIVER_DISPATCH 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 the_Use_decl_annotations_annotation à votre définition de fonction. The_Use_decl_annotations_annotation garantit que les annotations appliquées au type de fonction DRIVER_DISPATCH 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.

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é à PASSIVE_LEVEL (voir la section Remarques).