IDriverEntry::OnDeviceAdd-Methode (wudfddi.h)

Artikel
03/01/2024

[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. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die OnDeviceAdd-Methode fügt einem System ein neues Gerät hinzu.

Syntax

HRESULT OnDeviceAdd(
  [in] IWDFDriver           *pWdfDriver,
  [in] IWDFDeviceInitialize *pWdfDeviceInit
);

Parameter

[in] pWdfDriver

Ein Zeiger auf die IWDFDriver-Schnittstelle für das übergeordnete Treiberobjekt, zu dem das neue Gerät gehört.

[in] pWdfDeviceInit

Ein Zeiger auf die IWDFDeviceInitialize-Schnittstelle , die der Treiber zum Initialisieren des neu erstellten Geräts verwendet.

Rückgabewert

OnDeviceAdd gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode einen der Fehlercodes zurück, die in Winerror.h definiert sind. Der Treiber sollte nur S_OK zurückgeben, wenn er erfolgreich die IWDFDriver::CreateDevice-Methode aufgerufen hat , um das Framework-Geräteobjekt zu erstellen. Wenn der Treiber einen Fehlercode zurückgibt, löscht UMDF den gesamten Gerätestapel unabhängig davon, ob es sich bei dem Treiber um einen Filtertreiber oder einen Funktionstreiber handelt.

Hinweise

Für jedes Gerät, das im Treiberhostprozess geladen wird, wird ein neues Geräteobjekt erstellt. Wenn ein neues Gerät im System eintrifft, ruft das Framework OnDeviceAdd auf, um den Treiber über die Ankunft zu benachrichtigen, und übergibt die IWDFDriver - und IWDFDeviceInitialize-Schnittstellen im Aufruf. Der Treiber kann die IWDFDeviceInitialize::RetrieveDevicePropertyStore-Methode aufrufen, um die Geräteinformationen abzufragen, die bei der Geräteinstallation bereitgestellt werden. Der Treiber muss die IWDFDriver::CreateDevice-Methode aufrufen, um das Gerät zu konfigurieren und zu erstellen. Wenn der Treiber IWDFDriver::CreateDevice nicht erfolgreich aufruft , bevor er S_OK zurückgibt, ermittelt UMDF, dass das Verhalten des Treibers falsch ist, und beendet den Hostprozess.

Jeder Treiber, dessen OnDeviceAdd-Methode S_OK zurückgibt, erhält anschließend einen Aufruf der IPnpCallbackHardware::OnReleaseHardware-Methode , wenn die UMDF den Gerätestapel abreißt.

Verwenden Sie nicht die IWDFDeviceInitialize-Schnittstelle , auf die der pWdfDeviceInit-Parameter zeigt, nachdem der Treiber IWDFDriver::CreateDevice aufgerufen hat.

Weitere Informationen finden Sie unter Hinzufügen eines Geräts.