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

Статья
08/25/2023

При использовании INF-файла и идентификатора оборудования функция UpdateDriverForPlugAndPlayDevices устанавливает обновленные драйверы для устройств, соответствующих идентификатору оборудования.

Синтаксис

BOOL UpdateDriverForPlugAndPlayDevicesA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR HardwareId,
  [in]            LPCSTR FullInfPath,
  [in]            DWORD  InstallFlags,
  [out, optional] PBOOL  bRebootRequired
);

Параметры

[in, optional] hwndParent

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

[in] HardwareId

Указатель на строку с завершением NULL, которая предоставляет идентификатор оборудования, соответствующий существующим устройствам на компьютере. Максимальная длина аппаратного идентификатора, завершаемого значением NULL, MAX_DEVICE_ID_LEN. Дополнительные сведения об идентификаторах оборудования см. в разделе Строки идентификации устройств.

[in] FullInfPath

Указатель на строку с завершением NULL, которая предоставляет полный путь к INF-файлу. Файлы должны находиться на носителе распространения или в каталоге, созданном поставщиком, а не в системном расположении, например %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices копирует файлы драйверов в соответствующие системные расположения в случае успешной установки.

[in] InstallFlags

Значение, предоставленное вызывающей стороны, созданное с помощью ИЛИ для объединения нуля или нескольких из следующих битовых флагов:

INSTALLFLAG_FORCE

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

Важно Используйте этот флаг только с особой осторожностью. Установка этого флага может привести к установке более старого драйвера поверх нового драйвера, если пользователь запускает приложение поставщика после того, как будут доступны новые драйверы.

INSTALLFLAG_READONLY

Если этот флаг установлен, функция не будет копировать, переименовывать или удалять файлы установки. Использование этого флага должно быть ограничено средами, в которых доступ к файлам ограничен или невозможен, например "внедренной" операционной системой.

INSTALLFLAG_NONINTERACTIVE

Если этот флаг установлен, функция возвращает значение FALSE при обнаружении любой попытки отображения пользовательского интерфейса. Установите этот флаг, только если функция будет вызываться из компонента (например, службы), который не может отображать пользовательский интерфейс.

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

Параметр InstallFlags обычно равен нулю.

[out, optional] bRebootRequired

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

Если указатель имеет значение NULL, UpdateDriverForPlugAndPlayDevices при необходимости запрашивает перезагрузку после установки драйверов. Если указан указатель, функция возвращает значение BOOLEAN, равное TRUE , если система должна быть перезапущена. После этого вызывающий объект отвечает за запрос на перезапуск.

Дополнительные сведения см. в следующем разделе Примечаний .

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

Функция возвращает значение TRUE , если устройство было обновлено до указанного драйвера.

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

Код возврата	Описание
ERROR_FILE_NOT_FOUND	Путь, указанный для FullInfPath , не существует.
ERROR_IN_WOW64	Вызывающее приложение — это 32-разрядное приложение, которое пытается выполнить в 64-разрядной среде, что запрещено.
ERROR_INVALID_FLAGS	Недопустимое значение, указанное в параметре InstallFlags .
ERROR_NO_SUCH_DEVINST	Значение, указанное для HardwareId , не соответствует ни одному устройству в системе. То есть устройство не подключено.
ERROR_NO_MORE_ITEMS	Функция обнаружила совпадение для значения HardwareId , но указанный драйвер не был лучше, чем текущий драйвер, и вызывающий объект не указал флаг INSTALLFLAG_FORCE.

UpdateDriverForPlugAndPlayDevices проверяет устройства в системе и пытается установить драйверы, указанные в FullInfPath , для всех устройств, соответствующих указанному значению HardwareId .

Поведение по умолчанию заключается в установке указанных драйверов только в том случае, если они лучше соответствуют установленным в данный момент драйверам, а указанные драйверы также лучше соответствуют любым драйверам в %SystemRoot%\inf. Дополнительные сведения см. в разделе Выбор драйверов в Windows.

UpdateDriverForPlugAndPlayDevices также можно использовать, чтобы определить, подключено ли устройство с указанным значением HardwareId . Дополнительные сведения см. в статье Создание приложения для установки устройств.

UpdateDriverForPlugAndPlayDevices отправляет запрос IRP_MN_QUERY_REMOVE_DEVICE указанному устройству, всем дочерним элементам устройства и всем другим устройствам, которые рекурсивно являются частью отношений удаления для устройства. Если какое-либо из этих устройств не выполняет запрос на удаление, UpdateDriverForPlugAndPlayDevices устанавливает флаг DI_NEEDREBOOT в элементе Flagsструктуры SP_DEVINSTALL_PARAMS для устройства. Сведения о связях удаления см. в запросе на IRP_MN_QUERY_DEVICE_RELATIONS .

Как правило, приложения установки устройств должны указывать значение NULL для bRebootRequired. Таким образом, при необходимости система инициирует перезагрузку. Приложение должно указывать значение указателя только в следующих случаях:

Чтобы завершить установку, приложение должно несколько раз вызвать UpdateDriverForPlugAndPlayDevices .
Приложение должно выполнять другие операции перед перезапуском (если это необходимо).
Приложение является установщиком класса, который должен задать DI_NEEDREBOOT в SP_DEVINSTALL_PARAMS , если требуется перезагрузка.

Если приложение должно вызывать UpdateDriverForPlugAndPlayDevices несколько раз, оно должно сохранить полученное значение состояния перезапуска TRUE , а затем запрашивать перезагрузку после возврата последнего вызова.

Если функция возвращает ERROR_IN_WOW64 в 32-разрядном приложении, приложение выполняется в 64-разрядной системе, что запрещено. Дополнительные сведения см. в статье Установка устройств в 64-разрядных системах.

Требования

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

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