DRIVER_OBJECT-Struktur (wdm.h)
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_annotations
Anmerkung _ 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.
Anforderungen
Anforderung | Wert |
---|---|
Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |