DEVICE_OBJECT-Struktur (wdm.h)
Die DEVICE_OBJECT-Struktur wird vom Betriebssystem verwendet, um ein Geräteobjekt darzustellen. Ein Geräteobjekt stellt ein logisches, virtuelles oder physisches Gerät dar, für das ein Treiber E/A-Anforderungen verarbeitet.
Syntax
typedef struct _DEVICE_OBJECT {
CSHORT Type;
USHORT Size;
LONG ReferenceCount;
struct _DRIVER_OBJECT *DriverObject;
struct _DEVICE_OBJECT *NextDevice;
struct _DEVICE_OBJECT *AttachedDevice;
struct _IRP *CurrentIrp;
PIO_TIMER Timer;
ULONG Flags;
ULONG Characteristics;
__volatile PVPB Vpb;
PVOID DeviceExtension;
DEVICE_TYPE DeviceType;
CCHAR StackSize;
union {
LIST_ENTRY ListEntry;
WAIT_CONTEXT_BLOCK Wcb;
} Queue;
ULONG AlignmentRequirement;
KDEVICE_QUEUE DeviceQueue;
KDPC Dpc;
ULONG ActiveThreadCount;
PSECURITY_DESCRIPTOR SecurityDescriptor;
KEVENT DeviceLock;
USHORT SectorSize;
USHORT Spare1;
struct _DEVOBJ_EXTENSION *DeviceObjectExtension;
PVOID Reserved;
} DEVICE_OBJECT, *PDEVICE_OBJECT;
Member
Type
Wird vom Betriebssystem verwendet, um anzugeben, dass ein Objekt ein Geräteobjekt ist. Für Geräteobjekte ist der Wert dieses Members 3. Dies ist ein schreibgeschütztes Element.
Size
Gibt die Größe des Geräteobjekts in Bytes an. Diese Größe umfasst die vom Treiber angegebene Geräteerweiterung, auf die vom DeviceExtension-Member verwiesen wird, aber nicht die undurchsichtige Geräteobjekterweiterung, auf die das DeviceObjectExtension-Element verweist. Size ist ein schreibgeschütztes Element.
ReferenceCount
Wird vom E/A-Manager verwendet, um die Anzahl geöffneter Handles für das Gerät nachzuverfolgen, die dem Geräteobjekt zugeordnet sind. Dadurch kann der E/A-Manager das Entladen eines Treibers vermeiden, wenn ausstehende Ziehpunkte für die Geräte des Treibers vorhanden sind. Dies ist ein schreibgeschütztes Element.
DriverObject
Ein Zeiger auf das Treiberobjekt (DRIVER_OBJECT), das das geladene Image des Treibers darstellt, der in die DriverEntry - und AddDevice-Routinen eingegeben wurde. Dieses Element wird vom E/A-Manager bei einem erfolgreichen Aufruf von IoCreateDevice oder IoCreateDeviceSecure festgelegt. Dies ist ein schreibgeschütztes Element.
NextDevice
Ein Zeiger auf das nächste Geräteobjekt, falls vorhanden, das vom gleichen Treiber erstellt wurde. Der E/A-Manager aktualisiert diese Liste bei jedem erfolgreichen Aufruf von IoCreateDevice oder IoCreateDeviceSecure.
Ein nicht Plug & Play (PnP)-Treiber, der entladen wird, muss die Liste seiner Geräteobjekte durchlaufen ("walk") und sie löschen. Ein PnP-Treiber muss diese Liste der Geräteobjekte nicht durchlaufen. Stattdessen führen PnP-Treiber ihre Bereinigung während des PnP-Vorgangs zum Entfernen des Geräts (IRP_MN_REMOVE_DEVICE) durch.
Ein Treiber, der seine Geräteobjekte dynamisch neu erstellt, verwendet diesen Member ebenfalls. Dies ist ein Lese-/Schreibelement.
AttachedDevice
Ein Zeiger auf das angefügte Geräteobjekt. Wenn kein angefügtes Geräteobjekt vorhanden ist, ist dieses Element NULL. Das Geräteobjekt, auf das vom AttachedDevice-Member verwiesen wird, ist in der Regel das Geräteobjekt eines Filtertreibers, das E/A-Anforderungen abfängt, die ursprünglich auf das Gerät ausgerichtet sind, das vom Geräteobjekt dargestellt wird. Weitere Informationen finden Sie in den Themen IoAttachDevice und IoAttachDeviceByPointer . Dies ist ein undurchsichtiges Element.
CurrentIrp
Ein Zeiger auf den aktuellen IRP, wenn der Treiber über eine StartIo-Routine verfügt, deren Einstiegspunkt im Treiberobjekt festgelegt wurde und ob der Treiber derzeit IRP(s) verarbeitet. Andernfalls ist dieser Member NULL. Weitere Informationen finden Sie in den Themen IoStartPacket und IoStartNextPacket . Dies ist ein schreibgeschütztes Element.
Timer
Ein Zeiger auf ein Timerobjekt. Dadurch kann der E/A-Manager jede Sekunde eine vom Treiber bereitgestellte Timerroutine aufrufen. Weitere Informationen finden Sie unter IoInitializeTimer. Dies ist ein Lese-/Schreibelement.
Flags
Gerätetreiber führen einen bitweisen OR-Vorgang mit diesem Member in ihren neu erstellten Geräteobjekten aus, indem sie einen oder mehrere der folgenden systemdefinierte Werte verwenden.
Weitere Informationen zum Festlegen des Flags-Elements finden Sie unter Initialisieren eines Geräteobjekts.
| Wert | Bedeutung |
|---|---|
| DO_VERIFY_VOLUME (0x00000002) | Wechselmedientreiber legen dieses Flag fest, während sie Übertragungsanforderungen verarbeiten. Solche Treiber sollten auch auf dieses Flag im Ziel für eine Übertragungsanforderung überprüfen, bevor sie Daten übertragen. Weitere Informationen finden Sie im Thema Unterstützen von Wechselmedien . |
| DO_BUFFERED_IO (0x00000004) | Gibt den Puffertyp an, der vom E/A-Manager für E/A-Anforderungen verwendet wird, die an den Gerätestapel gesendet werden. Treiber auf höherer Ebene ODER dieses Element mit demselben Wert wie der nächstniedrige Treiber im Stapel, mit Ausnahme von Treibern der höchsten Ebene. |
| DO_EXCLUSIVE (0x00000008) | Gibt an, dass der Treiber ein exklusives Gerät, z. B. ein Video-, serielles, paralleles oder Soundgerät, verwendet. WDM-Treiber dürfen dieses Flag nicht festlegen. Weitere Informationen finden Sie im Thema Angeben des exklusiven Zugriffs auf Geräteobjekte . |
| DO_DIRECT_IO (0x00000010) | Siehe DO_BUFFERED_IO. |
| DO_MAP_IO_BUFFER (0x00000020) | Dieses Flag wird nicht mehr verwendet. Treiber sollten dieses Flag nicht festlegen. |
| DO_DEVICE_INITIALIZING (0x00000080) | Der E/A-Manager legt dieses Flag fest, wenn das Geräteobjekt erstellt wird. Ein Gerätefunktionstreiber oder Filtertreiber löscht das Flag in seiner AddDevice-Routine , nachdem es: (1) Das Geräteobjekt an den Gerätestapel angefügt hat. (2) Legt den Energiezustand des Geräts fest. (3) Führt einen bitweisen OR-Vorgang auf dem Member mit einem der Energieflags aus (falls erforderlich). Der Plug & Play-Manager (PnP) überprüft, ob das Flag nach der Rückgabe der AddDevice-Routine eindeutig ist. |
| DO_SHUTDOWN_REGISTERED (0x00000800) | Wird vom E/A-Manager verwendet, um anzugeben, dass ein Treiber das Geräteobjekt für Benachrichtigungen zum Herunterfahren registriert hat. Dieses Flag sollte nicht von Treibern verwendet werden. |
| DO_BUS_ENUMERATED_DEVICE (0x00001000) | Das Betriebssystem legt dieses Flag in jedem physischen Geräteobjekt (PDO) fest. Treiber dürfen dieses Flag nicht ändern. |
| DO_POWER_PAGABLE (0x00002000) | Auslagerungstreiber, die mit Microsoft Windows 2000 und höheren Versionen von Windows kompatibel sind, nicht Teil des Auslagerungspfads sind und keinen Einschaltstrom erfordern, müssen dieses Flag festlegen. Das System ruft solche Treiber unter IRQL = PASSIVE_LEVEL auf. Treiber können nicht sowohl dieses Flag als auch DO_POWER_INRUSH festlegen. Alle Treiber für WDM, Microsoft Windows 98 und Windows Millennium Edition müssen DO_POWER_PAGABLE festlegen. |
| DO_POWER_INRUSH (0x00004000) | Treiber von Geräten, die einen Einschaltstrom benötigen, wenn das Gerät eingeschaltet ist, müssen dieses Flag festlegen. Ein Treiber kann nicht sowohl dieses Flag als auch DO_POWER_PAGABLE festlegen. |
| DO_DEVICE_TO_BE_RESET (0x04000000) | Der E/A-Manager legt dieses Flag als Signal für den Bustreiber fest, um das Gerät zurückzusetzen. Andere Treiber sollten dieses Flag nicht verwenden. |
| DO_DAX_VOLUME (0x10000000) | Gibt an, dass ein Volume ein DAX-Volume ist. |
Characteristics
Gibt eine oder mehrere systemdefinierte Konstanten in Kombination mit einem bitweisen OR-Vorgang an, die zusätzliche Informationen zum Treibergerät bereitstellen. Diese Konstanten umfassen Folgendes:
| Wert | Bedeutung |
|---|---|
| FILE_AUTOGENERATED_DEVICE_NAME | Weist den E/A-Manager an, einen Namen für das Gerät zu generieren, anstatt dass der Aufrufer beim Aufrufen dieser Routine einen DeviceName angibt. Der E/A-Manager stellt sicher, dass der Name eindeutig ist. Dieses Merkmal wird in der Regel von einem PnP-Bustreiber angegeben, um einen Namen für ein physisches Geräteobjekt (PDO) für ein untergeordnetes Gerät auf demselben Bus zu generieren. |
| FILE_CHARACTERISTIC_PNP_DEVICE | Gibt an, dass das Geräteobjekt Teil eines PnP-Stapels (Plug & Play) ist. Dieses Merkmal ist erforderlich, wenn ein Bustreiber (oder Busfiltertreiber) WMI-Unterstützung für ein Geräteobjekt registriert, das die IRP_MN_START_DEVICE-Anforderung noch nicht empfangen hat. FILE_CHARACTERISTIC_PNP_DEVICE ist auch erforderlich, wenn sich ein Funktions- oder Filtertreiber vor dem Anfügen an den Gerätestapel für WMI registriert. |
| FILE_CHARACTERISTIC_TS_DEVICE | Gibt an, dass das Geräteobjekt Teil eines Terminaldienste-Gerätestapels ist. Treiber sollten dieses Merkmal nicht festlegen. |
| FILE_CHARACTERISTIC_WEBDAV_DEVICE | Gibt an, dass ein webbasiertes WebDAV-Dateisystem (Distributed Authoring and Versioning) auf dem Gerät eingebunden ist. Treiber sollten dieses Merkmal nicht festlegen. |
| FILE_DEVICE_IS_MOUNTED | Gibt an, dass ein Dateisystem auf dem Gerät eingebunden ist. Treiber sollten dieses Merkmal nicht festlegen. |
| FILE_DEVICE_SECURE_OPEN | Weist den E/A-Manager an, den Sicherheitsdeskriptor des Geräteobjekts auf relativ geöffnete und nachgestellte Dateinamen für das Gerät anzuwenden. Weitere Informationen finden Sie im Thema Steuern des Gerätenamespacezugriffs . |
| FILE_FLOPPY_DISKETTE | Gibt an, dass es sich bei dem Gerät um ein Diskettengerät handelt. |
| FILE_READ_ONLY_DEVICE | Gibt an, dass das Gerät nicht geschrieben werden kann. |
| FILE_REMOTE_DEVICE | Gibt an, dass das Gerät remote ist. |
| FILE_REMOVABLE_MEDIA | Gibt an, dass das Speichergerät Wechselmedien unterstützt. Beachten Sie, dass dieses Merkmal auf Wechselmedien und kein Wechselmedium hinweist. Beispielsweise sollten Treiber für JAZ-Laufwerkgeräte diese Eigenschaft angeben, Treiber für PCMCIA-Flash-Datenträger jedoch nicht. |
| FILE_VIRTUAL_VOLUME | Gibt an, dass das Volume virtuell ist. Treiber sollten dieses Merkmal nicht festlegen. |
| FILE_WRITE_ONCE_MEDIA | Gibt an, dass das Gerät einmal geschriebene Medien unterstützt. Treiber legen diesen Member nicht direkt fest. Weitere Informationen zum Festlegen von Gerätemerkmalen finden Sie im Thema Angeben von Gerätemerkmalen . |
| FILE_CHARACTERISTIC_CSV | Gibt an, dass es sich bei dem Gerät um ein freigegebenes Clustervolume (CSV) handelt. |
| FILE_DEVICE_ALLOW_APPCONTAINER_TRAVERSAL | Der E/A-Manager führt normalerweise eine vollständige Sicherheitsüberprüfung für den Durchlaufzugriff auf jede geöffnete Datei durch, wenn es sich beim Client um einen App-Container handelt. Durch festlegen dieses Flags wird diese erzwungene Traverse-Zugriffsüberprüfung umgangen, wenn das Clienttoken bereits über Durchlaufberechtigungen verfügt. |
| FILE_PORTABLE_DEVICE | Gibt an, dass der zugrunde liegende Stapel das tragbare Gerät berücksichtigt. Dies wird vom Speicherstapel verwendet und bedeutet, dass sich das Gerät nicht im lokalen Computercontainer befindet und sich nicht auf einem festen Bustyp befindet. |
Vpb
Ein Zeiger auf den Volumeparameterblock (VPB), der dem Geräteobjekt zugeordnet ist. Bei Dateisystemtreibern kann der VPB eine Verbindung mit jedem unbenannten logischen Geräteobjekt bereitstellen, das eine instance eines eingebundenen Volumes darstellt. Dies ist ein undurchsichtiges Element.
DeviceExtension
Ein Zeiger auf die Geräteerweiterung. Die Struktur und der Inhalt der Geräteerweiterung sind treiberdefiniert. Die Größe wird vom Treiber bestimmt und im Aufruf von IoCreateDevice oder IoCreateDeviceSecure des Treibers angegeben. Weitere Informationen zu Geräteerweiterungen finden Sie unter Geräteerweiterungen. Dies ist ein schreibgeschütztes Element. Das Objekt, auf das das Element verweist, kann jedoch vom Treiber geändert werden.
DeviceType
Legen Sie durch IoCreateDevice und IoCreateDeviceSecure unter Verwendung des Werts fest, der für den DeviceType-Parameter dieser Routine angegeben wird. Weitere Informationen finden Sie im Thema Angeben von Gerätetypen .
StackSize
Gibt die Mindestanzahl von Stapelspeicherorten in IRPs an, die an diesen Treiber gesendet werden sollen. IoCreateDevice und IoCreateDeviceSecure legen diesen Member in neu erstellten Geräteobjekten auf 1 fest. Treiber der niedrigsten Ebene können diesen Member daher ignorieren. Der E/A-Manager legt den StackSize-Member im Geräteobjekt eines übergeordneten Treibers automatisch auf den entsprechenden Wert fest, wenn der Treiber IoAttachDevice oder IoAttachDeviceToDeviceStack aufruft. Nur ein Treiber auf höherer Ebene, der sich mit IoGetDeviceObjectPointer über einen anderen Treiber ketten lässt, muss den Wert von StackSize in seinen eigenen Geräteobjekten explizit auf 1 + den StackSize-Wert des Geräteobjekts des nächstniedrigen Treibers festlegen.
Queue
Wird intern vom E/A-Manager verwendet, um das Geräteobjekt bei Bedarf in die Warteschlange zu stellen. Dies ist ein undurchsichtiges Element.
Queue.ListEntry
Eine LIST_ENTRY Struktur, die Vorwärts- und Rückwärtszeiger für eine doppelt verknüpfte Liste enthält.
Queue.Wcb
Vom E/A-Manager verwendete Gerätekontextinformationen.
AlignmentRequirement
Gibt die Adressausrichtungsanforderung des Geräts für Datenübertragungen an. Der Wert muss einer der FILE_XXX_ALIGNMENT-Werte sein, die in Wdm.h definiert sind. Weitere Informationen finden Sie in den Themen Initialisieren eines Geräteobjekts, GetDmaAlignment und ZwQueryInformationFile .
DeviceQueue
Das Gerätewarteschlangenobjekt für das Geräteobjekt. Das Gerätewarteschlangenobjekt enthält alle IRPs, die darauf warten, vom Treiber verarbeitet zu werden, der dem Geräteobjekt zugeordnet ist. Weitere Informationen finden Sie im Thema Vom Treiber verwaltete IRP-Warteschlangen . Dies ist ein undurchsichtiges Element.
Dpc
Das DPC-Objekt (DeFerred Procedure Call) für das Geräteobjekt. Weitere Informationen finden Sie im Thema Einführung in DPC-Objekte . Dies ist ein undurchsichtiges Element.
ActiveThreadCount
Für die zukünftige Verwendung reserviert. Dies ist ein undurchsichtiges Element.
SecurityDescriptor
Gibt einen Sicherheitsdeskriptor (SECURITY_DESCRIPTOR) für das Geräteobjekt an, wenn das Geräteobjekt erstellt wird. Wenn dieses Element NULL ist, empfängt das Geräteobjekt die Standardsicherheitseinstellungen. Dies ist ein schreibgeschütztes Element, obwohl das Element über die ZwSetSecurityObject-Funktion geändert werden kann.
DeviceLock
Ein Synchronisierungsereignisobjekt, das vom E/A-Manager zugeordnet wird. Der E/A-Manager ruft sein Ereignisobjekt ab, bevor er eine Bereitstellungs- oder Einbindungsüberprüfungsanforderung an einen Dateisystemtreiber sendet. Dies ist ein undurchsichtiges Element.
SectorSize
Wenn das Geräteobjekt kein Volume darstellt, wird dieses Element auf 0 festgelegt. Wenn das Geräteobjekt ein Volume darstellt, gibt dieses Element die Sektorgröße des Volumes in Bytes an. Der E/A-Manager verwendet diesen Member, um sicherzustellen, dass alle Ausgegebenen Lesevorgänge, Schreibvorgänge und Festlegen von Dateipositionsvorgängen ordnungsgemäß ausgerichtet werden, wenn die Zwischenpufferung deaktiviert ist. Beim Erstellen des Geräteobjekts wird ein Standardmäßiger Systembyte-pro-Sektor-Wert verwendet, jedoch Dateisystemtreiber. Und seltener können Legacy- und Minifiltertreiber diesen Wert aktualisieren, der auf der Geometrie der zugrunde liegenden Volumehardware basiert, wenn eine Bereitstellung erfolgt. Andere Treiber sollten diesen Member nicht ändern.
Spare1
Ist für das System reserviert. Dies ist ein undurchsichtiges Element.
DeviceObjectExtension
Ein Zeiger auf eine Geräteobjekterweiterung, die vom E/A-Manager und PnP-Manager verwendet wird, um Informationen zum Zustand des Geräts zu speichern. Dies ist ein undurchsichtiges Element.
Reserved
Ist für das System reserviert. Dies ist ein undurchsichtiges Element.
Hinweise
Das Betriebssystem stellt Geräte nach Geräteobjekten dar. Weitere Informationen finden Sie im Thema Geräteobjekte und Gerätestapel .
Treiber erstellen Geräteobjekte mithilfe der Routinen IoCreateDevice und IoCreateDeviceSecure . Weitere Informationen zum Erstellen von Geräteobjekten finden Sie unter Erstellen eines Geräteobjekts.
Ein Geräteobjekt ist teilweise undurchsichtig. Treiber legen Elemente des Geräteobjekts nicht direkt fest, es sei denn, es ist anders dokumentiert. Weitere Informationen zu den Membern, die Treiber direkt ändern können, finden Sie unter Initialisieren eines Geräteobjekts. Informationen zu anderen Geräteobjekteigenschaften finden Sie unter Eigenschaften von Geräteobjekten.
Undurchsichtige Member innerhalb eines Geräteobjekts müssen als nicht zugänglich betrachtet werden. Treiber, die Abhängigkeiten von Objektmemberspeicherorten oder Zugriff auf undurchsichtige Member aufweisen, bleiben möglicherweise nicht portabel und interoperabel mit anderen Treibern im Laufe der Zeit.
Der vom System bereitgestellte Videoporttreiber richtet die Felder der Geräteobjekte ein, die er im Auftrag von Video-Miniporttreibern erstellt.
Der vom System bereitgestellte SCSI-Porttreiber richtet die Felder der Geräteobjekte ein, die er im Auftrag von SCSI-Miniporttreibern erstellt.
Die systemseitig bereitgestellte NDIS-Bibliothek richtet die Felder der Geräteobjekte ein, die sie im Auftrag von NDIS-Miniporttreibern erstellt.
Anforderungen
| Anforderung | Wert |
|---|---|
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |