Функция DiUninstallDevice (newdev.h)

Статья
08/25/2023

Функция DiUninstallDevice удаляет устройство и удаляет его узел устройства (devnode) из системы. Это отличается от использования SetupDiCallClassInstaller с кодом DIF_REMOVE , так как он пытается удалить узел устройства в дополнение к дочерним devnodes, которые присутствуют во время вызова.

До Windows 8 все дочерние устройства, которые отсутствуют во время вызова, не будут удалены. Однако начиная с Windows 8, все дочерние устройства, которые отсутствуют во время вызова, будут удалены.

Синтаксис

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

Параметры

[in] hwndParent

Дескриптор окна верхнего уровня, используемого для отображения любого компонента пользовательского интерфейса, связанного с запросом на удаление для устройства. Этот параметр является необязательным и может иметь значение NULL.

[in] DeviceInfoSet

Дескриптор набора сведений об устройстве , содержащего элемент сведений об устройстве. Этот элемент представляет устройство, которое будет удалено с помощью этого вызова.

[in] DeviceInfoData

Указатель на структуру SP_DEVINFO_DATA , представляющую указанное устройство в указанном наборе сведений об устройстве, для которого выполняется запрос на удаление.

[in] Flags

Значение типа DWORD, указывающее флаги удаления устройства. Начиная с Windows 7 для этого параметра необходимо задать нулевое значение.

[out, optional] NeedReboot

Указатель на значение типа BOOL, заданное DiUninstallDevice , чтобы указать, требуется ли перезагрузка системы для выполнения запроса на удаление устройства. Этот параметр является необязательным и может иметь значение NULL.

Если задан параметр и требуется перезагрузка системы, DiUninstallDevice задает значение TRUE. В этом случае приложение должно предложить пользователю перезапустить систему. Если этот параметр указан и перезапуск системы не требуется, DiUninstallDevice устанавливает значение FALSE.

Если этот параметр имеет значение NULL и для завершения удаления устройства требуется перезагрузка системы, DiUninstallDevice отображает диалоговое окно перезагрузки системы.

Дополнительные сведения об этом параметре см. в разделе Примечания .

Возвращаемое значение

DiUninstallDevice возвращает значение TRUE , если функция успешно удалила узел устройства верхнего уровня, представляющий устройство. В противном случае DiUninstallDevice возвращает значение FALSE, а зарегистрированную ошибку можно получить, выполнив вызов GetLastError. В следующем списке показаны некоторые из наиболее распространенных значений ошибок, которые getLastError может возвращать для этого API:

Код возврата	Описание
ERROR_ACCESS_DENIED	Вызывающий объект не имеет прав администратора. По умолчанию Windows требует, чтобы вызывающий объект был иметь права администратора для удаления устройств.
ERROR_INVALID_FLAGS	Значение, указанное для параметра Flags , не равно нулю.

Примечание Возвращаемое значение не указывает, что удаление всех дочерних devnodes выполнено успешно или не удалось. Начиная с Windows Vista сведения о состоянии удаления дочерних devnodes доступны в файле Setupapi.dev.log . Дополнительные сведения об этом файле см. в разделе SetupAPI Text Logs.

DiUninstallDevice выполняет ту же функцию, что и SetupDiCallClassInstaller при использовании с DIF_REMOVE кодом. Ключевое отличие заключается в том, что дочерние devnodes для устройства верхнего уровня также удаляются. DiUninstallDevice возвращает ошибку только в том случае, если не удалось удалить узел устройства верхнего уровня, что согласуется с поведением SetupDiCallClassInstaller при использовании с DIF_REMOVE кодом. Подробные сведения об успешном удалении дочернего узла devnode доступны в файле Setupapi.dev.log.

Удаляемое устройство указывается путем предоставления набора сведений об устройстве , включающего указанное устройство, и структуру SP_DEVINFO_DATA для конкретного устройства. Они предоставляются в параметрах DeviceInfoSet и DeviceInfoData .

Чтобы создать набор сведений об устройствах, содержащий указанное устройство, и получить структуру SP_DEVINFO_DATA для устройства, выполните одну из следующих задач:

Вызовите SetupDiGetClassDevs , чтобы получить набор сведений об устройствах, который содержит устройство, а затем вызовите Метод SetupDiEnumDeviceInfo для перечисления устройств в наборе сведений об устройствах. При каждом вызове SetupDiEnumDeviceInfo возвращает структуру SP_DEVINFO_DATA , представляющую перечисленное устройство в наборе сведений об устройстве.
Чтобы получить конкретные сведения о перечислимом устройстве, вызовите Метод SetupDiGetDeviceProperty и укажите структуру SP_DEVINFO_DATA , возвращаемую методом SetupDiEnumDeviceInfo.
Вызовите SetupDiEnumDeviceInfo , чтобы добавить устройство с известным идентификатором экземпляра устройства в набор сведений об устройстве. SetupDiOpenDeviceInfo возвращает структуру SP_DEVINFO_DATA , представляющую устройство в наборе сведений об устройстве.

Если запрос на удаление устройства требует перезагрузки компьютера, DiUninstallDevice предлагает пользователю перезагрузить систему, если параметр NeedReboot имеет значение NULL. Если приложение использует какое-либо окно пользовательского интерфейса, для параметра hwndParent должно быть задано значение дескриптора этого окна.

Однако если приложение управляет уведомлением о необходимом перезапуске системы, оно должно задать для параметра NeedReboot значение, отличное от NULL . DiUninstallDevice задает для параметра NeedRebootзначение TRUE или FALSE в зависимости от того, требуется ли перезагрузка системы.

В следующем списке показаны примеры того, почему приложение может управлять перезагрузкой системы.

Приложению необходимо удалить несколько устройств. После удаления всех устройств приложение должно предложить пользователю перезапустить систему, если любой вызов DiUninstallDevice возвращал значение TRUE в параметре NeedReboot .
Приложение требует выполнения некоторых других операций, прежде чем система может быть перезапущена. Если требуется перезагрузка системы, приложение должно завершить необходимые операции, а затем предложить пользователю перезапустить систему.
Приложение является установщиком класса. В этом случае установщик класса должен установить флаг DI_NEEDREBOOT в элементе Flags структуры SP_DEVINSTALL_PARAMS для устройства.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows 7 и более поздних версиях Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	newdev.h (включая Newdev.h)
Библиотека	Newdev.lib
DLL	Newdev.dll