DiInstallDriverA-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 DiInstallDriverA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR InfPath,
  [in]            DWORD  Flags,
  [out, optional] PBOOL  NeedReboot
);

Parameter

[in, optional] hwndParent

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

[in] InfPath

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

[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 eine bessere Übereinstimmung für das Gerät als der Treiber ist, der derzeit auf dem Gerät installiert ist. Wenn auch DIIRFLAG_INSTALL_AS_SET angegeben ist, 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 unter 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 zur Verfügung gestellt. 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, damit 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 Systemneustart 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 für den Systemneustart an. Weitere Informationen zu diesem Parameter finden Sie im folgenden 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 durch Aufrufen 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. Standardmäßig erfordert Windows, dass der Aufrufer über Administratorrechte verfügt, um ein Treiberpaket im Treiberspeicher vorab zu installieren.
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 0 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. Installiert das Treiberpaket im Treiberspeicher. Wenn ein instance desselben Treiberpakets bereits im Treiberspeicher vorinstalliert ist, entfernt DiInstallDriver zunächst 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, installiert den Treiber nur dann auf einem Gerät, 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 den 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 anzuweisen, den Benutzer aufzufordern, 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 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, und wenn dies der Fall ist, den Benutzer auffordern, 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 der Klasseninstaller das DI_NEEDREBOOT Flag im Flags-Member der SP_DEVINSTALL_PARAMS-Struktur für ein Gerät festlegen.
Rufen Sie DiInstallDevice auf, um einen ausgewählten Treiber auf einem ausgewählten Gerät zu installieren. Weitere Informationen finden Sie unter SetupAPI-Funktionen zur Vereinfachung der Treiberinstallation.

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 Code, der nicht Codierungsneutral ist, 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