DiInstallDevice-Funktion (newdev.h)

Artikel
03/04/2024

Die DiInstallDevice-Funktion installiert einen angegebenen Treiber, der im Treiberspeicher auf einem angegebenen Gerät vorinstalliert ist, das im System vorhanden ist.

Syntax

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

Parameter

[in, optional] hwndParent

Ein Handle für das Fenster auf oberster Ebene, das DiInstallDevice verwendet, um alle Benutzeroberflächenkomponenten anzuzeigen, die der Installation des Geräts zugeordnet sind. Dieser Parameter ist optional und kann auf NULL festgelegt werden.

[in] DeviceInfoSet

Ein Handle für einen Geräteinformationssatz , der ein Geräteinformationselement enthält, das das angegebene Gerät darstellt.

[in] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die das angegebene Gerät im angegebenen Geräteinformationssatz darstellt.

[in, optional] DriverInfoData

Ein Zeiger auf eine SP_DRVINFO_DATA Struktur, die den Treiber angibt, der auf dem angegebenen Gerät installiert werden soll. Dieser Parameter ist optional und kann auf NULL festgelegt werden. Wenn dieser Parameter NULL ist, durchsucht DiInstallDevice die treiber, die im Treiberspeicher vorinstalliert sind, nach dem Treiber, der am besten mit dem angegebenen Gerät übereinstimmt, und installiert den Treiber, falls einer gefunden wird, auf dem angegebenen Gerät.

[in] Flags

Ein Wert vom Typ DWORD , der null oder das folgende Flag angibt:

DIIDFLAG_SHOWSEARCHUI

Wenn der Aufrufer keinen Treiber angibt (DriverInfoData ist auf NULL festgelegt) und DiInstallDevice keinen vorinstallierten Treiber findet, der dem angegebenen Gerät entspricht. Stattdessen zeigt DiInstallDevice den Assistenten Neue Hardware gefunden für das Gerät an.

DIIDFLAG_NOFINISHINSTALLUI

DiInstallDevice startet weder Seiten des Assistenten für die Fertiginstallation noch Aktionen zum Abschließen der Installation. Der Aufrufer von DiInstallDevice muss diese Vorgänge starten. Der Aufrufer sollte dieses Flag nur angeben, wenn der Aufrufer erfordert, dass Seiten des Assistenten für die Fertiginstallation im Kontext einer vom Aufrufer bereitgestellten Benutzeroberfläche aufgerufen werden.

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice versucht, einen NULL-Treiber auf dem angegebenen Gerät zu installieren. Wenn dieses Flag festgelegt ist, verwendet DiInstallDevice nicht den DriverInfoData-Parameter . DiInstallDevice entfernt alle Geräteeinstellungen. Wenn das Gerät nicht im rohen Modus ausgeführt werden kann, legt die Funktion die status des Geräts auf CM_PROB_FAILED_INSTALL fest. Wenn DiInstallDevice keinen NULL-Treiber installieren kann, entspricht der resultierende Zustand des Geräts dem, wenn das Gerät zum ersten Mal mit dem Computer verbunden war und Windows keinen Treiber für das Gerät gefunden hat.

DIIDFLAG_INSTALLCOPYINFDRIVERS

Jede zusätzliche INF-Datei, die über eine CopyINF-Direktive angegeben wird, wird auf jedem Gerät installiert, für das sie gilt. Ein Fehler bei der Installation eines zusätzlichen INF führt nicht dazu, dass die Installation des primären INF fehlschlägt.

[out, optional] NeedReboot

Ein Zeiger auf einen Wert vom Typ BOOL , den DiInstallDevice festlegt, um anzugeben, ob ein Systemneustart erforderlich ist, um die Installation abzuschließen. Dieser Parameter ist optional und kann auf NULL festgelegt werden. Wenn dieser Parameter angegeben wird und ein Systemneustart erforderlich ist, um die Installation abzuschließen, legt DiInstallDevice den Wert auf TRUE fest. In diesem Fall ist der Aufrufer für den Neustart des Systems verantwortlich. Wenn dieser Parameter angegeben wird und kein Systemneustart erforderlich ist, legt DiInstallDevice diesen Parameter auf FALSE fest. Wenn dieser Parameter NULL ist und ein Systemneustart erforderlich ist, um die Installation abzuschließen, zeigt DiInstallDevice ein Dialogfeld zum Neustart des Systems an.

Rückgabewert

DiInstallDevice gibt TRUE zurück, wenn die Funktion den angegebenen Treiber erfolgreich auf dem angegebenen Gerät installiert hat. Andernfalls gibt DiInstallDeviceFALSE zurück, und der protokollierte Fehler kann durch einen Aufruf von GetLastError abgerufen werden. Einige der häufigeren Fehlerwerte, die GetLastError möglicherweise zurückgibt, sind wie folgt:

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Aufrufer verfügt nicht über Administratorrechte. Windows Vista und Windows Server 2008 erfordern standardmäßig, dass ein aufrufende Prozess über Administratorrechte verfügt, um einen Treiber auf einem Gerät zu installieren.
ERROR_INVALID_FLAGS	Der für Flags angegebene Wert ist nicht 0 oder ein bitweiser OR der gültigen Flags.
ERROR_IN_WOW64	Die aufrufende Anwendung ist eine 32-Bit-Anwendung, die versucht, in einer 64-Bit-Umgebung auszuführen, was nicht zulässig ist. Weitere Informationen finden Sie unter Installieren von Geräten auf 64-Bit-Systemen.

Hinweise

Rufen Sie DiInstallDevice nur auf, wenn ein bestimmter Treiber auf einem bestimmten Gerät installiert werden muss. Verwenden Sie andernfalls UpdateDriverForPlugAndPlayDevices oder DiInstallDriver , um einen Treiber für ein Gerät zu installieren. Weitere Informationen dazu, welche dieser Funktionen zum Installieren eines Treibers auf einem Gerät aufgerufen werden sollen, finden Sie unter SetupAPI Functions that Simplify Driver Installation.

Vor dem Aufruf von DiInstallDevice muss der Aufrufer eine SP_DEVINFO_DATA-Struktur abrufen, um das Gerät anzugeben, und optional eine SP_DRVINFO_DATA-Struktur , um einen Treiber für das Gerät anzugeben.

Führen Sie eine der folgenden Schritte 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 abzurufen:

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.
- - ODER -
Rufen Sie SetupDiOpenDeviceInfo 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.

Um eine SP_DRVINFO_DATA Struktur für einen ausgewählten Treiber abzurufen, rufen Sie SetupDiBuildDriverInfoList auf, um eine Liste der Treiber für das Gerät zu erstellen, und rufen Sie dann SetupDiEnumDriverInfo auf, um die Elemente der Treiberliste für das Gerät aufzulisten. Für jeden aufgezählten Treiber ruft SetupDiEnumDriverInfo eine SP_DRVINFO_DATA-Struktur ab, die den Treiber identifiziert. SetupDiGetDriverInfoDetail kann auch aufgerufen werden, um zusätzliche Details zu einem aufgezählten Treiber abzurufen.

Im Allgemeinen sollte eine Installationsanwendung NeedReboot auf NULL festlegen. Dadurch wird sichergestellt, dass DiInstallDevice den Benutzer auffordert, das System neu zu starten, wenn ein Neustart erforderlich ist, um die Installation abzuschließen. Eine Anwendung sollte einen NeedReboot-Zeiger nur in den folgenden Fällen bereitstellen:

Die Anwendung muss DiInstallDevice mehrmals aufrufen, um eine Installation abzuschließen. In diesem Fall sollte die Anwendung aufzeichnen, ob ein TRUENeedReboot-Wert von einem der Aufrufe von DiInstallDevice zurückgegeben wird. Wenn dies der Fall ist, sollte der Benutzer aufgefordert werden, das System nach dem letzten Aufruf von DiInstallDevice neu zu starten.
Die Anwendung muss die erforderlichen Vorgänge ausführen, mit Ausnahme des Aufrufens von DiInstallDevice, bevor ein Systemneustart erfolgen sollte. 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-Member der SP_DEVINSTALL_PARAMS-Struktur für ein Gerät festlegen.

Anforderungen

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