DiRollbackDriver-Funktion (newdev.h)

  • Artikel

Die DiRollbackDriver-Funktion führt ein Rollback des Treibers aus, der auf einem angegebenen Gerät installiert ist.

Syntax

BOOL DiRollbackDriver(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Parameter

[in] DeviceInfoSet

Ein Handle für den Geräteinformationssatz , der ein Geräteinformationselement enthält, das das Gerät darstellt, für das ein Treiberrollback ausgeführt wird.

[in] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA Struktur, die das spezifische Gerät in den angegebenen Geräteinformationen darstellt, für das ein Treiberrollback ausgeführt wird.

[in, optional] hwndParent

Ein Handle für das Fenster der obersten Ebene, das DiRollbackDriver verwendet, um eine beliebige Benutzeroberflächenkomponente anzuzeigen, die einem Treiberrollback für das angegebene Gerät zugeordnet ist. Dieser Parameter ist optional und kann auf NULL festgelegt werden.

[in] Flags

Ein Wert vom Typ DWORD, der auf Null oder ROLLBACK_FLAG_NO_UI festgelegt werden kann.

In der Regel sollte dieses Flag auf 0 festgelegt werden. In diesem Fall unterdrückt DiRollbackDriver nicht die Standardbenutzeroberflächenkomponenten, die einem Treiberrollback zugeordnet sind. Wenn dieses Flag jedoch auf ROLLBACK_FLAG_NO_UI festgelegt ist, unterdrückt DiRollbackDriver die Anzeige von Benutzeroberflächenkomponenten, die einem Treiberrollback zugeordnet sind.

[out, optional] NeedReboot

Ein Zeiger auf einen Wert vom Typ BOOL, den DiRollbackDriver festlegt, um anzugeben, ob ein Systemneustart erforderlich ist, um das Rollback abzuschließen. Dieser Parameter ist optional und kann NULL sein.

Wenn der Parameter angegeben wird und ein Systemneustart erforderlich ist, um das Rollback abzuschließen, legt DiRollbackDriver 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 Systemneustart erforderlich ist, um die Installation abzuschließen, legt DiRollbackDriver den Wert auf FALSE fest.

Wenn der Parameter NULL ist und ein Systemneustart erforderlich ist, um das Rollback abzuschließen, zeigt DiRollbackDriver ein Dialogfeld für den Systemneustart an.

Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt hinweise .

Rückgabewert

DiRollbackDriver gibt TRUE zurück, wenn die Funktion erfolgreich ein Rollback für den Treiber für das Gerät durchgeführt hat. Andernfalls gibt DiRollbackDriverFALSE zurück, und der protokollierte Fehler kann durch einen Aufruf 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 zurückzusetzen.
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.
ERROR_INVALID_FLAGS
 Der für Flags angegebene Wert ist nicht gleich null oder ROLLBACK_FLAG_NO_UI.
ERROR_NO_MORE_ITEMS
 Ein Sicherungstreiber ist für das Gerät nicht festgelegt.

Hinweise

Wenn ein zuvor installierter Sicherungstreiber für ein Gerät festgelegt ist, ersetzt ein Treiberrollback für das Gerät den Treiber, der derzeit auf dem Gerät installiert ist, durch den Sicherungstreiber. Windows verwaltet höchstens einen Sicherungstreiber für ein Gerät. Windows legt einen Treiber als Sicherungstreiber für ein Gerät fest, unmittelbar nachdem der Treiber erfolgreich auf dem Gerät installiert wurde, und Windows ermittelt, dass das Gerät ordnungsgemäß funktioniert. Wenn ein Treiber jedoch nicht erfolgreich auf einem Gerät installiert wird oder das Gerät nach der Installation nicht ordnungsgemäß funktioniert, legt Windows den Treiber nicht als Sicherungstreiber für das Gerät fest. Weitere Informationen zum Treiberrollback finden Sie unter Informationen zu Geräte-Manager im Hilfe- und Supportcenter.

Wenn das angegebene Gerät über einen Sicherungstreiber verfügt, führt DiRollbackDriver die folgenden Vorgänge aus:

  1. Wenn Flags auf 0 festgelegt ist, fordert DiRollbackDriver den Benutzer auf, zu bestätigen, ob der Sicherungstreiber installiert werden soll. Andernfalls installiert DiRollbackDriver, wenn Flags auf ROLLBACK_FLAG_NO_UI festgelegt ist, den Sicherungstreiber, ohne den Benutzer zur Bestätigung der Installation des Sicherungstreibers aufzufordern.
  2. DiRollbackDriver installiert den Sicherungstreiber. Der Treiber wird installiert, ob der Sicherungstreiber besser mit dem Gerät übereinstimmt als der Treiber, der derzeit auf dem Gerät installiert ist.
  3. Wenn der Treiber, der durch den Sicherungstreiber ersetzt wird, kein Posteingangstreiber ist und nicht auf anderen Geräten im System installiert ist, entfernt DiRollbackDriver den Treiber aus dem System. DiRollbackDriver entfernt den Treiber aus dem System, da davon ausgegangen wird, dass ein Benutzer einen Treiber nur dann ersetzt, wenn ein Problem mit dem Treiber vorliegt.
Wenn das angegebene Gerät keinen Sicherungstreiber hat, ruft DiRollbackDriverSetLastError auf, um den Fehler ERROR_NO_MORE_ITEMS festzulegen, entfernt den aktuell installierten Treiber nicht und gibt FALSE zurück.

Im Allgemeinen sollten Installationsanwendungen NeedReboot auf NULL festlegen, damit das System automatisch einen Systemneustart initiiert, wenn ein Neustart erforderlich ist, um das Rollback abzuschließen. Eine Anwendung sollte einen NeedReboot-Zeiger nur in den folgenden Fällen bereitstellen:

  • Die Anwendung muss DiRollbackDriver mehrmals aufrufen, um eine Installation abzuschließen. In diesem Fall sollte die Anwendung aufzeichnen, ob ein TRUENeedReboot-Wert von einem der Aufrufe von DiRollbackDriver zurückgegeben wird. Wenn dies der Fall ist, sollte der Benutzer aufgefordert werden, das System neu zu starten, nachdem der letzte Aufruf von DiRollbackDriver zurückgegeben wurde.
  • Die Anwendung muss die erforderlichen Vorgänge ausführen, mit Ausnahme des Aufrufs von DiRollbackDriver, 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.
Um einen neuen Treiber für ein Gerät zu installieren, anstatt den Treiber für das Gerät zurückzusetzen, rufen Sie DiInstallDriver oder UpdateDriverForPlugAndPlayDevices auf.

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
DLL Newdev.dll

Weitere Informationen

DiInstallDriver

UpdateDriverForPlugAndPlayGeräte