DRIVER_OBJECT Struktur (wdm.h)

Artikel
07.02.2025

Jedes Treiberobjekt stellt das Bild eines geladenen Kernelmodustreibers dar. Ein Zeiger auf das Treiberobjekt ist ein Eingabeparameter für die DriverEntry, AddDeviceund optionale Reinitialisieren Routinen und dessen Unload Routine( falls vorhanden).

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

Syntax

C++

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;

Angehörige

Type

Definiert das CSHORT Member Type.

Size

Definiert das CSHORT Member Size.

DeviceObject

Zeigen Sie auf die vom Treiber erstellten Geräteobjekte. Dieses Mitglied wird automatisch aktualisiert, wenn der Treiber IoCreateDevice erfolgreich aufruft. Ein Treiber kann dieses Element und das NextDevice- Mitglied von DEVICE_OBJECT verwenden, um eine Liste aller geräteobjekte zu durchlaufen, die der Treiber erstellt hat.

Flags

Definiert das ULONG Member Flags.

DriverStart

Definiert das PVOID Member DriverStart.

DriverSize

Definiert das ULONG Member DriverSize.

DriverSection

Definiert das PVOID Member DriverSection.

DriverExtension

Zeiger auf die Treibererweiterung. Das einzige barrierefreie Mitglied der Treibererweiterung ist DriverExtension->AddDevice-, in dem die DriverEntry Routine des Treibers die AddDevice Routine des Treibers speichert.

DriverName

Definiert das UNICODE_STRING Member DriverName-.

HardwareDatabase

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

FastIoDispatch

Zeigen Sie auf eine Struktur, die die schnellen E/A-Einstiegspunkte des Treibers definiert. Dieses Mitglied 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, die durch die DriverEntry-Routine festgelegt wird, wenn der Treiber initialisiert wird. Wenn ein Treiber keine StartIo- Routine hat, ist dieses Element NULL-.

DriverUnload

Der Einstiegspunkt für die Unload Routine des Treibers, falls vorhanden, die von der DriverEntry-Routine festgelegt wird, wenn der Treiber initialisiert wird. Wenn ein Treiber keine Unload Routine hat, ist dieses Element NULL-.

MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1]

Eine Verteilertabelle, die aus einem Array von Einstiegspunkten für die DispatchXxx Routinen des Fahrers besteht. Die Indexwerte des Arrays sind die IRP_MJ_XXX- Werte, die jeden Hauptfunktionscodedarstellen. 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 Versandroutinen.

Um Codeanalyse für Treiber, Statische Treiberüberprüfung (SDV) und andere Überprüfungstools zu unterstützen, wird jede DispatchXxx Routine mithilfe des DRIVER_DISPATCH Typs deklariert, wie in diesem Codebeispiel gezeigt:

C++

DRIVER_DISPATCH DispatchXxx;

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

C++

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

Der DRIVER_DISPATCH Funktionstyp wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition unbedingt die _Use_decl_annotations_-Anmerkung hinzufügen. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den funktionstyp DRIVER_DISPATCH in der Headerdatei angewendet werden, verwendet 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.

Bemerkungen

Die Initialisierungsroutine jedes Kernelmodustreibers sollte DriverEntry- benannt werden, 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 der E/A-Manager die Übertragungsadresse des Treibers nicht finden. Die Namen anderer Standardtreiberroutinen können nach Ermessen des Fahrerschreibers ausgewählt werden.

Ein Treiber muss seine DispatchXxx- Einstiegspunkte im Treiberobjekt festlegen, das an die DriverEntry Routine übergeben wird, wenn der Treiber geladen wird. Ein Gerätetreiber muss einen oder mehrere DispatchXxx Einstiegspunkte 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 wird ein Treiber keine IRPs für IRP_MJ_XXX- gesendet, für die er keine DispatchXxx- Routine im Treiberobjekt einrichtet. Weitere Informationen zum Satz von IRP_MJ_XXX-, die Treiber für verschiedene Typen zugrunde liegenden Geräte verarbeiten müssen, finden Sie unter IRP Major Function Codes.

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

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 die \Registry\Machine\System\CurrentControlSet\Services\DriverName Schlüssel, wobei der Werteintrag von DriverName den Treiber identifiziert. Wie für die HardwareDatabase- im Eingabetreiberobjekt erhält ein Treiber schreibgeschützten Zugriff auf diese Zeichenfolge.

Nicht dokumentierte Elemente innerhalb eines Treiberobjekts sollten als nicht zugänglich angesehen werden. Treiber mit Abhängigkeiten von Objektmemberspeicherorten oder zugriff auf nicht dokumentierte Member bleiben im Laufe der Zeit möglicherweise nicht portabel und interoperabel mit anderen Treibern.