структура SP_DEVINSTALL_PARAMS_A (setupapi.h)

Статья
11/20/2024

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

Синтаксис

typedef struct _SP_DEVINSTALL_PARAMS_A {
  DWORD             cbSize;
  DWORD             Flags;
  DWORD             FlagsEx;
  HWND              hwndParent;
  PSP_FILE_CALLBACK InstallMsgHandler;
  PVOID             InstallMsgHandlerContext;
  HSPFILEQ          FileQueue;
  ULONG_PTR         ClassInstallReserved;
  DWORD             Reserved;
  CHAR              DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_A, *PSP_DEVINSTALL_PARAMS_A;

Члены

cbSize

Размер структуры SP_DEVINSTALL_PARAMS в байтах.

Flags

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

Значения флагов перечислены в группах: записываемые приложениями установки устройств и установщиками, только для чтения (только для ОС), зарезервированными и устаревшими. Первая группа перечисляет флаги, которые доступны для записи:

DI_CLASSINSTALLPARAMS

Задайте для использования параметров установки класса. SetupDiSetClassInstallParams задает этот флаг, когда вызывающий объект задает параметры и очищает флаг, когда вызывающий объект задает указатель NULL.

DI_COMPAT_FROM_CLASS

Задайте для принудительного SetupDiBuildDriverInfoList для создания списка совместимых драйверов устройства из списка драйверов классов вместо INF-файла.

DI_DRIVERPAGE_ADDED

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

DI_DONOTCALLCONFIGMG

Задайте, если диспетчер конфигурации не должен вызываться для удаления или повторного удаления устройств во время выполнения определенных функций установки устройства (например, SetupDiInstallDevice).

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

CM_Reenumerate_DevNode CM_Reenumerate_DevNode_Ex CM_Query_And_Remove_SubTree CM_Query_And_Remove_SubTree_Ex CM_Setup_DevNode CM_Setup_DevNode_Ex CM_Set_HW_Prof_Flags CM_Set_HW_Prof_Flags_Ex CM_Enable_DevNode CM_Enable_DevNode_Ex CM_Disable_DevNode CM_Disable_DevNode_Ex

DI_ENUMSINGLEINF

Если установщики и другие компоненты установки устройств должны выполнять поиск только в INF-файле, указанном SP_DEVINSTALL_PARAMS.DriverPath. Если этот флаг задан, DriverPath содержит путь к одному INF-файлу вместо пути к каталогу.

DI_INF_IS_SORTED

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

DI_INSTALLDISABLED

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

DI_NEEDREBOOT

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

DI_NEEDRESTART

То же, что и DI_NEEDREBOOT.

DI_NOBROWSE

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

DI_NODI_DEFAULTACTION

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

DI_NOFILECOPY

Установите, если приложения и компоненты установки устройства, такие как SetupDiInstallDevice, должны пропускать копирование файлов.

DI_NOVCP

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

DI_NOWRITE_IDS

Установите для предотвращения setupDiInstallDevice записи идентификаторов оборудования и совместимых идентификаторов устройства для узла устройства (devnode). Этот флаг должен быть задан только для устройств, перечисляемых корнем.

Этот флаг переопределяет флаг DI_FLAGSEX_ALWAYSWRITEIDS.

DI_PROPERTIES_CHANGE

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

DI_QUIETINSTALL

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

DI_RESOURCEPAGE_ADDED

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

DI_SHOWOEM

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

DI_USECI_SELECTSTRINGS

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

Следующие флаги доступны только для чтения (только для ОС):

DI_DIDCLASS

Задайте, если SetupDiBuildDriverInfoList уже создал список драйверов для этого класса устройства. Если этот список уже создан, он содержит все сведения о драйвере, и этот флаг всегда задан. SetupDiDetydriverInfoList очищает этот флаг при удалении списка драйверов для класса.

Этот флаг доступен только для чтения. Только операционная система задает этот флаг.

DI_DIDCOMPAT

Задайте, если SetupDiBuildDriverInfoList уже создал список совместимых драйверов для этого устройства. Если этот список уже создан, он содержит все сведения о драйвере, и этот флаг всегда задан. SetupDiDedriverInfoList очищает этот флаг при удалении совместимого списка драйверов.

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

Этот флаг доступен только для чтения. Только операционная система задает этот флаг.

DI_MULTMFGS

Задает SetupDiBuildDriverInfoList, если список драйверов для класса установки устройства устройства содержит драйверы, предоставляемые несколькими производителями.

Этот флаг доступен только для чтения. Только операционная система задает этот флаг.

Зарезервированы следующие флаги:

DI_AUTOASSIGNRES

DI_DISABLED

DI_FORCECOPY

DI_GENERALPAGE_ADDED

DI_OVERRIDE_INFFLAGS

DI_SHOWALL

DI_SHOWCLASS

DI_SHOWCOMPAT

Следующие флаги устарели:

DI_NOSELECTICONS

DI_PROPS_NOCHANGEUSAGE

FlagsEx

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

Значения флага перечислены в группах: записываемые приложениями и установщиками устройств, доступными только для чтения (только для ОС), зарезервированными и устаревшими.

Первая группа перечисляет флаги, которые доступны для записи:

DI_FLAGSEX_ALLOWEXCLUDEDDRVS

Если задано, включите драйверы, помеченные как "Исключить из выбора".

Например, если этот флаг задан, SetupDiSelectDevice отображает драйверы с состоянием "Исключить из выбора" и SetupDiBuildDriverInfoList включает в себя исключение из списка запрошенных драйверов.

Драйвер является "Исключить из выбора", если ExcludeFromSelect в INF-файле или драйвер для устройства, целое класс установки которого помечен NoInstallClass или NoUseClass в установщике классов INF. Драйверы для устройств PnP обычно являются "Исключить из выбора"; Устройства PnP не должны быть установлены вручную. Чтобы создать список файлов драйверов для устройства PnP, вызывающий объект SetupDiBuildDriverInfoList должен задать этот флаг.

DI_FLAGSEX_ALWAYSWRITEIDS

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

DI_FLAGSEX_APPENDDRIVERLIST

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

DI_FLAGSEX_DRIVERLIST_FROM_URL

Если задано, создайте список драйверов из INF(s), полученный из URL-адреса, указанного в SP_DEVINSTALL_PARAMS.DriverPath. Если DriverPath является пустой строкой, используйте веб-сайт Центра обновления Windows.

В настоящее время операционная система не поддерживает URL-адреса. Используйте этот флаг для прямого SetupDiBuildDriverInfoList для поиска веб-сайта Центра обновления Windows.

Не устанавливайте этот флаг, если установлен DI_QUIETINSTALL.

DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS

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

DI_FLAGSEX_FILTERCLASSES

Если задано, SetupDiBuildClassInfoList проверяет наличие фильтров включения классов. Это означает, что устройство не будет включено в список классов, если его класс помечен как NoInstallClass.

DI_FLAGSEX_FILTERSIMILARDRIVERS

(Windows XP и более поздние версии.) Если задано, SetupDiBuildDriverInfoList включает "аналогичные" драйверы при создании списка драйверов классов. Драйвер "аналогичный" — это драйвер, для которого один из аппаратных идентификаторов или совместимых идентификаторов в INF-файле частично (или полностью) соответствует одному из аппаратных идентификаторов или совместимых идентификаторов оборудования.

DI_FLAGSEX_FINISHINSTALL_ACTION

(Windows Vista и более поздние версии.) Дополнительные сведения см. в маркировке устройства как действия Finish-Install для выполнения.

DI_FLAGSEX_INET_DRIVER

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

DI_FLAGSEX_INSTALLEDDRIVER

(Windows XP и более поздние версии.) Если задано, SetupDiBuildDriverInfoList включает только текущий установленный драйвер при создании списка драйверов классов или драйверов, совместимых с устройствами.

DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE

(Windows XP и более поздние версии.) Если задано, при создании списка драйверов классов SetupDiBuildDriverInfoList не будет объединять узлы в списке драйверов, которые находятся в том же INF и имеют то же описание драйвера и ранг.

DI_FLAGSEX_NO_DRVREG_MODIFY

Не обработайте записи AddReg и DelReg для ключей оборудования и программного обеспечения (драйвера) устройства. То есть записи AddReg и DelReg в INF-файле DDInstall и DDInstall. Разделы HW.

DI_FLAGSEX_POWERPAGE_ADDED

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

DI_FLAGSEX_PROPCHANGE_PENDING

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

Когда пользователь закрывает лист свойств устройства, диспетчер устройств проверяет флаг DI_FLAGSEX_PROPCHANGE_PENDING. Если он задан, диспетчер устройств очищает этот флаг, задает флаг DI_PROPERTIES_CHANGE и отправляет DIF_PROPERTYCHANGE запрос установщикам, чтобы уведомить их о том, что что-то изменилось.

DI_FLAGSEX_RECURSIVESEARCH

(Windows Vista и более поздние версии.) Если задано, если SetupDiBuildDriverInfoList выполняет поиск INFS в пути, указанном в значении DriverPath, поиск будет рекурсивным.

DI_FLAGSEX_SEARCH_PUBLISHED_INFS

(Windows Vista и более поздние версии.) Если задано значение, если SetupDiBuildDriverInfoList используется для поиска INFs без пути INF или пути поиска, это ограничивает поиск только inFs, импортированных в хранилище драйверов.

DI_FLAGSEX_SETFAILEDINSTALL

Установите, если установка завершилась ошибкой. Если этот флаг задан , функция установки SetupDiInstallDevice просто задает флаг FAILEDINSTALL в ConfigFlags устройства значение реестра. Если задано DI_FLAGSEX_SETFAILEDINSTALL, то в ответ на DIF_INSTALLDEVICE установщики классов должны возвращать NO_ERROR, а установщики классов должны возвращать NO_ERROR или ERROR_DI_DO_DEFAULT.

DI_FLAGSEX_USECLASSFORCOMPAT

Фильтрация INF-файлов в классе установки устройства при создании списка совместимых драйверов. Если класс установки устройства известен, установка этого флага сокращает время, необходимое для создания списка совместимых драйверов при поиске INF-файлов, которые не предварительно компилируются. Этот флаг игнорируется, если задано DI_COMPAT_FROM_CLASS.

Следующие флаги доступны только для чтения; Только операционная система задает следующие флаги:

DI_FLAGSEX_CI_FAILED

Устанавливается операционной системой, если установщик класса не удалось загрузить или запустить. Этот флаг доступен только для чтения.

DI_FLAGSEX_DIDCOMPATINFO

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

DI_FLAGSEX_DIDINFOLIST

Windows создал список узлов драйверов, включающих все драйверы, перечисленные в INF-файлах указанного класса установки. Если указанный класс установки NULL, так как набор HDEVINFO или устройство не имеет связанного класса, список включает все узлы драйверов из всех доступных INF-файлов. Этот флаг доступен только для чтения.

DI_FLAGSEX_IN_SYSTEM_SETUP

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

Следующие флаги зарезервированы и не должны использоваться:

DI_FLAGSEX_ALTPLATFORM_DRVSEARCH

DI_FLAGSEX_BACKUPONREPLACE

DI_FLAGSEX_DEVICECHANGE

DI_FLAGSEX_OLDINF_IN_CLASSLIST

DI_FLAGSEX_PREINSTALLBACKUP

DI_FLAGSEX_RESTART_DEVICE_ONLY

DI_FLAGSEX_USEOLDINFSEARCH

Следующие флаги устарели:

DI_FLAGSEX_AUTOSELECTRANK0

DI_FLAGSEX_NOUIONQUERYREMOVE

hwndParent

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

InstallMsgHandler

Обратный вызов, используемый для обработки событий во время копирования файлов. Установщик может использовать обратный вызов, например, для выполнения специальной обработки при фиксации очереди файлов.

InstallMsgHandlerContext

Частные данные, используемые обратным вызовом InstallMsgHandler.

FileQueue

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

Если вы связываете очередь файлов с набором сведений об устройстве (SetupDiSetDeviceInstallParams), перед удалением набора сведений об устройстве необходимо отключить очередь от набора сведений об устройстве. Если не удается отключить очередь файлов, Windows не может уменьшать количество ссылок в наборе сведений об устройстве и не может освободить память.

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

ClassInstallReserved

Указатель на данные установщика классов. Совместно используемые установщики не должны использовать это поле.

Reserved

Скрытный. Только для внутреннего использования.

DriverPath[MAX_PATH]

Этот путь используется функцией SetupDiBuildDriverInfoList.

Замечания

Заметка

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

Требования

Требование	Ценность
заголовка	setupapi.h (include Setupapi.h)

См. также

SetupDiBuildClassInfoList

SetupDiBuildDriverInfoList

SetupDiCallClassInstaller

SetupDiGetDeviceInstallParams

SetupDiInstallDevice

SetupDiSelectDevice

SetupDiSetDeviceInstallParams

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

структура SP_DEVINSTALL_PARAMS_A (setupapi.h)

Синтаксис

Члены

DI_CLASSINSTALLPARAMS

DI_COMPAT_FROM_CLASS

DI_DRIVERPAGE_ADDED

DI_DONOTCALLCONFIGMG

DI_ENUMSINGLEINF

DI_INF_IS_SORTED

DI_INSTALLDISABLED

DI_NEEDREBOOT

DI_NEEDRESTART

DI_NOBROWSE

DI_NODI_DEFAULTACTION

DI_NOFILECOPY

DI_NOVCP

DI_NOWRITE_IDS

DI_PROPERTIES_CHANGE

DI_QUIETINSTALL

DI_RESOURCEPAGE_ADDED

DI_SHOWOEM

DI_USECI_SELECTSTRINGS

DI_DIDCLASS

DI_DIDCOMPAT

DI_MULTMFGS

DI_FLAGSEX_ALLOWEXCLUDEDDRVS

DI_FLAGSEX_ALWAYSWRITEIDS

DI_FLAGSEX_APPENDDRIVERLIST

DI_FLAGSEX_DRIVERLIST_FROM_URL

DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS

DI_FLAGSEX_FILTERCLASSES

DI_FLAGSEX_FILTERSIMILARDRIVERS

DI_FLAGSEX_FINISHINSTALL_ACTION

DI_FLAGSEX_INET_DRIVER

DI_FLAGSEX_INSTALLEDDRIVER

DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE

DI_FLAGSEX_NO_DRVREG_MODIFY

DI_FLAGSEX_POWERPAGE_ADDED

DI_FLAGSEX_PROPCHANGE_PENDING

DI_FLAGSEX_RECURSIVESEARCH

DI_FLAGSEX_SEARCH_PUBLISHED_INFS

DI_FLAGSEX_SETFAILEDINSTALL

DI_FLAGSEX_USECLASSFORCOMPAT

DI_FLAGSEX_CI_FAILED

DI_FLAGSEX_DIDCOMPATINFO

DI_FLAGSEX_DIDINFOLIST

DI_FLAGSEX_IN_SYSTEM_SETUP

Замечания

Требования

См. также

Обратная связь

Дополнительные ресурсы