SP_DEVINSTALL_PARAMS_A structure (setupapi.h)

An SP_DEVINSTALL_PARAMS structure contains device installation parameters associated with a particular device information element or associated globally with a device information set.

Syntax

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;

Members

cbSize

The size, in bytes, of the SP_DEVINSTALL_PARAMS structure.

Flags

Flags that control installation and user interface operations. Some flags can be set before sending the device installation request while other flags are set automatically during the processing of some requests. Flags can be a combination of the following values.

The flag values are listed in groups: writable by device installation applications and installers, read-only (only set by the OS), reserved, and obsolete. The first group lists flags that are writable:

DI_CLASSINSTALLPARAMS

Set to use the Class Install parameters. SetupDiSetClassInstallParams sets this flag when the caller specifies parameters and clears the flag when the caller specifies a NULL parameters pointer.

DI_COMPAT_FROM_CLASS

Set to force SetupDiBuildDriverInfoList to build a device's list of compatible drivers from its class driver list instead of the INF file.

DI_DRIVERPAGE_ADDED

Set by a class installer or co-installer if the installer supplies a page that replaces the system-supplied driver properties page. If this flag is set, the operating system does not display the system-supplied driver page.

DI_DONOTCALLCONFIGMG

Set if the configuration manager should not be called to remove or reenumerate devices during the execution of certain device installation functions (for example, SetupDiInstallDevice).

If this flag is set, device installation applications, class installers, and co-installers must not call the following functions:

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

Set if installers and other device installation components should only search the INF file specified by SP_DEVINSTALL_PARAMS.DriverPath. If this flag is set, DriverPath contains the path of a single INF file instead of a path of a directory.

DI_INF_IS_SORTED

Set to indicate that the Select Device page should list drivers in the order in which they appear in the INF file, instead of sorting them alphabetically.

DI_INSTALLDISABLED

Set if the device should be installed in a disabled state by default. To be recognized, this flag must be set before Windows calls the default handler for the DIF_INSTALLDEVICE request.

DI_NEEDREBOOT

For NT-based operating systems, this flag is set if the device requires that the computer be restarted after device installation or a device state change. A class installer or co-installer can set this flag at any time during device installation, if the installer determines that a restart is necessary.

DI_NEEDRESTART

The same as DI_NEEDREBOOT.

DI_NOBROWSE

Set to disable browsing when the user is selecting an OEM disk path. A device installation application sets this flag to constrain a user to only installing from the installation media location.

DI_NODI_DEFAULTACTION

Set if SetupDiCallClassInstaller should not perform any default action if the class installer returns ERR_DI_DO_DEFAULT or there is not a class installer.

DI_NOFILECOPY

Set if device installation applications and components, such as SetupDiInstallDevice, should skip file copying.

DI_NOVCP

Set to disable creation of a new copy queue. Use the caller-supplied copy queue in SP_DEVINSTALL_PARAMS.FileQueue.

DI_NOWRITE_IDS

Set to prevent SetupDiInstallDevice from writing the INF-specified hardware IDs and compatible IDs to the device properties for the device node (devnode). This flag should only be set for root-enumerated devices.

This flag overrides the DI_FLAGSEX_ALWAYSWRITEIDS flag.

DI_PROPERTIES_CHANGE

Set by Device Manager if a device's properties were changed, which requires an update of the installer's user interface.

DI_QUIETINSTALL

Set if the device installer functions must be silent and use default choices wherever possible. Class installers and co-installers must not display any UI if this flag is set.

DI_RESOURCEPAGE_ADDED

Set by a class installer or co-installer if the installer supplies a page that replaces the system-supplied resource properties page. If this flag is set, the operating system does not display the system-supplied resource page.

DI_SHOWOEM

Set to allow support for OEM disks. If this flag is set, the operating system presents a "Have Disk" button on the Select Device page. This flag is set, by default, in system-supplied wizards.

DI_USECI_SELECTSTRINGS

Set if a class installer or co-installer supplied strings that should be used during SetupDiSelectDevice.

The following flags are read-only (only set by the OS):

DI_DIDCLASS

Set if SetupDiBuildDriverInfoList has already built a list of the drivers for this class of device. If this list has already been built, it contains all the driver information and this flag is always set. SetupDiDestroyDriverInfoList clears this flag when it deletes a list of drivers for a class.

This flag is read-only. Only the operating system sets this flag.

DI_DIDCOMPAT

Set if SetupDiBuildDriverInfoList has already built a list of compatible drivers for this device. If this list has already been built, it contains all the driver information and this flag is always set. SetupDiDestroyDriverInfoList clears this flag when it deletes a compatible driver list.

This flag is only set in device installation parameters that are associated with a particular device information element, not in parameters for a device information set as a whole.

This flag is read-only. Only the operating system sets this flag.

DI_MULTMFGS

Set by SetupDiBuildDriverInfoList if a list of drivers for a device setup class contains drivers that are provided by multiple manufacturers.

This flag is read-only. Only the operating system sets this flag.

The following flags are reserved:

DI_AUTOASSIGNRES

DI_DISABLED

DI_FORCECOPY

DI_GENERALPAGE_ADDED

DI_OVERRIDE_INFFLAGS

DI_SHOWALL

DI_SHOWCLASS

DI_SHOWCOMPAT

The following flags are obsolete:

DI_NOSELECTICONS

DI_PROPS_NOCHANGEUSAGE

FlagsEx

Additional flags that provide control over installation and user interface operations. Some flags can be set before calling the device installer functions while other flags are set automatically during the processing of some functions. FlagsEx can be a combination of the following values.

The flag values are listed in groups: writable by device installation applications and installers, read-only (only set by the OS), reserved, and obsolete.

The first group lists flags that are writable:

DI_FLAGSEX_ALLOWEXCLUDEDDRVS

If set, include drivers that were marked "Exclude From Select."

For example, if this flag is set, SetupDiSelectDevice displays drivers that have the Exclude From Select state and SetupDiBuildDriverInfoList includes Exclude From Select drivers in the requested driver list.

A driver is "Exclude From Select" if either it is marked ExcludeFromSelect in the INF file or it is a driver for a device whose whole setup class is marked NoInstallClass or NoUseClass in the class installer INF. Drivers for PnP devices are typically "Exclude From Select"; PnP devices should not be manually installed. To build a list of driver files for a PnP device a caller of SetupDiBuildDriverInfoList must set this flag.

DI_FLAGSEX_ALWAYSWRITEIDS

If set and the DI_NOWRITE_IDS flag is clear, always write hardware and compatible IDs to the device properties for the devnode. This flag should only be set for root-enumerated devices.

DI_FLAGSEX_APPENDDRIVERLIST

If set, SetupDiBuildDriverInfoList appends a new driver list to an existing list. This flag is relevant when searching multiple locations.

DI_FLAGSEX_DRIVERLIST_FROM_URL

If set, build the driver list from INF(s) retrieved from the URL that is specified in SP_DEVINSTALL_PARAMS.DriverPath. If the DriverPath is an empty string, use the Windows Update website.

Currently, the operating system does not support URLs. Use this flag to direct SetupDiBuildDriverInfoList to search the Windows Update website.

Do not set this flag if DI_QUIETINSTALL is set.

DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS

If set, do not include old Internet drivers when building a driver list. This flag should be set any time that you are building a list of potential drivers for a device. You can clear this flag if you are just getting a list of drivers currently installed for a device.

DI_FLAGSEX_FILTERCLASSES

If set, SetupDiBuildClassInfoList will check for class inclusion filters. This means that a device will not be included in the class list if its class is marked as NoInstallClass.

DI_FLAGSEX_FILTERSIMILARDRIVERS

(Windows XP and later.) If set, SetupDiBuildDriverInfoList includes "similar" drivers when building a class driver list. A "similar" driver is one for which one of the hardware IDs or compatible IDs in the INF file partially (or completely) matches one of the hardware IDs or compatible IDs of the hardware.

DI_FLAGSEX_FINISHINSTALL_ACTION

(Windows Vista and later.) See Marking a Device as having a Finish-Install Action to Perform for more information.

DI_FLAGSEX_INET_DRIVER

If set, the driver was obtained from the Internet. Windows will not use the device's INF to install future devices because Windows cannot guarantee that it can retrieve the driver files again from the Internet.

DI_FLAGSEX_INSTALLEDDRIVER

(Windows XP and later.) If set, SetupDiBuildDriverInfoList includes only the currently installed driver when creating a list of class drivers or device-compatible drivers.

DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE

(Windows XP and later.) If set, when creating a list of class drivers, SetupDiBuildDriverInfoList will not merge nodes in the driver list that are from the same INF and have the same driver description and rank.

DI_FLAGSEX_NO_DRVREG_MODIFY

Do not process the AddReg and DelReg entries for the device's hardware and software (driver) keys. That is, the AddReg and DelReg entries in the INF file DDInstall and DDInstall.HW sections.

DI_FLAGSEX_POWERPAGE_ADDED

If set, an installer added their own page for the power properties dialog. The operating system will not display the system-supplied power properties page. This flag is only relevant if the device supports power management.

DI_FLAGSEX_PROPCHANGE_PENDING

If set, the user made changes to one or more device property sheets. The property-page provider typically sets this flag.

When the user closes the device property sheet, Device Manager checks the DI_FLAGSEX_PROPCHANGE_PENDING flag. If it is set, Device Manager clears this flag, sets the DI_PROPERTIES_CHANGE flag, and sends a DIF_PROPERTYCHANGE request to the installers to notify them that something has changed.

DI_FLAGSEX_RECURSIVESEARCH

(Windows Vista and later.) If set, when SetupDiBuildDriverInfoList searches for INFs in the path specified in the DriverPath value, the search will be recursive.

DI_FLAGSEX_SEARCH_PUBLISHED_INFS

(Windows Vista and later.) If set, when SetupDiBuildDriverInfoList is used to search for INFs without an INF path or search path specified, this restricts the search to only INFs that have been imported into the Driver Store.

DI_FLAGSEX_SETFAILEDINSTALL

Set if the installation failed. If this flag is set, the SetupDiInstallDevice function just sets the FAILEDINSTALL flag in the device's ConfigFlags registry value. If DI_FLAGSEX_SETFAILEDINSTALL is set, co-installers must return NO_ERROR in response to DIF_INSTALLDEVICE, while class installers must return NO_ERROR or ERROR_DI_DO_DEFAULT.

DI_FLAGSEX_USECLASSFORCOMPAT

Filter INF files on the device's setup class when building a list of compatible drivers. If a device's setup class is known, setting this flag reduces the time that is required to build a list of compatible drivers when searching INF files that are not precompiled. This flag is ignored if DI_COMPAT_FROM_CLASS is set.

The following flags are read-only; only the operating system sets these flags:

DI_FLAGSEX_CI_FAILED

Set by the operating system if a class installer failed to load or start. This flag is read-only.

DI_FLAGSEX_DIDCOMPATINFO

Windows has built a list of driver nodes that are compatible with the device. This flag is read-only.

DI_FLAGSEX_DIDINFOLIST

Windows has built a list of driver nodes that includes all the drivers that are listed in the INF files of the specified setup class. If the specified setup class is NULL because the HDEVINFO set or device has no associated class, the list includes all driver nodes from all available INF files. This flag is read-only.

DI_FLAGSEX_IN_SYSTEM_SETUP

If set, installation is occurring during initial system setup. This flag is read-only.

The following flags are reserved and should not be used:

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

The following flags are obsolete:

DI_FLAGSEX_AUTOSELECTRANK0

DI_FLAGSEX_NOUIONQUERYREMOVE

hwndParent

Window handle that will own the user interface dialogs related to this device.

InstallMsgHandler

Callback used to handle events during file copying. An installer can use a callback, for example, to perform special processing when committing a file queue.

InstallMsgHandlerContext

Private data that is used by the InstallMsgHandler callback.

FileQueue

A handle to a caller-supplied file queue where file operations should be queued but not committed.

If you associate a file queue with a device information set (SetupDiSetDeviceInstallParams), you must disassociate the queue from the device information set before you delete the device information set. If you fail to disassociate the file queue, Windows cannot decrement its reference count on the device information set and cannot free the memory.

This queue is only used if the DI_NOVCP flag is set, indicating that file operations should be enqueued but not committed.

ClassInstallReserved

A pointer for class-installer data. Co-installers must not use this field.

Reserved

Reserved. For internal use only.

DriverPath[MAX_PATH]

This path is used by the SetupDiBuildDriverInfoList function.

Remarks

Note

The setupapi.h header defines SP_DEVINSTALL_PARAMS as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Header setupapi.h (include Setupapi.h)

See also

SetupDiBuildClassInfoList

SetupDiBuildDriverInfoList

SetupDiCallClassInstaller

SetupDiGetDeviceInstallParams

SetupDiInstallDevice

SetupDiSelectDevice

SetupDiSetDeviceInstallParams