DRIVER_OBJECT Struktur (wdm.h)

Jedes Treiberobjekt stellt das Bild eines geladenen Kernelmodustreibers dar. Der E/A-Manager weist die DRIVER_OBJECT Struktur zu und übergibt sie ggf. als Eingabeparameter an die DriverEntry-, AddDevice- und optionalen Reinitialisierungsroutinen sowie an die Unload-Routine .

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

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

Gibt den Objekttypbezeichner für das Treiberobjekt an. Der E/A-Manager legt dieses Feld fest, wenn es das Treiberobjekt zuweist. Treiber sollten dieses Feld nicht verwenden oder ändern.

Size

Gibt die Größe der Treiberobjektstruktur in Bytes an. Der E/A-Manager legt dieses Feld fest, wenn es das Treiberobjekt zuweist. Treiber sollten dieses Feld nicht verwenden oder ändern.

DeviceObject

Zeigen Sie auf das erste Geräteobjekt in einer verknüpften Liste von Geräteobjekten, die vom Treiber erstellt wurden. Dieses Feld verknüpft alle Geräte, die von einem einzelnen Treiber in einer Liste erstellt wurden. Dieses Mitglied wird automatisch vom E/A-Manager aktualisiert, wenn der Treiber IoCreateDevice erfolgreich aufruft. Ein Treiber kann dieses Element und das NextDevice-Mitglied von DEVICE_OBJECT verwenden, um die vollständige Liste aller Geräteobjekte zu durchlaufen, die der Treiber erstellt hat. Dies ist besonders hilfreich beim Entladen des Treibers, um sicherzustellen, dass alle Geräteobjekte ordnungsgemäß bereinigt werden.

Flags

Enthält vom System definierte Flags, die verschiedene Attribute und Zustände des Treibers beschreiben. Dieses Feld stellt eine erweiterbare Kennzeichnungsposition für Treiberobjekte bereit. Diese Flags werden vom E/A-Manager und anderen Systemkomponenten festgelegt und verwaltet. Treiber sollten dieses Feld nicht direkt ändern.

DriverStart

Verweist auf die virtuelle Basisadresse, an der das Treiberimage im Systemspeicher geladen wird. Diese Adresse stellt den Anfang des Codeabschnitts des Treibers im Kerneladressraum dar. Der E/A-Manager legt diesen Wert fest, wenn der Treiber geladen wird.

DriverSize

Gibt die Größe des Treiberimages im Arbeitsspeicher in Bytes an. Dieser Wert stellt den gesamtspeicherbedarf des geladenen Treibers dar, einschließlich Code, Daten und anderen Abschnitten. Der E/A-Manager legt diesen Wert fest, wenn der Treiber geladen wird.

DriverSection

Verweist auf das Abschnittsobjekt des Treibers, das das Treiberimage im Speicher-Manager darstellt. Dies ist eine undurchsichtige Systemstruktur, die intern vom Speicher-Manager und Ladeprogramm verwendet wird. Treiber sollten nicht auf dieses Mitglied zugreifen oder ändern.

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

Enthält den Unicode-Zeichenfolgennamen des Treibers. Dieses Feld wird vom Fehlerprotokollthread verwendet, um den Namen des Treibers zu bestimmen, an den eine E/A-Anforderung gebunden ist oder an diesen gebunden wurde. Dies ist in der Regel das Formular \Driver\DriverName, wobei DriverName dem Dienstnamen des Treibers in der Registrierung entspricht. Der E/A-Manager legt diesen Wert basierend auf der Registrierungskonfiguration des Treibers fest.

HardwareDatabase

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

FastIoDispatch

Zeigen Sie auf eine FAST_IO_DISPATCH Struktur, die die schnellen E/A-Einstiegspunkte des Treibers definiert. Dieser optionale Zeiger verweist auf ein Array alternativer Einstiegspunkte auf einen Treiber für schnelle E/A-Unterstützung. Schnelle E/A wird durchgeführt, indem die Treiberroutine direkt mit separaten Parametern aufgerufen wird, anstatt den standardmäßigen IRP-Aufrufmechanismus zu verwenden. Beachten Sie, dass diese Funktionen nur für synchrone E/A-Vorgänge und beim Zwischenspeichern der Datei verwendet werden können. Dieses Element wird nur von Dateisystemtreibern (FSDs) und Netzwerktransporttreibern verwendet.

DriverInit

Die Einstiegspunktadresse für die DriverEntry-Routine des Fahrers. Der E/A-Manager legt dieses Feld so fest, dass es auf die Initialisierungsfunktion des Treibers verweist, wenn der Treiber geladen wird. Dies ist die erste Funktion, die im Treiber aufgerufen wird, wenn sie in den Arbeitsspeicher geladen wird, und sie ist für die Initialisierung des Treiberobjekts und das Einrichten von Dispatch-Routinen verantwortlich.

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. Diese Hauptfunktionsverteilungstabelle muss das letzte Feld im Objekt sein, damit sie erweiterbar bleibt. 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:

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

Jede Initialisierungsroutine des 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 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. Dieser Registrierungsschlüssel enthält die Dienstkonfiguration des Treibers, einschließlich der Folgenden:

• Start: Wenn der Treiber geladen werden soll (Start, System, automatisch, Bedarf oder deaktiviert)
• Typ: Der Diensttyp (Kerneltreiber, Dateisystemtreiber usw.)
• ErrorControl: Wie das System reagieren soll, wenn der Treiber nicht geladen werden kann
• ImagePath: Der Pfad zur Treiber-Binärdatei

Treiber können zusätzliche Konfigurationsdaten unter dem Parameter-Unterschlüssel ihres Dienstschlüssels speichern. 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.

Anforderungen

Siehe auch

DriverEntry-

IoCreateDevice

IoDeleteDevice-

StartIo-

Entladen