SetupDiChangeState-Funktion (setupapi.h)

  • Artikel

Die SetupDiChangeState-Funktion ist der Standardhandler für die DIF_PROPERTYCHANGE Installationsanforderung.

Syntax

WINSETUPAPI BOOL SetupDiChangeState(
  [in]      HDEVINFO         DeviceInfoSet,
  [in, out] PSP_DEVINFO_DATA DeviceInfoData
);

Parameter

[in] DeviceInfoSet

Ein Handle zu einem Geräteinformationssatz für den lokalen Computer. Dieser Satz enthält ein Geräteinformationselement, das das Gerät darstellt, dessen Zustand geändert werden soll.

[in, out] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die das Geräteinformationselement in DeviceInfoSet angibt. Dies ist ein IN-OUT-Parameter, da DeviceInfoData.DevInst kann bei der Rückgabe mit einem neuen Handle-Wert aktualisiert werden.

Rückgabewert

Die Funktion gibt TRUE zurück, wenn sie erfolgreich ist. Andernfalls wird FALSE zurückgegeben, und der protokollierte Fehler kann durch einen Aufruf von GetLastError abgerufen werden.

Hinweise

SetupDiChangeState ändert den Zustand eines installierten Geräts.

Der Aufrufer von SetupDiChangeState muss Mitglied der Gruppe Administratoren sein.

Hinweis Nur ein Klasseninstallationsprogramm sollte SetupDiChangeState aufrufen, und das nur in den Situationen, in denen der Klasseninstallationsprogramm Eigenschaftsänderungsvorgänge ausführen muss, nachdem SetupDiChangeState den Standardvorgang zum Ändern der Eigenschaft abgeschlossen hat. In solchen Situationen muss das Klasseninstallationsprogramm SetupDiChangeState direkt aufrufen, wenn das Installationsprogramm eine DIF_PROPERTYCHANGE Anforderung verarbeitet. Weitere Informationen zum Aufrufen des Standardhandlers finden Sie unter Aufrufen von DIF-Standardcodehandlern.
 
Aufrufer von SetupDiChangeState müssen im SP_PROPCHANGE_PARAMS für das Geräteelement ein DICS_XXX-Flag angeben, das den Typ der auf dem Gerät durchzuführenden Zustandsänderung angibt. Aufrufer dieser Funktion müssen die entsprechenden Felder im SP_PROPCHANGE_PARAMS festlegen und SetupDiSetClassInstallParams aufrufen, bevor sie diese Funktion aufrufen.

Wenn Sie das DICS_FLAG_CONFIGSPECIFIC-Flag im SP_PROPCHANGE_PARAMS angeben, müssen Sie das Feld HwProfile ausfüllen. Der Wert 0 für HwProfile gibt das aktuelle Profil an.

Um ein Gerät im aktuellen Hardwareprofil zu aktivieren/deaktivieren, legen Sie das DICS_FLAG_CONFIGSPECIFIC-Flag im SP_PROPCHANGE_PARAMS fest. Um ein Gerät global zu aktivieren/deaktivieren, z. B. in den angedockten und nicht angedockten Hardwareprofilen, legen Sie das DICS_FLAG_GLOBAL-Flag fest.

Diese Funktion führt Folgendes aus:

Aufrufer dieser Funktion sollten keine DICS_STOP oder DICS_START im SP_PROPCHANGE_PARAMS angeben. Verwenden Sie DICS_PROPCHANGE, um ein Gerät zu beenden und neu zu starten, damit Änderungen an der Gerätekonfiguration wirksam werden.

Wenn DI_DONOTCALLCONFIGMG für ein Gerät festgelegt ist, sollten Sie nicht SetupDiChangeState für das Gerät aufrufen, sondern stattdessen das DI_NEEDREBOOT-Flag festlegen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform Desktop
Kopfzeile setupapi.h (einschließlich Setupapi.h)
Bibliothek Setupapi.lib
DLL Setupapi.dll
APIs ext-ms-win-setupapi-classinstallers-l1-1-2 (eingeführt in Windows 10, Version 10.0.14393)

Weitere Informationen

DIF_PROPERTYCHANGE

SP_PROPCHANGE_PARAMS

SetupDiCallClassInstaller