Verwenden von Steuerelementgeräteobjekten

Ein Steuerelementgeräteobjekt ist ein Frameworkgeräteobjekt, das Plug & Play (PnP) oder Energieverwaltungsvorgänge nicht unterstützt. Treiber können Steuergeräteobjekte verwenden, um nur softwarebasierte virtuelle Geräte oder ältere Hardwaregeräte darzustellen (d. a. Geräte, die keine PnP- oder Energieverwaltungsfunktionen bieten).

Ein Treiber, der ein Steuerelementgerätobjekt erstellt, erstellt in der Regel auch eine symbolische Verknüpfung für das Geräteobjekt. Anwendungen können E/A-Anforderungen an das Steuerelementgerätobjekt senden, indem sie den symbolischen Linknamen an ein API-Element übergeben, z. B. die Microsoft Win32 CreateFile-Funktion .

Das Framework fügt keine Geräteobjekte der Steuerung an einen Gerätestapel an. Wenn eine Anwendung eine E/A-Anforderung an ein Steuerelementgerätobjekt sendet, übermittelt der E/A-Manager die Anforderung daher direkt an den Treiber, der das Steuerelementgerätobjekt erstellt hat, und nicht an den Treiber am oberen Rand des Stapels. (Ein zusätzlicher Treiber kann jedoch IoAttachDevice aufrufen, um ein Geräteobjekt über dem Steuerelementgerätobjekt anzufügen. In diesem Fall empfängt der zusätzliche Treiber zuerst die E/A-Anforderung.)

Verwendung von Steuerelementgeräteobjekten

Zwei typische Verwendungsmöglichkeiten für Steuergeräte sind:

1. Ein Filtertreiber für ein PnP-Gerät, wenn der Treiber eine Reihe benutzerdefinierter E/A-Steuercodes für anwendungen unterstützt.

   Wenn eine Anwendung versucht hat, die benutzerdefinierten E/A-Steuercodes an den Anfang des Treiberstapels zu senden (z. B. mithilfe des symbolischen Linknamens einer Geräteschnittstelle), schlägt ein Treiber über dem Filtertreiber möglicherweise die E/A-Anforderung fehl, wenn der Treiber die benutzerdefinierten E/A-Steuerungscodes nicht erkannt hat. Um dieses Problem zu vermeiden, kann der Filtertreiber ein Steuerelementgerätobjekt erstellen. Anwendungen können den symbolischen Linknamen des Steuerelementgeräteobjekts verwenden, um E/A-Steuerungscodes direkt an den Filtertreiber zu senden.

   (Beachten Sie, dass eine bessere Möglichkeit für den Filtertreiber, das Problem zu vermeiden, darin besteht, als Bustreiber zu fungieren und untergeordnete Geräte aufzulisten , die im Rohmodus arbeiten. Anders ausgedrückt: Für jedes Gerät, das der Filtertreiber unterstützt, kann der Treiber ein physisches Geräteobjekt (PDO) erstellen, für das kein Funktionstreiber erforderlich ist. Der Treiber ruft WdfPdoInitAssignRawDevice und WdfDeviceInitAssignName für jedes dieser Geräte auf, und die Anwendung kann ein Gerät anhand des Namens identifizieren, wenn sie einen benutzerdefinierten E/A-Steuerungscode sendet.)

2. Ein Treiber für ein Gerät, das PnP nicht unterstützt.

   Ein solcher Treiber muss Steuergeräteobjekte verwenden, da sich die Geräteobjekte für solche Geräte nicht in einem Gerätestapel befinden und keine PnP-Funktionen bereitstellen. Weitere Informationen zur Unterstützung von Nicht-PnP-Geräten finden Sie unter Verwenden Kernel-Mode Driver Frameworks mit Nicht-PnP-Treibern.

Erstellen eines Steuerelementgeräteobjekts

Um ein Steuerelementgeräteobjekt zu erstellen, muss ein Treiber Folgendes ausführen:

1. Rufen Sie WdfControlDeviceInitAllocate auf, um eine WDFDEVICE_INIT-Struktur abzurufen.

2. Rufen Sie bei Bedarf Objektinitialisierungsmethoden auf, um die WDFDEVICE_INIT Struktur zu initialisieren. Der Treiber kann nur die folgenden Initialisierungsmethoden aufrufen:

   • WdfControlDeviceInitSetShutdownNotification
   • WdfDeviceInitAssignName
   • WdfDeviceInitAssignSDDLString
   • WdfDeviceInitAssignWdmIrpPreprocessCallback
   • WdfDeviceInitSetCharacteristics
   • WdfDeviceInitSetDeviceClass
   • WdfDeviceInitSetExclusive
   • WdfDeviceInitSetFileObjectConfig
   • WdfDeviceInitSetIoInCallerContextCallback
   • WdfDeviceInitSetIoType
   • WdfDeviceInitSetRequestAttributes

3. Rufen Sie WdfDeviceCreate auf, die den Inhalt der WDFDEVICE_INIT-Struktur verwendet, um ein Framework-Geräteobjekt zu erstellen.

4. Führen Sie die folgenden Initialisierungsvorgänge aus:

   • Erstellen Sie bei Bedarf eine Standard-E/A-Warteschlange für das Gerät.
   • Rufen Sie bei Bedarf WdfDeviceConfigureRequestDispatching auf.
   • Rufen Sie WdfDeviceCreateSymbolicLink auf, um einen symbolischen Linknamen zu erstellen, den Anwendungen für den Zugriff auf das Steuerungsgerät verwenden können.

5. Rufen Sie WdfControlFinishInitializing auf.

Regeln für die Verwendung von Steuerelementgeräteobjekten

Treiber, die Geräteobjekte erstellen, müssen den folgenden Regeln entsprechen:

• Treiber können das Handle des Steuerelementgeräteobjekts nicht an Frameworkmethoden übergeben, die untergeordnete Geräte auflisten.

• Treiber können das Handle des Steuerelementgeräteobjekts nicht an Frameworkmethoden übergeben, die Geräteschnittstellen unterstützen.

• Treiber können E/ A-Warteschlangen erstellen und Anforderungshandler für die Warteschlangen registrieren, aber das Framework lässt die Energieverwaltung der Warteschlangen nicht zu.

• Treiber können Dateiobjekte für Geräteobjekte erstellen.

Benennen eines Steuerelementgeräteobjekts

Alle Geräteobjekte des Steuerelements müssen benannt werden. In der Regel ruft Ihr Treiber WdfDeviceInitAssignName auf, um einen Gerätenamen zuzuweisen, und ruft dann WdfDeviceCreateSymbolicLink auf, um einen symbolischen Linknamen zu erstellen, den Anwendungen für den Zugriff auf das Objekt verwenden können.

Wenn Ihr Treiber WdfDeviceInitAssignName nicht aufruft, um einen Gerätenamen zuzuweisen, generiert das Framework automatisch einen Namen für Steuerungsgeräte . Ihr Treiber kann WdfDeviceCreateSymbolicLink jedoch nicht aufrufen.

Ihr Treiber kann WdfDeviceInitSetDeviceClass aufrufen, um eine Gerätesetupklasse für ein Steuergerät anzugeben. Die Geräteeinrichtungsklasse identifiziert einen Abschnitt der Registrierung, der vom Administrator bereitgestellte Informationen zu Geräten enthält, die zur Setupklasse gehören. Weitere Informationen zum Aufrufen von WdfDeviceInitSetDeviceClass finden Sie unter Steuern des Gerätezugriffs in Framework-Based Drivers.

Empfangen einer Benachrichtigung über das Herunterfahren des Systems

Da Steuergeräteobjekte PnP nicht unterstützen, kann Ihr Treiber keine Rückruffunktionen registrieren, die den Treiber darüber informieren, wenn sich der Energiezustand eines Geräts ändert. Der Treiber kann jedoch WdfControlDeviceInitSetShutdownNotification aufrufen, um eine EvtDeviceShutdownNotification-Rückruffunktion zu registrieren. Diese Rückruffunktion informiert den Treiber, wenn das System seine Leistung verlieren wird.

Löschen eines Steuerelementgeräteobjekts

Einige Treiber müssen ihre Steuergeräteobjekte löschen, bevor der Treiber entladen wird, wie folgt:

• Wenn Ihr Treiber Steuergeräteobjekte erstellt (die keine PnP- oder Energieverwaltung unterstützen), und wenn der Treiber auch Frameworkgeräteobjekte erstellt, die PnP und die Energieverwaltung unterstützen, muss der Treiber schließlich WdfObjectDelete unter IRQL = PASSIVE_LEVEL aufrufen, um die Objekte des Steuergeräts zu löschen.

  Wenn der Treiber beide Arten von Geräteobjekten erstellt, kann das Betriebssystem Den Treiber erst entladen, wenn der Treiber die Geräteobjekte gelöscht hat.

  Der Treiber darf die Steuerelementgeräteobjekte jedoch erst löschen, nachdem das Framework die anderen Geräteobjekte gelöscht hat. Um zu bestimmen, wann das Framework die anderen Geräteobjekte gelöscht hat, sollte Ihr Treiber EvtCleanupCallback-Funktionen für diese Objekte bereitstellen.

• Wenn Ihr Treiber Steuergeräteobjekte erstellt, aber keine Frameworkgeräteobjekte erstellt, die die PnP- und Energieverwaltung unterstützen, muss der Treiber die Steuergeräteobjekte nicht löschen.

  In diesem Fall löscht das Framework die Objekte des Steuerelementgeräts, nachdem die Rückruffunktion EvtDriverUnload des Treibers zurückgegeben wird.