The SetupDiChangeState function is the default handler for the DIF_PROPERTYCHANGE installation request.
BOOL SetupDiChangeState( _In_ HDEVINFO DeviceInfoSet, _Inout_ PSP_DEVINFO_DATA DeviceInfoData );
- DeviceInfoSet [in]
A handle to a device information set for the local computer. This set contains a device information element that represents the device whose state is to be changed.
- DeviceInfoData [in, out]
A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet. This is an IN-OUT parameter because DeviceInfoData.DevInst might be updated with a new handle value upon return.
The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved by making a call to GetLastError.
SetupDiChangeState changes the state of an installed device.
The caller of SetupDiChangeState must be a member of the Administrators group.
Note Only a class installer should call SetupDiChangeState and only in those situations where the class installer must perform property change operations after SetupDiChangeState completes the default property change operation. In such situations, the class installer must directly call SetupDiChangeState when the installer processes a DIF_PROPERTYCHANGE request. For more information about calling the default handler, see Calling Default DIF Code Handlers.
Callers of SetupDiChangeState must specify a DICS_XXX flag in the SP_PROPCHANGE_PARAMS for the device element that indicates the type of state change to perform on the device. Callers of this function must set the appropriate fields in the SP_PROPCHANGE_PARAMS and call SetupDiSetClassInstallParams before calling this function.
If you specify the DICS_FLAG_CONFIGSPECIFIC flag in the SP_PROPCHANGE_PARAMS then you must fill in the HwProfile field. A value of zero for HwProfile indicates the current profile.
To enable/disable a device in the current hardware profile, set the DICS_FLAG_CONFIGSPECIFIC flag in the SP_PROPCHANGE_PARAMS. To enable/disable a device globally, such as in both the docked and undocked hardware profiles, set the DICS_FLAG_GLOBAL flag.
This function does the following:
Loads the drivers for the device and starts the device, if possible. If the function cannot start the device, it sets the DI_NEEDREBOOT flag for the device which indicates to the initiator of the property change request that they must prompt the user to restart the computer.
Disables the device. If the device can be disabled but this function cannot disable the device dynamically, this function marks the device to be disabled the next time that the computer restarts.
Removes and reconfigures the device so that the new properties can take effect. This flag typically indicates that a user has changed a property on a device manager property page for the device. The PnP manager directs the drivers for the device to remove their device objects and then the PnP manager reconfigures and restarts the device.
Callers of this function should not specify DICS_STOP or DICS_START in the SP_PROPCHANGE_PARAMS. Use DICS_PROPCHANGE to stop and restart a device to cause changes in the device's configuration to take effect.
If DI_DONOTCALLCONFIGMG is set for a device, you should not call SetupDiChangeState for the device but should instead set the DI_NEEDREBOOT flag.
|Available in Microsoft Windows 2000 and later versions of Windows.|
Build date: 11/16/2013