UpdateDriverForPlugAndPlayDevicesA-Funktion (newdev.h)

Artikel
03/04/2024

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

Syntax

BOOL UpdateDriverForPlugAndPlayDevicesA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR HardwareId,
  [in]            LPCSTR 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-beendete Zeichenfolge, die den Hardwarebezeichner bereitstellt, um vorhandenen Geräten auf dem Computer zu entsprechen. 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-beendete Zeichenfolge, die den vollständigen Pfaddateinamen einer INF-Datei angibt. 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 0 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 bereits bessere Treiber auf dem Computer 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 ein Versuch zur Anzeige der Benutzeroberfläche erkannt wird. 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 eine Anzeige der Benutzeroberfläche versucht wird, kann das Gerät in einem unbestimmten Zustand belassen werden.

Der InstallFlags-Parameter ist in der Regel 0.

[out, optional] bRebootRequired

Ein Zeiger auf eine BOOL-typisierte Variable, die 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 der Treiber ggf. 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, zum 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 stimmte nicht besser als der aktuelle Treiber überein, und der Aufrufer gab das INSTALLFLAG_FORCE-Flag nicht an.

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 aktuell 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 angeschlossen 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 eine Abfrage-Entfernungsanforderung fehlschlägt, legt UpdateDriverForPlugAndPlayDevices das DI_NEEDREBOOT-Flag 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 jeden TRUE-Neustart status empfangenen Wert speichern und dann nach dem letzten Aufruf zum Neustart auffordern.

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