DiShowUpdateDevice function (newdev.h)

Article
10/13/2021

The DiShowUpdateDevice function displays the Hardware Update wizard for a specified device.

Syntax

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

Parameters

[in, optional] hwndParent

A handle to the top-level window that DiShowUpdateDevice uses to display any user interface components that are associated with updating the specified device. This parameter is optional and can be set to NULL.

[in] DeviceInfoSet

A handle to the device information set that contains a device information element that represents the device for which to show the Hardware Update wizard.

[in] DeviceInfoData

A pointer to an SP_DEVINFO_DATA structure that represents the device for which to show the Hardware Update wizard.

[in] Flags

This parameter must be set to zero.

[out, optional] NeedReboot

A pointer to a value of type BOOL that DiShowUpdateDevice sets to indicate whether a system restart is required to complete the driver update. This parameter is optional and can be NULL. If the parameter is supplied and a system restart is required to complete the driver update, DiShowUpdateDevice sets the value to TRUE. In this case, the caller must prompt the user to restart the system. If this parameter is supplied and a system restart is not required to complete the installation, DiShowUpdateDevice sets the value to FALSE. If the parameter is NULL and a system restart is required to complete the driver update, DiShowUpdateDevice displays a system restart dialog box. For more information about this parameter, see the following Remarks section.

Return value

DiShowUpdateDevice returns TRUE if the Hardware Update wizard successfully updated the driver for the specified device. Otherwise, DiShowUpdateDevice returns FALSE and the logged error can be retrieved by making a call to GetLastError. Some of the more common error values that GetLastError might return are as follows:

Return code	Description
ERROR_ACCESS_DENIED	The caller does not have Administrator privileges. By default, Windows requires that the calling process have Administrator privileges to update a driver package.
ERROR_CANCELLED	The user canceled the Hardware Update wizard.
ERROR_IN_WOW64	The calling application is a 32-bit application that is attempting to execute in a 64-bit environment, which is not allowed. For more information, see Installing Devices on 64-Bit Systems.
ERROR_INVALID_FLAGS	The value specified for Flags is not equal to zero.

Remarks

DiShowUpdateDevice displays the Hardware Update wizard for the specified device instance. For information about how to update device drivers by using the Hardware Update wizard, see Help and Support Center.

In general, installation applications should set NeedReboot to NULL so that the system will automatically initiate a system restart if a restart is required to complete a hardware update. An application should supply a NeedReboot pointer only in the following cases:

The installation application must call DiShowUpdateDevice several times to complete hardware updates. In this case, the application should record whether a TRUENeedReboot value is returned by any of the calls to DiShowUpdateDevice and, if so, prompt the user to restart the system after the final call to DiShowUpdateDevice returns.
The application must perform required operations, other than calling DiShowUpdateDevice, before a system restart should occur. If a system restart is required, the application should finish the required operations and then prompt the user to restart the system.

To roll back a driver for a device instead of invoking the Hardware Update wizard, call DiRollbackDriver.

To install a new driver for a device instead of invoking the Hardware Update wizard, call DiInstallDriver or UpdateDriverForPlugAndPlayDevices.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of Windows.
Target Platform	Desktop
Header	newdev.h (include Newdev.h)
Library	Newdev.lib
DLL	Newdev.dll