Поделиться через

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

  • Статья

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

Синтаксис

BOOL DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR InfPath,
  [in]            DWORD   Flags,
  [out, optional] PBOOL   NeedReboot
);

Параметры

[in, optional] hwndParent

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

[in] InfPath

Указатель на строку, завершающуюся значением NULL, которая предоставляет полный путь к INF-файлу для пакета драйвера.

[in] Flags

Значение типа DWORD, указывающее ноль или комбинацию одного или нескольких флагов, как описано здесь (обычно флаги имеют нулевое значение).

Если параметр Flags равен нулю, DiInstallDriver устанавливает указанный драйвер на устройство только в том случае, если драйвер лучше подходит для устройства, чем драйвер, установленный на устройстве. Сведения о том, как Windows выбирает драйвер для устройства, см. в разделе Выбор драйверов в Windows.

Если флаги включают DIIRFLAG_FORCE_INF, DiInstallDriver устанавливает указанный драйвер на соответствующее устройство независимо от того, лучше ли драйвер соответствует устройству, чем драйвер, установленный в данный момент на устройстве. Если также указан DIIRFLAG_INSTALL_AS_SET, DIIRFLAG_FORCE_INF игнорируется.

Осторожностью Принудительная установка драйвера может привести к замене более совместимого или более нового драйвера на менее совместимый или более старый драйвер.
 

Если flags включает DIIRFLAG_INSTALL_AS_SET (поддерживается в Windows 10 версии 1709 и более поздних), InfPath должен указывать каталог вместо полного пути к INF-файлу, а DiInstallDriver установит все INF-файлы в этом каталоге с особым поведением. Все пакеты драйверов будут переведены в хранилище драйверов , но пока не будут доступны для установки на устройствах. При следующем завершении работы системы эти пакеты драйверов будут доступны для установки на устройствах в будущем, и они будут установлены на любых устройствах, которые лучше всего соответствуют таким образом, чтобы устройства были готовы при следующей загрузке системы.

[out, optional] NeedReboot

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

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

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

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

Комментарии

DiInstallDriver выполняет следующие операции:

  1. Предварительно устанавливает пакет драйвера в хранилище драйверов. Если в хранилище драйверов уже установлен экземпляр того же пакета драйверов, DiInstallDriver сначала удаляет этот экземпляр, а затем добавляет новый экземпляр пакета драйверов в хранилище драйверов.
  2. Перечисляет устройства, которые присутствуют в системе.
  3. Если параметр Flags равен нулю, устанавливает драйвер на устройстве только в том случае, если указанный драйвер лучше соответствует устройству, чем драйвер, установленный на устройстве.
  4. Если флаги равны DIIRFLAG_FORCE_INF, устанавливает драйвер на устройстве независимо от того, соответствует ли пакет драйвера устройству лучше, чем драйвер, установленный на устройстве.
Как правило, приложение установки должно задать для параметра NeedRebootзначение NULL , чтобы направить DiInstallDriver , чтобы предложить пользователю перезапустить систему, если для завершения установки требуется перезагрузка. Приложение должно предоставлять указатель NeedReboot только в следующих случаях:
  • Чтобы завершить установку, приложение должно вызвать DiInstallDriver несколько раз. В этом случае приложение должно записать, возвращается ли значение TRUENeedReboot любым из вызовов DiInstallDriver , и, если да, предложите пользователю перезапустить систему после возврата окончательного вызова DiInstallDriver .
  • Приложение должно выполнять необходимые операции, кроме вызова DiInstallDriver, прежде чем произойдет перезагрузка системы. Если требуется перезагрузка системы, приложение должно завершить необходимые операции, а затем предложить пользователю перезапустить систему.
  • Приложение является установщиком класса. В этом случае установщик класса должен установить флаг DI_NEEDREBOOT в элементе Flags структуры SP_DEVINSTALL_PARAMS для устройства.
Чтобы установить выбранный драйвер на выбранном устройстве, вызовите DiInstallDevice. Дополнительные сведения см. в разделе SetupAPI Functions that Simplify Driver Installation.

Примечание

Заголовок newdev.h определяет DiInstallDriver в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

См. также раздел

DiInstallDevice