SetupDiOpenDeviceInfo

SetupDiOpenDeviceInfo

BOOLEAN
SetupDiOpenDeviceInfo(
IN HDEVINFO DeviceInfoSet,
IN PCTSTR DeviceInstanceId,
IN HWND hwndParent, /* optional */
IN DWORD OpenFlags
OUT PSP_DEVINFO_DATA DeviceInfoData /* optional */
);

SetupDiOpenDeviceInfo retrieves information about an existing device instance and adds it to the specified device information set. If a device information element already exists for this device instance, the function returns the existing element.

Parameters

DeviceInfoSet

Supplies a handle to a device information set to which the opened device information element should be added.

DeviceInstanceId

Supplies the ID of the device instance. This is the registry path relative to the Enum path of the device instance key. For example, Root\*PNP0500\0000.

hwndParent

Supplies the window handle of the top-level window to use for any user interface related to installing the device.

OpenFlags

Controls how the device information element is opened. Can be the following:

DIOD_INHERIT_CLASSDRVS

If this flag is specified, the resulting device information element inherits the class driver list, if any, associated with the device information set. In addition, if there is a selected driver for the device information set, that same driver is selected for the new device information element.

If the device information element was already present, its class driver list, if any, is replaced with the inherited list.

DeviceInfoData

Supplies a pointer to a variable that receives a context structure that is initialized for the newly-opened device information element.

Return Value

The function returns TRUE if it is successful. Otherwise it returns FALSE and the logged error can be retrieved with a call to GetLastError.

Comments

If this device instance is being added to a set that has an associated class, the device class must be the same or the call will fail. In this case, a call to GetLastError returns ERROR_CLASS_MISMATCH.

If the new device information element is successfully opened but the caller-supplied DeviceInfoData buffer is invalid, this function returns FALSE. In this case, a call to GetLastError returns ERROR_INVALID_USER_BUFFER. However, the device information element is added as a new member of the set anyway.