structure DRIVER_OBJECT (wdm.h)

Article
02/07/2025

Chaque objet de pilote représente l’image d’un pilote en mode noyau chargé. Un pointeur vers l’objet pilote est un paramètre d’entrée vers l'DriverEntryd’un pilote, AddDeviceet facultatif Réinitialiser routines et à sa routine Décharger routine, le cas échéant.

Un objet de pilote est partiellement opaque. Les enregistreurs de pilotes doivent connaître certains membres d’un objet pilote pour initialiser un pilote et le décharger si le pilote est déchargé. Les membres suivants de l’objet de pilote sont accessibles aux pilotes.

Syntaxe

typedef struct _DRIVER_OBJECT {
  CSHORT             Type;
  CSHORT             Size;
  PDEVICE_OBJECT     DeviceObject;
  ULONG              Flags;
  PVOID              DriverStart;
  ULONG              DriverSize;
  PVOID              DriverSection;
  PDRIVER_EXTENSION  DriverExtension;
  UNICODE_STRING     DriverName;
  PUNICODE_STRING    HardwareDatabase;
  PFAST_IO_DISPATCH  FastIoDispatch;
  PDRIVER_INITIALIZE DriverInit;
  PDRIVER_STARTIO    DriverStartIo;
  PDRIVER_UNLOAD     DriverUnload;
  PDRIVER_DISPATCH   MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1];
} DRIVER_OBJECT, *PDRIVER_OBJECT;

Membres

Type

Définit le membre CSHORTType.

Size

Définit le membre CSHORT Size.

DeviceObject

Pointeur vers les objets d’appareil créés par le pilote. Ce membre est automatiquement mis à jour lorsque le pilote appelle IoCreateDevice correctement. Un pilote peut utiliser ce membre et le NextDevice membre de DEVICE_OBJECT pour parcourir une liste de tous les objets d’appareil créés par le pilote.

Flags

Définit le membre ULONG Flags.

DriverStart

Définit le membre PVOIDDriverStart.

DriverSize

Définit le membre ULONGDriverSize.

DriverSection

Définit le membre PVOIDDriverSection.

DriverExtension

Pointeur vers l’extension du pilote. Le seul membre accessible de l’extension de pilote est DriverExtension->AddDevice, dans lequel la routine DriverEntry d’un pilote stocke la routine AddDevice du pilote.

DriverName

Définit le membre UNICODE_STRINGDriverName.

HardwareDatabase

Pointeur vers le chemin \Registry\Machine\Hardware vers les informations de configuration matérielle dans le Registre.

FastIoDispatch

Pointeur vers une structure définissant les points d’entrée d’E/S rapides du pilote. Ce membre est utilisé uniquement par les disques FSD et les pilotes de transport réseau.

DriverInit

Point d’entrée de la routine DriverEntry, qui est configuré par le gestionnaire d’E/S.

DriverStartIo

Point d’entrée de la routine StartIo du pilote, le cas échéant, défini par la routine DriverEntry lors de l’initialisation du pilote. Si aucun pilote n’a routine StartIo, ce membre est NULL.

DriverUnload

Point d’entrée de la routine Décharger du pilote, le cas échéant, défini par la routine DriverEntry lors de l’initialisation du pilote. Si un pilote n’a pas de routine décharger, ce membre est NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Table de répartition composée d’un tableau de points d’entrée pour les routines DispatchXxx du pilote. Les valeurs d’index du tableau sont les valeurs IRP_MJ_XXX représentant chaque code de fonction principal IRP . Chaque pilote doit définir des points d’entrée dans ce tableau pour le IRP_MJ_XXX demandes que le pilote gère. Pour plus d’informations, consultez Écriture de routines de répartition.

Pour aider 'analyse du code pour les pilotes, le vérificateur de pilotes statiques (SDV) et d’autres outils de vérification, chaque routine DispatchXxx est déclarée à l’aide du type DRIVER_DISPATCH, comme illustré dans cet exemple de code :

DRIVER_DISPATCH DispatchXxx;

Ensuite, la routine de rappel est implémentée comme suit :

_Use_decl_annotations_
NTSTATUS
  DispatchXxx(
    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 l'_Use_decl_annotations_ annotation à votre définition de fonction. L’annotation _Use_decl_annotations_ 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 les exigences relatives aux 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 annoter le comportement de la fonction.

Remarques

La routine d’initialisation de chaque pilote en mode noyau doit être nommée DriverEntry afin que le système charge automatiquement le pilote. Si le nom de cette routine est autre chose, l’enregistreur de pilotes doit définir le nom de la routine d’initialisation pour l’éditeur de liens ; sinon, le chargeur système ou le gestionnaire d’E/S ne trouve pas l’adresse de transfert du pilote. Les noms d’autres routines de pilotes standard peuvent être choisis à la discrétion de l’enregistreur de pilotes.

Un pilote doit définir son DispatchXxx points d’entrée dans l’objet pilote transmis à la routine DriverEntry lors du chargement du pilote. Un pilote de périphérique doit définir un ou plusieurs DispatchXxx points d’entrée pour le IRP_MJ_XXX que tout pilote du même type d’appareil est requis pour gérer. Un pilote de niveau supérieur doit définir un ou plusieurs DispatchXxx points d’entrée pour tous les IRP_MJ_XXX qu’il doit transmettre au pilote de périphérique sous-jacent. Sinon, un pilote n’est pas envoyé d’IRPs pour une IRP_MJ_XXX pour laquelle il ne configure pas de routine DispatchXxx dans l’objet du pilote. Pour plus d’informations sur l’ensemble de IRP_MJ_XXX que les pilotes pour différents types d’appareils sous-jacents doivent être gérés, consultez codes de fonction principaux IRP.

La routine DriverEntry définit également les AddDevicedu pilote, StartIo et/ou Décharger points d’entrée, le cas échéant, dans l’objet pilote.

La chaîne HardwareDatabase peut être utilisée par les pilotes de périphérique pour obtenir des informations de configuration matérielle à partir du Registre lorsque le pilote est chargé. Un pilote reçoit un accès en lecture seule à cette chaîne.

L’entrée RegistryPath à la routine DriverEnt ry pointe vers la routine \Registry\Machine\System\CurrentControlSet\Services\DriverName, où l’entrée de valeur de DriverName identifie le pilote. Comme pour l'HardwareDatabase dans l’objet du pilote d’entrée, un pilote reçoit un accès en lecture seule à cette chaîne.

Les membres non documentés au sein d’un objet de pilote doivent être considérés comme inaccessibles. Les pilotes avec dépendances sur les emplacements des membres d’objet ou sur l’accès aux membres non documentés peuvent ne pas rester portables et interopérables avec d’autres pilotes au fil du temps.