DiInstallDriverA-Funktion (newdev.h)

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

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 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 MIT NULL beendete Zeichenfolge, die den vollqualifizierten Pfad der INF-Datei für das Treiberpaketbereitstellt.

[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 Null festgelegt).

Wenn Flags null ist, DiInstallDriver nur den angegebenen Treiber auf einem Gerät installiert, wenn der Treiber für ein Gerät besser geeignet ist 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 How Windows Selects Drivers.

Wenn Flags DIIRFLAG_FORCE_INF enthält, installiert DiInstallDriver den angegebenen Treiber auf einem übereinstimmenden Gerät, unabhängig davon, ob der Treiber für das Gerät besser geeignet ist als der Treiber, der derzeit auf dem Gerät installiert ist. Wenn DIIRFLAG_INSTALL_AS_SET ebenfalls 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 (unter Windows 10, Version 1709 und höher unterstützt), sollte InfPath- ein Verzeichnis anstelle eines vollqualifizierten Pfads zu einer INF-Datei angeben und DiInstallDriver alle INF-Dateien in diesem Verzeichnis mit besonderem Verhalten installieren. Alle Treiberpakete werden im Treiberspeicher bereitgestellt, aber noch nicht auf Geräten installiert werden. 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, der DiInstallDriver festlegt, um anzugeben, ob ein System neu gestartet wird, um die Installation abzuschließen. Dieser Parameter ist optional und kann NULL-werden. Wenn der Parameter angegeben wird und ein Systemneustart erforderlich ist, um die Installation abzuschließen, legt DiInstallDriver den Wert auf TRUEfest. In diesem Fall muss der Aufrufer den Benutzer auffordern, das System neu zu starten. Wenn dieser Parameter angegeben wird und kein Systemneustart 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 Anmerkungen.

Rückgabewert

DiInstallDriver gibt TRUE zurück, wenn die Funktion erfolgreich das angegebene Treiberpaket im Treiberspeichervorinstalliert 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ückgegeben werden, 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 Treiberspeichervorzuinstallieren.
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, die nicht zulässig ist. Weitere Informationen finden Sie unter Installieren von Geräten auf 64-Bit-Systemen.

Bemerkungen

DiInstallDriver führt die folgenden Vorgänge aus:

1. Vorinstalliert das Treiberpaket im Treiberspeicher. Wenn bereits eine Instanz desselben Treiberpakets im Treiberspeicher vorinstalliert ist, DiInstallDriver diese Instanz zuerst entfernt und anschließend die neue Instanz des Treiberpakets zum Treiberspeicher hinzufügt.
2. Listet Geräte auf, die im System vorhanden sind.
3. Wenn Flags gleich Null ist, wird der Treiber nur 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, wird der Treiber auf einem Gerät installiert, unabhängig davon, ob das Treiberpaket die bessere Übereinstimmung mit dem Gerät ist als der Treiber, der derzeit auf dem Gerät installiert ist.

Im Allgemeinen sollte eine Installationsanwendung NeedReboot- auf NULL- festlegen, um DiInstallDriver- zu leiten, um den Benutzer aufzufordern, das System neu zu starten, wenn ein Neustart erforderlich ist, um die Installation abzuschließen. Eine Anwendung sollte nur in den folgenden Fällen einen NeedReboot Zeiger 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 in diesem Fall den Benutzer auffordern, das System nach dem letzten Aufruf von DiInstallDriver neu zu starten.
• Die Anwendung muss erforderliche Vorgänge ausführen, die nicht DiInstallDriver-aufrufen, bevor ein Systemneustart erfolgen soll. Wenn ein Systemneustart erforderlich ist, sollte die Anwendung die erforderlichen Vorgänge abschließen und den Benutzer auffordern, das System neu zu starten.
• Die Anwendung ist ein Klasseninstallationsprogramm, in diesem Fall sollte das Klasseninstallationsprogramm das DI_NEEDREBOOT Flag im Flags Mitglied der SP_DEVINSTALL_PARAMS-Struktur für ein Gerät festlegen.

Rufen Sie DiInstallDeviceauf, um einen ausgewählten Treiber auf einem ausgewählten Gerät zu installieren. Weitere Informationen finden Sie unter SetupAPI-Funktionen, die die Treiberinstallationvereinfachen.

Anmerkung

Der header newdev.h definiert DiInstallDriver als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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
mindestens unterstützte Client-	Verfügbar in Windows Vista und höheren Versionen von Windows.
Zielplattform-	Desktop
Header-	newdev.h (include Newdev.h)
Library	Newdev.lib

Siehe auch

DiInstallDevice