UpdateDriverForPlugAndPlayDevicesW-Funktion (newdev.h)

Artikel
08/25/2023

Bei Einer INF-Datei und einer Hardware-ID installiert die UpdateDriverForPlugAndPlayDevices-Funktion aktualisierte Treiber für Geräte, die der Hardware-ID entsprechen.

Syntax

BOOL UpdateDriverForPlugAndPlayDevicesW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR HardwareId,
  [in]            LPCWSTR FullInfPath,
  [in]            DWORD   InstallFlags,
  [out, optional] PBOOL   bRebootRequired
);

Parameter

[in, optional] hwndParent

Ein Handle für das Fenster der obersten Ebene, das für jede Benutzeroberfläche im Zusammenhang mit der Installation von Geräten verwendet werden soll.

[in] HardwareId

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Hardwarebezeichner bereitstellt, um vorhandene Geräte auf dem Computer abzugleichen. Die maximale Länge eines MIT NULL beendeten Hardwarebezeichners ist MAX_DEVICE_ID_LEN. Weitere Informationen zu Hardwarebezeichnern finden Sie unter Geräteidentifikationszeichenfolgen.

[in] FullInfPath

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den vollständigen Pfaddateinamen einer INF-Datei bereitstellt. Die Dateien sollten sich auf dem Verteilungsmedium oder in einem vom Anbieter erstellten Verzeichnis befinden, nicht an einem Systemspeicherort wie %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices kopiert Treiberdateien an die entsprechenden Systemspeicherorte, wenn die Installation erfolgreich ist.

[in] InstallFlags

Ein vom Aufrufer bereitgestellter Wert, der mithilfe von OR erstellt wird, um null oder mehr der folgenden Bitflags zu kombinieren:

INSTALLFLAG_FORCE

Wenn dieses Flag festgelegt ist und die Funktion ein Gerät findet, das dem HardwareId-Wert entspricht, installiert die Funktion neue Treiber für das Gerät, unabhängig davon, ob auf dem Computer bereits bessere Treiber vorhanden sind.

Wichtig Verwenden Sie dieses Flag nur mit äußerster Vorsicht. Das Festlegen dieses Flags kann dazu führen, dass ein älterer Treiber über einen neueren Treiber installiert wird, wenn ein Benutzer die Anwendung des Anbieters ausführt, nachdem neuere Treiber verfügbar sind.

INSTALLFLAG_READONLY

Wenn dieses Flag festgelegt ist, kopiert, benennt oder löscht die Funktion keine Installationsdateien. Die Verwendung dieses Flags sollte auf Umgebungen beschränkt sein, in denen der Dateizugriff eingeschränkt oder unmöglich ist, z. B. ein "eingebettetes" Betriebssystem.

INSTALLFLAG_NONINTERACTIVE

Wenn dieses Flag festgelegt ist, gibt die Funktion FALSE zurück, wenn versucht wird, die Benutzeroberfläche anzuzeigen. Legen Sie dieses Flag nur fest, wenn die Funktion von einer Komponente (z. B. einem Dienst) aufgerufen wird, die keine Benutzeroberfläche anzeigen kann.

Hinweis Wenn dieses Flag festgelegt ist und versucht wird, eine Ui-Anzeige durchzuführen, kann das Gerät in einem unbestimmten Zustand belassen werden.

Der InstallFlags-Parameter ist in der Regel null.

[out, optional] bRebootRequired

Ein Zeiger auf eine BOOL-typisierte Variable, der angibt, ob ein Neustart erforderlich ist und wer dazu aufgefordert werden soll. Dieser Zeiger ist optional und kann NULL sein.

Wenn der Zeiger NULL ist, fordert UpdateDriverForPlugAndPlayDevices nach der Installation von Treibern bei Bedarf zum Neustart auf. Wenn der Zeiger angegeben wird, gibt die Funktion einen BOOLEschen Wert zurück, der TRUE ist, wenn das System neu gestartet werden soll. Es liegt dann in der Verantwortung des Aufrufers, zu einem Neustart aufzufordern.

Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .

Rückgabewert

Die Funktion gibt TRUE zurück, wenn ein Gerät auf den angegebenen Treiber aktualisiert wurde.

Andernfalls wird FALSE zurückgegeben, und der protokollierte Fehler kann mit einem Aufruf von GetLastError abgerufen werden. Mögliche Fehlerwerte, die von GetLastError zurückgegeben werden, sind in der folgenden Tabelle enthalten.

Rückgabecode	Beschreibung
ERROR_FILE_NOT_FOUND	Der pfad, der für FullInfPath angegeben wurde, ist nicht vorhanden.
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.
ERROR_INVALID_FLAGS	Der für InstallFlags angegebene Wert ist ungültig.
ERROR_NO_SUCH_DEVINST	Der für HardwareId angegebene Wert stimmt mit keinem Gerät im System überein. Das heißt, das Gerät ist nicht angeschlossen.
ERROR_NO_MORE_ITEMS	Die Funktion hat eine Übereinstimmung für den HardwareId-Wert gefunden, aber der angegebene Treiber war keine bessere Übereinstimmung als der aktuelle Treiber, und der Aufrufer hat das flag INSTALLFLAG_FORCE nicht angegeben.

Hinweise

UpdateDriverForPlugAndPlayDevices überprüft die Geräte auf dem System und versucht, die von FullInfPath angegebenen Treiber für alle Geräte zu installieren, die dem angegebenen HardwareId-Wert entsprechen.

Das Standardverhalten besteht darin, die angegebenen Treiber nur zu installieren, wenn sie besser mit den derzeit installierten Treibern übereinstimmen und die angegebenen Treiber auch besser übereinstimmen als alle Treiber in %SystemRoot%\inf. Weitere Informationen finden Sie unter So wählt Windows Treiber aus.

UpdateDriverForPlugAndPlayDevices kann auch verwendet werden, um zu bestimmen, ob das Gerät mit dem angegebenen HardwareId-Wert eingesteckt ist. Weitere Informationen finden Sie unter Schreiben einer Geräteinstallationsanwendung.

UpdateDriverForPlugAndPlayDevices sendet eine IRP_MN_QUERY_REMOVE_DEVICE-Anforderung an das angegebene Gerät, alle untergeordneten Elemente des Geräts und alle anderen Geräte, die rekursiv Teil der Entfernungsbeziehungen für das Gerät sind. Wenn eines dieser Geräte bei einer Abfragelöschanforderung fehlschlägt, legt UpdateDriverForPlugAndPlayDevices das flag DI_NEEDREBOOT im Flags-Element der SP_DEVINSTALL_PARAMS-Struktur für das Gerät fest. Informationen zu Entfernungsbeziehungen finden Sie in der IRP_MN_QUERY_DEVICE_RELATIONS-Anforderung .

Im Allgemeinen sollten GeräteinstallationsanwendungenNULL für bRebootRequired bereitstellen. Daher initiiert das System bei Bedarf einen Neustart. Eine Anwendung sollte einen Zeigerwert nur in den folgenden Fällen angeben:

Die Anwendung muss UpdateDriverForPlugAndPlayDevices mehrmals aufrufen, um eine Installation abzuschließen.
Die Anwendung muss andere Vorgänge ausführen, bevor der Neustart (falls erforderlich) erfolgt.
Die Anwendung ist ein Klasseninstallationsprogramm, das DI_NEEDREBOOT in SP_DEVINSTALL_PARAMS festlegen sollte, wenn ein Neustart erforderlich ist.

Wenn die Anwendung UpdateDriverForPlugAndPlayDevices mehrmals aufrufen muss, sollte sie alle TRUE-Neustarts status empfangenen Wert speichern und dann zu einem Neustart auffordern, nachdem der letzte Aufruf zurückgegeben wurde.

Wenn die Funktion ERROR_IN_WOW64 in einer 32-Bit-Anwendung zurückgibt, wird die Anwendung auf einem 64-Bit-System ausgeführt, was nicht zulässig ist. Weitere Informationen finden Sie unter Installieren von Geräten auf 64-Bit-Systemen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	newdev.h (include Newdev.h)
Bibliothek	Newdev.lib

Freigeben über