DiUninstallDevice-Funktion (newdev.h)

Artikel
02/29/2024

Die DiUninstallDevice-Funktion deinstalliert ein Gerät und entfernt dessen Geräteknoten (devnode) aus dem System. Dies unterscheidet sich von der Verwendung von SetupDiCallClassInstaller mit dem DIF_REMOVE Code, da versucht wird, den Geräteknoten zusätzlich zu untergeordneten Devnodes zu deinstallieren, die zum Zeitpunkt des Aufrufs vorhanden sind.

Vor dem Windows 8 werden alle untergeordneten Geräte, die zum Zeitpunkt des Anrufs nicht vorhanden sind, nicht deinstalliert. Ab Windows 8 werden jedoch alle untergeordneten Geräte deinstalliert, die zum Zeitpunkt des Aufrufs nicht vorhanden sind.

Syntax

BOOL DiUninstallDevice(
  [in]            HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Parameter

[in] hwndParent

Ein Handle für das Fenster der obersten Ebene, das verwendet wird, um alle Benutzeroberflächenkomponenten anzuzeigen, die der Deinstallationsanforderung für das Gerät zugeordnet sind. Dieser Parameter ist optional und kann auf NULL festgelegt werden.

[in] DeviceInfoSet

Ein Handle für den Geräteinformationssatz , der ein Geräteinformationselement enthält. Dieses Element stellt das Gerät dar, das über diesen Aufruf deinstalliert werden soll.

[in] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die das angegebene Gerät im angegebenen Geräteinformationssatz darstellt, für den die Deinstallationsanforderung ausgeführt wird.

[in] Flags

Ein Wert vom Typ DWORD, der Geräteentinstallationsflags angibt. Ab Windows 7 muss dieser Parameter auf Null festgelegt werden.

[out, optional] NeedReboot

Ein Zeiger auf einen Wert vom Typ BOOL, den DiUninstallDevice festlegt, um anzugeben, ob ein Systemneustart erforderlich ist, um die Deinstallationsanforderung des Geräts abzuschließen. Dieser Parameter ist optional und kann auf NULL festgelegt werden.

Wenn der Parameter angegeben wird und ein Systemneustart erforderlich ist, legt DiUninstallDevice den Wert auf TRUE fest. In diesem Fall muss die Anwendung den Benutzer auffordern, das System neu zu starten. Wenn dieser Parameter angegeben wird und kein Neustart des Systems erforderlich ist, legt DiUninstallDevice den Wert auf FALSE fest.

Wenn dieser Parameter NULL ist und ein Systemneustart erforderlich ist, um die Deinstallation des Geräts abzuschließen, zeigt DiUninstallDevice ein Dialogfeld zum Neustart des Systems an.

Weitere Informationen zu diesem Parameter finden Sie im Abschnitt Hinweise .

Rückgabewert

DiUninstallDevice gibt TRUE zurück, wenn die Funktion den Geräteknoten der obersten Ebene, der das Gerät darstellt, erfolgreich deinstalliert hat. Andernfalls gibt DiUninstallDeviceFALSE zurück, und der protokollierte Fehler kann durch einen Aufruf von GetLastError abgerufen werden. Die folgende Liste zeigt einige der häufigeren Fehlerwerte, die GetLastError möglicherweise für diese API zurückgibt:

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Aufrufer verfügt nicht über Administratorrechte. Standardmäßig erfordert Windows, dass der Aufrufer über Administratorrechte zum Deinstallieren von Geräten verfügt.
ERROR_INVALID_FLAGS	Der für den Flags-Parameter angegebene Wert ist nicht gleich 0.

Hinweis Der Rückgabewert gibt nicht an, dass die Entfernung aller untergeordneten Devnodes erfolgreich war oder fehlgeschlagen ist. Ab Windows Vista, Informationen über den status des Entfernens von untergeordneten devnodes sind in der Setupapi.dev.log Datei verfügbar. Weitere Informationen zu dieser Datei finden Sie unter SetupAPI-Textprotokolle.

Hinweise

DiUninstallDevice führt dieselbe Funktion wie SetupDiCallClassInstaller aus, wenn sie mit dem DIF_REMOVE-Code verwendet wird. Der Hauptunterschied besteht darin, dass auch untergeordnete Devnodes für das Gerät der obersten Ebene gelöscht werden. DiUninstallDevice gibt nur dann einen Fehler zurück, wenn der Geräteknoten der obersten Ebene nicht deinstalliert werden konnte. Dies entspricht dem Verhalten von SetupDiCallClassInstaller , wenn er mit dem DIF_REMOVE-Code verwendet wird. Ausführliche Informationen darüber, ob die Deinstallation des untergeordneten Devnode-Elements erfolgreich war, finden Sie in der datei Setupapi.dev.log.

Das zu deinstallierende Gerät wird durch Bereitstellen eines Geräteinformationssatzes angegeben, der das referenzierte Gerät und eine SP_DEVINFO_DATA Struktur für das jeweilige Gerät enthält. Diese werden in den Parametern DeviceInfoSet und DeviceInfoData bereitgestellt.

Führen Sie eine der folgenden Aufgaben aus, um einen Geräteinformationssatz zu erstellen, der das angegebene Gerät enthält, und eine SP_DEVINFO_DATA Struktur für das Gerät zu erhalten:

Rufen Sie SetupDiGetClassDevs auf, um einen Geräteinformationssatz abzurufen, der das Gerät enthält, und rufen Sie dann SetupDiEnumDeviceInfo auf, um die Geräte im Geräteinformationssatz aufzulisten. Bei jedem Aufruf gibt SetupDiEnumDeviceInfo eine SP_DEVINFO_DATA-Struktur zurück, die das aufgezählte Gerät im Geräteinformationssatz darstellt.
Rufen Sie SetupDiGetDeviceProperty auf, und geben Sie die SP_DEVINFO_DATA Struktur an, die von SetupDiEnumDeviceInfo zurückgegeben wird, um spezifische Informationen zum aufgezählten Gerät zu erhalten.
Rufen Sie SetupDiEnumDeviceInfo auf, um dem Geräteinformationssatz ein Gerät mit einem bekannten Gerät instance ID hinzuzufügen. SetupDiOpenDeviceInfo gibt eine SP_DEVINFO_DATA-Struktur zurück, die das Gerät im Geräteinformationssatz darstellt.

Falls für die Deinstallationsanforderung des Geräts ein Neustart des Computers erforderlich ist, fordert DiUninstallDevice den Benutzer auf, das System neu zu starten, wenn der NeedReboot-Parameter auf NULL festgelegt ist. Wenn es ein Benutzeroberflächenfenster gibt, das die Anwendung verwendet, sollte der hwndParent-Parameter auf den Wert des Handle dieses Fensters festgelegt werden.

Wenn die Anwendung jedoch die Benachrichtigung über einen erforderlichen Systemneustart verwaltet, muss sie den NeedReboot-Parameter auf einen Wert ohne NULL festlegen. DiUninstallDevice legt den NeedReboot-Parameter auf TRUE oder FALSE fest, je nachdem, ob ein Systemneustart erforderlich ist.

Die folgende Liste zeigt Beispiele dafür, warum die Anwendung den Systemneustart verwalten kann:

Die Anwendung muss mehrere Geräte deinstallieren. Nachdem alle Geräte deinstalliert wurden, sollte die Anwendung den Benutzer auffordern, das System neu zu starten, wenn ein Aufruf von DiUninstallDevicetrue im NeedReboot-Parameter zurückgegeben hat.
Die Anwendung erfordert einige andere Vorgänge, bevor das System neu gestartet werden kann. Wenn ein Systemneustart erforderlich ist, sollte die Anwendung die erforderlichen Vorgänge abschließen und den Benutzer dann auffordern, das System neu zu starten.
Die Anwendung ist ein Klasseninstallationsprogramm. In diesem Fall sollte das Klasseninstallationsprogramm das DI_NEEDREBOOT-Flag im Flags-Element der SP_DEVINSTALL_PARAMS-Struktur für ein Gerät festlegen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 7 und späteren Windows-Versionen.
Zielplattform	Desktop
Kopfzeile	newdev.h (include Newdev.h)
Bibliothek	Newdev.lib
DLL	Newdev.dll