DRIVER_OBJECT-Struktur (wdm.h)

Artikel
03/08/2023

Jedes Treiberobjekt stellt das Image eines geladenen Kernelmodustreibers dar. Ein Zeiger auf das Treiberobjekt ist ein Eingabeparameter auf DriverEntry, AddDevice und optionale Wiederholungsroutinen sowie auf die Deload-Routine eines Treibers, falls vorhanden.

Ein Treiberobjekt ist teilweise undurchsichtig. Treiberautoren müssen bestimmte Elemente eines Treiberobjekts kennen, um einen Treiber zu initialisieren und zu entladen, wenn der Treiber entladen werden kann. Auf die folgenden Member des Treiberobjekts kann für Treiber zugegriffen werden.

Syntax

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;

Member

Type

Definiert den CSHORT-Membertyp.

Size

Definiert die CSHORT-Elementgröße.

DeviceObject

Zeiger auf die vom Treiber erstellten Geräteobjekte. Dieser Member wird automatisch aktualisiert, wenn der Treiber IoCreateDevice erfolgreich aufruft . Ein Treiber kann dieses Element und das NextDevice-Element von DEVICE_OBJECT verwenden, um eine Liste aller vom Treiber erstellten Geräteobjekte zu durchlaufen.

Flags

Definiert die ULONG-Memberflags.

DriverStart

Definiert das PVOID-ElementDriverStart.

DriverSize

Definiert das ULONG-MemberDriverSize.

DriverSection

Definiert das PVOID-ElementDriverSection.

DriverExtension

Zeiger auf die Treibererweiterung. Das einzige zugängliche Element der Treibererweiterung ist DriverExtension-AddDevice, in dem die DriverEntry-Routine> eines Treibers die AddDevice-Routine des Treibers speichert.

DriverName

Definiert das UNICODE_STRING Member DriverName.

HardwareDatabase

Zeigen Sie auf den Pfad \Registry\Machine\Hardware auf die Hardwarekonfigurationsinformationen in der Registrierung.

FastIoDispatch

Zeiger auf eine Struktur, die die schnellen E/A-Einstiegspunkte des Treibers definiert. Dieses Element wird nur von FSDs und Netzwerktransporttreibern verwendet.

DriverInit

Der Einstiegspunkt für die DriverEntry-Routine , die vom E/A-Manager eingerichtet wird.

DriverStartIo

Der Einstiegspunkt für die StartIo-Routine des Treibers, falls vorhanden, der von der DriverEntry-Routine festgelegt wird, wenn der Treiber initialisiert wird. Wenn ein Treiber über keine StartIo-Routine verfügt, ist dieser Member NULL.

DriverUnload

Der Einstiegspunkt für die Entladeroutine des Treibers( falls vorhanden), die von der DriverEntry-Routine festgelegt wird, wenn der Treiber initialisiert wird. Wenn ein Treiber keine Entladeroutine aufweist, ist dieser Member NULL.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Eine Dispatchtabelle, die aus einem Array von Einstiegspunkten für die DispatchXxx-Routinen des Treibers besteht. Die Indexwerte des Arrays sind die IRP_MJ_XXX-Werte , die jeden IRP-Hauptfunktionscode darstellen. Jeder Treiber muss Einstiegspunkte in diesem Array für die IRP_MJ_XXX-Anforderungen festlegen, die der Treiber verarbeitet. Weitere Informationen finden Sie unter Schreiben von Dispatch-Routinen.

Um die Codeanalyse für Treiber, die statische Treiberüberprüfung (Static Driver Verifier , SDV) und andere Überprüfungstools zu unterstützen, wird jede DispatchXxx-Routine mit dem DRIVER_DISPATCH-Typ deklariert, wie in diesem Codebeispiel gezeigt:

DRIVER_DISPATCH DispatchXxx;

Anschließend wird die Rückrufroutine wie folgt implementiert:

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

Der DRIVER_DISPATCH Funktionstyp ist in der Headerdatei Wdm.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die _Use_decl_annotationsAnmerkung _ hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den DRIVER_DISPATCH Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Hinweise

Die Initialisierungsroutine jedes Kernelmodustreibers sollte DriverEntry heißen, damit das System den Treiber automatisch lädt. Wenn der Name dieser Routine etwas anderes ist, muss der Treiberschreiber den Namen der Initialisierungsroutine für den Linker definieren. Andernfalls kann der Systemladeprogramm oder E/A-Manager die Übertragungsadresse des Treibers nicht finden. Die Namen anderer Standardtreiberroutinen können im Ermessen des Treiberschreibers ausgewählt werden.

Ein Treiber muss seine DispatchXxx-Einstiegspunkte im Treiberobjekt festlegen, das beim Laden des Treibers an die DriverEntry-Routine übergeben wird. Ein Gerätetreiber muss mindestens einen DispatchXxx-Einstiegspunkt für die IRP_MJ_XXX festlegen, die jeder Treiber desselben Gerätetyps verarbeiten muss. Ein Treiber auf höherer Ebene muss einen oder mehrere DispatchXxx-Einstiegspunkte für alle IRP_MJ_XXX festlegen, die er an den zugrunde liegenden Gerätetreiber übergeben muss. Andernfalls werden einem Treiber keine IRPs für IRP_MJ_XXX gesendet, für die keine DispatchXxx-Routine im Treiberobjekt eingerichtet wird. Weitere Informationen zum Satz von IRP_MJ_XXX , die Treiber für verschiedene Typen zugrunde liegender Geräte verarbeiten müssen, finden Sie unter IRP-Hauptfunktionscodes.

Die DriverEntry-Routine legt auch die Einstiegspunkte AddDevice, StartIo und/oder Unload des Treibers im Treiberobjekt fest, sofern vorhanden.

Die HardwareDatabase-Zeichenfolge kann von Gerätetreibern verwendet werden, um Hardwarekonfigurationsinformationen aus der Registrierung abzurufen, wenn der Treiber geladen wird. Ein Treiber erhält schreibgeschützten Zugriff auf diese Zeichenfolge.

Die RegistryPath-Eingabe an die DriverEntry-Routine verweist auf den Schlüssel \Registry\Machine\System\CurrentControlSet\Services\DriverName , wobei der Werteintrag von DriverName den Treiber identifiziert. Für die HardwareDatabase im Eingabetreiberobjekt erhält ein Treiber schreibgeschützten Zugriff auf diese Zeichenfolge.

Nicht dokumentierte Member in einem Treiberobjekt sollten als nicht zugänglich betrachtet werden. Treiber mit Abhängigkeiten von Objektmemberspeicherorten oder dem Zugriff auf nicht dokumentierte Member bleiben im Laufe der Zeit möglicherweise nicht portabel und interoperabel mit anderen Treibern.