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). |