Verwenden von Geräteschnittstellen in UMDF-Treibern

  • Artikel

Warnung

UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden.

Die archivierten UMDF 1-Beispiele finden Sie im Treiberbeispielupdate Windows 11, Version 22H2 – Mai 2022.

Weitere Informationen finden Sie unter Erste Schritte mit UMDF.

Eine Geräteschnittstelle ist eine symbolische Verknüpfung mit einem PnP-Gerät (Plug & Play), das eine Anwendung für den Zugriff auf das Gerät verwenden kann. Eine Anwendung im Benutzermodus kann den symbolischen Linknamen der Schnittstelle an ein API-Element übergeben, z. B. an die CreateFile-Funktion von Microsoft Win32. Um den symbolischen Linknamen einer Geräteschnittstelle abzurufen, kann die Benutzermodusanwendung SetupDi-Funktionen aufrufen. Weitere Informationen zu SetupDi-Funktionen finden Sie unter SetupDi Device Interface Functions.

Jede Geräteschnittstelle gehört zu einer Geräteschnittstellenklasse. Beispielsweise kann ein Treiberstapel für ein CD-ROM-Gerät eine Schnittstelle bereitstellen, die zur GUID_DEVINTERFACE_CDROM-Klasse gehört. Einer der Treiber des CD-ROM-Geräts registriert eine instance der GUID_DEVINTERFACE_CDROM-Klasse, um das System und die Anwendungen darüber zu informieren, dass ein CD-ROM-Gerät verfügbar ist. Weitere Informationen zu Geräteschnittstellenklassen finden Sie unter Einführung in Geräteschnittstellen.

Registrieren einer Geräteschnittstelle

Um eine instance einer Geräteschnittstellenklasse zu registrieren, kann ein UMDF-basierter Treiber IWDFDevice::CreateDeviceInterface in seiner IDriverEntry::OnDeviceAdd-Rückruffunktion aufrufen. Wenn der Treiber mehrere Instanzen der Schnittstelle unterstützt, kann er jeder instance eine eindeutige Verweiszeichenfolge zuweisen.

Aktivieren und Deaktivieren einer Geräteschnittstelle

Wenn die Erstellung erfolgreich ist, aktiviert und deaktiviert das Framework die Schnittstelle basierend auf dem PnP-Zustand des Geräts automatisch.

Darüber hinaus kann ein Treiber eine Geräteschnittstelle bei Bedarf deaktivieren und erneut aktivieren. Wenn ein Treiber beispielsweise feststellt, dass sein Gerät nicht mehr reagiert, kann der Treiber IWDFDevice::AssignDeviceInterfaceState aufrufen, um die Schnittstellen des Geräts zu deaktivieren und zu verhindern, dass Anwendungen neue Handles für die Schnittstelle abrufen. (Vorhandene Handles für die Schnittstelle sind nicht betroffen.) Wenn das Gerät später verfügbar wird, kann der Treiber IWDFDevice::AssignDeviceInterfaceState erneut aufrufen, um die Schnittstellen erneut zu aktivieren.

Empfangen von Anforderungen für den Zugriff auf eine Geräteschnittstelle

Wenn eine Anwendung Zugriff auf die Geräteschnittstelle eines Treibers anfordert, ruft das Framework die IQueueCallbackCreate::OnCreateFile-Rückruffunktion des Treibers auf. Der Treiber kann IWDFFile::RetrieveFileName aufrufen, um den Namen des Geräts oder der Datei abzurufen, auf das die Anwendung zugreift. Wenn der Treiber bei der Registrierung der Geräteschnittstelle eine Verweiszeichenfolge angegeben hat, schließt das Betriebssystem die Verweiszeichenfolge in die Datei oder den Gerätenamen ein, die IWDFFile::RetrieveFileName zurückgibt.

Erstellen von Geräteereignissen

Ihr UMDF-basierter Treiber kann gerätespezifische, benutzerdefinierte Ereignisse (als Geräteereignisse bezeichnet) erstellen, indem IWDFDevice::P ostEvent aufgerufen wird. Ein Treiber, der für die Verwendung einer der Geräteschnittstellen registriert ist, kann Benachrichtigungen über die benutzerdefinierten Ereignisse eines Geräts empfangen. UMDF-basierte Treiber erhalten solche Benachrichtigungen, indem sie eine IRemoteInterfaceCallbackEvent::OnRemoteInterfaceEvent-Rückruffunktion bereitstellen.

Benutzerdefinierte Ereignisse sind für das Gerät eindeutig. Sowohl der Entwickler des Treibers, der das Ereignis erstellt, als auch der Entwickler des Treibers, der das Ereignis empfängt, muss die Bedeutung des Ereignisses verstehen.

Zugreifen auf die Geräteschnittstelle eines anderen Treibers

Wenn Der UMDF-basierte Treiber E/A-Anforderungen an eine Geräteschnittstelle sendet, die von einem anderen Treiber bereitgestellt wird, können Sie ein Remote-E/A-Ziel erstellen, das die Geräteschnittstelle darstellt.

Zunächst muss sich Ihr Treiber registrieren, um eine Benachrichtigung zu erhalten, wenn eine Geräteschnittstelle verfügbar ist. Führen Sie die folgenden Schritte durch:

  1. Wenn Ihr Treiber IWDFDriver::CreateDevice aufruft, kann der Treiber eine IPnpCallbackRemoteInterfaceNotification-Schnittstelle bereitstellen. Die IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival-Rückruffunktion dieser Schnittstelle informiert Ihren Treiber, wenn Geräteschnittstellen verfügbar sind.

  2. Nachdem Ihr Treiber IWDFDriver::CreateDevice aufgerufen hat, kann er IWDFDevice2::RegisterRemoteInterfaceNotification für jede Vom Treiber verwendete Geräteschnittstelle aufrufen.

Anschließend ruft das Framework die IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival-Rückruffunktion des Treibers auf, wenn eine angegebene Geräteschnittstelle verfügbar wird. Die Rückruffunktion kann IWDFRemoteInterfaceInitialize::GetInterfaceGuid und IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink aufrufen, um zu bestimmen, welche Geräteschnittstelle eingetroffen ist.

Die IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival-Rückruffunktion Ihres Treibers sollte in der Regel die folgenden Aktionen ausführen:

  1. Rufen Sie IWDFDevice2::CreateRemoteInterface auf, um ein Remoteschnittstellenobjekt zu erstellen, und stellen Sie optional die Schnittstellen IRemoteInterfaceCallbackEvent und IRemoteInterfaceCallbackRemoval bereit.

  2. Rufen Sie IWDFDevice2::CreateRemoteTarget auf, um ein Remotezielobjekt zu erstellen und optional eine IRemoteTargetCallbackRemoval-Schnittstelle bereitzustellen.

  3. Rufen Sie IWDFRemoteTarget::OpenRemoteInterface auf, um die Geräteschnittstelle mit dem Remoteziel zu verbinden.

    Wenn es sich bei der Geräteschnittstelle um eine Schnittstelle handelt, die der SWENUM-Softwaregeräte-Enumerator erstellt, muss Ihr Treiber OpenRemoteInterface aus einem Arbeitselement aufrufen. (Siehe z. B. die QueueUserWorkItem-Funktion im Windows SDK.)

Jetzt kann der Treiber E/A-Anforderungen formatieren und an das Remote-E/A-Ziel senden.

Zusätzlich zur IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival-Rückruffunktion kann ein UMDF-basierter Treiber zwei zusätzliche Rückruffunktionen bereitstellen, um Benachrichtigungen über Geräteschnittstellenereignisse zu empfangen: