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

Статья
03/08/2023

Функция DiInstallDevice устанавливает указанный драйвер, предварительно установленный в хранилище драйверов на указанном устройстве, которое присутствует в системе.

Синтаксис

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

Параметры

[in, optional] hwndParent

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

[in] DeviceInfoSet

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

[in] DeviceInfoData

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

[in, optional] DriverInfoData

Указатель на структуру SP_DRVINFO_DATA , указывающую драйвер для установки на указанном устройстве. Этот параметр является необязательным и может иметь значение NULL. Если этот параметр имеет значение NULL, DiInstallDevice выполняет поиск драйверов, предустановленных в хранилище драйверов , на наличие драйвера, который лучше всего соответствует указанному устройству, и, если он найден, устанавливает драйвер на указанном устройстве.

[in] Flags

Значение типа DWORD , указывающее ноль или следующий флаг:

DIIDFLAG_SHOWSEARCHUI

Если вызывающий объект не указывает драйвер (для DriverInfoData задано значение NULL), а DiInstallDevice не находит предустановленный драйвер, соответствующий указанному устройству. Вместо этого DiInstallDevice отображает мастер найденного нового оборудования для устройства.

DIIDFLAG_NOFINISHINSTALLUI

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

DIIDFLAG_INSTALLNULLDRIVER

DiInstallDevice пытается установить драйвер NULL на указанном устройстве. Если этот флаг установлен, DiInstallDevice не использует параметр DriverInfoData . DiInstallDevice удаляет все параметры устройства и, если устройство не может работать в необработанном режиме, функция устанавливает состояние устройства на CM_PROB_FAILED_INSTALL. Если DiInstallDevice не может установить драйвер null, полученное состояние устройства будет таким же, как если бы устройство было впервые подключено к компьютеру, а Windows не найдёрла драйвер для устройства.

DIIDFLAG_INSTALLCOPYINFDRIVERS

Любой дополнительный INF-файл, указанный с помощью директивы CopyINF , будет установлен на любом устройстве, к нему применимо. Любой сбой при установке дополнительного INF не приведет к сбою установки основного INF.

[out, optional] NeedReboot

Указатель на значение типа BOOL , заданное DiInstallDevice , чтобы указать, требуется ли перезагрузка системы для завершения установки. Этот параметр является необязательным и может иметь значение NULL. Если этот параметр указан и для завершения установки требуется перезагрузка системы, DiInstallDevice устанавливает значение TRUE. В этом случае вызывающий объект отвечает за перезапуск системы. Если этот параметр указан и перезапуск системы не требуется, DiInstallDevice устанавливает для этого параметра значение FALSE. Если этот параметр имеет значение NULL и для завершения установки требуется перезагрузка системы, DiInstallDevice отображает диалоговое окно перезагрузки системы.

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Вызывающий объект не имеет прав администратора. По умолчанию Windows Vista и Windows Server 2008 требуют, чтобы вызывающий процесс был иметь права администратора для установки драйвера на устройстве.
ERROR_INVALID_FLAGS	Значение, указанное для параметра Flags , не равно нулю или побитовой части ИЛИ допустимых флагов.
ERROR_IN_WOW64	Вызывающее приложение — это 32-разрядное приложение, которое пытается выполнить в 64-разрядной среде, что запрещено. Дополнительные сведения см. в разделе Установка устройств в 64-разрядных системах.

Вызывайте DiInstallDevice , только если необходимо установить определенный драйвер на определенном устройстве. В противном случае используйте UpdateDriverForPlugAndPlayDevices или DiInstallDriver , чтобы установить драйвер для устройства. Дополнительные сведения о том, какие из этих функций следует вызывать для установки драйвера на устройстве, см. в разделе SetupAPI Functions that Simplify Driver Installation.

Перед вызовом DiInstallDevice вызывающий объект должен получить структуру SP_DEVINFO_DATA для указания устройства и, при необходимости, структуру SP_DRVINFO_DATA , чтобы указать драйвер для устройства.

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

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

Чтобы получить SP_DRVINFO_DATA структуру для выбранного драйвера, вызовите SetupDiBuildDriverInfoList , чтобы создать список драйверов для устройства, а затем вызовите метод SetupDiEnumDriverInfo для перечисления элементов списка драйверов для устройства. Для каждого перечисленного драйвера SetupDiEnumDriverInfo извлекает структуру SP_DRVINFO_DATA , которая идентифицирует драйвер. Для получения дополнительных сведений о перечислимом драйвере также можно вызвать SetupDiGetDriverInfoDetail.

Как правило, приложение установки должно присвоить параметру NeedReboot значение NULL. Это гарантирует, что DiInstallDevice предложит пользователю перезапустить систему, если для завершения установки требуется перезагрузка. Приложение должно предоставлять указатель NeedReboot только в следующих случаях:

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

Требования

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