Freigeben über

DiInstallDriverW-Funktion (newdev.h)

  • Artikel

Die DiInstallDriver-Funktion installiert einen Treiber im Treiberspeicher vor und installiert den Treiber dann auf Geräten, die im System vorhanden sind, das vom Treiber unterstützt wird.

Syntax

BOOL DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR InfPath,
  [in]            DWORD   Flags,
  [out, optional] PBOOL   NeedReboot
);

Parameter

[in, optional] hwndParent

Ein Handle für das Fenster der obersten Ebene, das DiInstallDriver 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] InfPath

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die den vollqualifizierten Pfad der INF-Datei für das Treiberpaket angibt.

[in] Flags

Ein Wert vom Typ DWORD, der null oder eine Kombination aus einem oder mehreren Flags angibt, wie hier beschrieben (Flags wird in der Regel auf 0 festgelegt).

Wenn Flags null ist, installiert DiInstallDriver den angegebenen Treiber nur dann auf einem Gerät, wenn der Treiber besser zu einem Gerät passt als der Treiber, der derzeit auf einem Gerät installiert ist. Informationen dazu, wie Windows einen Treiber für ein Gerät auswählt, finden Sie unter So wählt Windows Treiber aus.

Wenn Flags DIIRFLAG_FORCE_INF enthält, installiert DiInstallDriver den angegebenen Treiber auf einem übereinstimmenden Gerät, unabhängig davon, ob der Treiber besser mit dem Gerät als dem Treiber übereinstimmt, der derzeit auf dem Gerät installiert ist. Wenn auch DIIRFLAG_INSTALL_AS_SET angegeben wird, wird DIIRFLAG_FORCE_INF ignoriert.

Vorsicht Das Erzwingen der Installation des Treibers kann dazu führen, dass ein kompatiblerer oder neuerer Treiber durch einen weniger kompatiblen oder älteren Treiber ersetzt wird.
 

Wenn Flags DIIRFLAG_INSTALL_AS_SET enthält (unterstützt in Windows 10 Version 1709 und höher), sollte InfPath anstelle eines vollqualifizierten Pfads zu einer INF-Datei ein Verzeichnis angeben, und DiInstallDriver installiert alle INF-Dateien in diesem Verzeichnis mit besonderem Verhalten. Alle Treiberpakete werden im Treiberspeicher bereitgestellt, aber noch nicht für die Installation auf Geräten verfügbar gemacht. Beim nächsten Herunterfahren des Systems werden diese Treiberpakete für die Installation auf Geräten zur Verfügung gestellt, und sie werden auf allen Geräten installiert, für die sie am besten geeignet sind, sodass die Geräte beim nächsten Start des Systems bereit sind.

[out, optional] NeedReboot

Ein Zeiger auf einen Wert vom Typ BOOL, den DiInstallDriver festlegt, um anzugeben, ob ein Systemneustart erforderlich ist, um die Installation abzuschließen. Dieser Parameter ist optional und kann NULL sein. Wenn der Parameter angegeben wird und ein Neustart des Systems erforderlich ist, um die Installation abzuschließen, legt DiInstallDriver den Wert auf TRUE fest. In diesem Fall muss der Aufrufer den Benutzer auffordern, das System neu zu starten. Wenn dieser Parameter angegeben wird und kein Neustart des Systems erforderlich ist, um die Installation abzuschließen, legt DiInstallDriver den Wert auf FALSE fest. Wenn der Parameter NULL ist und ein Systemneustart erforderlich ist, um die Installation abzuschließen, zeigt DiInstallDriver ein Dialogfeld "Systemneustart" an. Weitere Informationen zu diesem Parameter finden Sie im abschnitt Hinweise .

Rückgabewert

DiInstallDriver gibt TRUE zurück, wenn die Funktion das angegebene Treiberpaket erfolgreich im Treiberspeicher vorinstalliert hat. DiInstallDriver gibt auch TRUE zurück, wenn die Funktion den Treiber erfolgreich auf einem oder mehreren Geräten im System installiert hat. Wenn das Treiberpaket nicht erfolgreich im Treiberspeicher installiert wurde, gibt DiInstallDriverFALSE zurück, und der protokollierte Fehler kann abgerufen werden, indem Sie GetLastError aufrufen. 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. Standardmäßig erfordert Windows, dass der Aufrufer über Administratorrechte verfügt, um ein Treiberpaket im Treiberspeicher vorzuinstallieren.
ERROR_FILE_NOT_FOUND
 Der Pfad der angegebenen INF-Datei ist nicht vorhanden.
ERROR_INVALID_FLAGS
 Der für Flags angegebene Wert ist nicht gleich Null oder DIIRFLAG_FORCE_INF.
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

DiInstallDriver führt die folgenden Vorgänge aus:

  1. Vorinstalliert das Treiberpaket im Treiberspeicher. Wenn ein instance desselben Treiberpakets bereits im Treiberspeicher vorinstalliert ist, entfernt DiInstallDriver zuerst dieses instance und fügt dann dem Treiberspeicher die neue instance des Treiberpakets hinzu.
  2. Listet Geräte auf, die im System vorhanden sind.
  3. Wenn Flags gleich 0 ist, wird der Treiber nur dann auf einem Gerät installiert, wenn der angegebene Treiber besser mit dem Gerät übereinstimmt als der Treiber, der derzeit auf dem Gerät installiert ist.
  4. Wenn Flags gleich DIIRFLAG_FORCE_INF ist, installiert der Treiber auf einem Gerät, unabhängig davon, ob das Treiberpaket besser mit dem Gerät übereinstimmt als der Treiber, der derzeit auf dem Gerät installiert ist.
Im Allgemeinen sollte eine Installationsanwendung NeedReboot auf NULL festlegen, um DiInstallDriver anweisen, den Benutzer zum Neustart des Systems aufzufordern, 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 DiInstallDriver mehrmals aufrufen, um eine Installation abzuschließen. In diesem Fall sollte die Anwendung aufzeichnen, ob ein TRUENeedReboot-Wert von einem der Aufrufe von DiInstallDriver zurückgegeben wird. Wenn dies der Fall ist, sollte der Benutzer aufgefordert werden, das System neu zu starten, nachdem der letzte Aufruf von DiInstallDriver zurückgegeben wird.
  • Die Anwendung muss die erforderlichen Vorgänge ausführen, mit Ausnahme des Aufrufs von DiInstallDriver, 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.
Um einen ausgewählten Treiber auf einem ausgewählten Gerät zu installieren, rufen Sie DiInstallDevice auf. Weitere Informationen finden Sie unter SetupAPI-Funktionen, die die Treiberinstallation vereinfachen.

Hinweis

Der header newdev.h definiert DiInstallDriver als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

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

Weitere Informationen

DiInstallDevice