SetupDiOpenDeviceInfoW function (setupapi.h)
The SetupDiOpenDeviceInfo function adds a device information element for a device instance to a device information set, if one does not already exist in the device information set, and retrieves information that identifies the device information element for the device instance in the device information set.
Syntax
WINSETUPAPI BOOL SetupDiOpenDeviceInfoW(
[in] HDEVINFO DeviceInfoSet,
[in] PCWSTR DeviceInstanceId,
[in, optional] HWND hwndParent,
[in] DWORD OpenFlags,
[out, optional] PSP_DEVINFO_DATA DeviceInfoData
);
Parameters
[in] DeviceInfoSet
A handle to the device information set to which SetupDiOpenDeviceInfo adds a device information element, if one does not already exist, for the device instance that is specified by DeviceInstanceId.
[in] DeviceInstanceId
A pointer to a NULL-terminated string that supplies the device instance identifier of a device (for example, "Root*PNP0500\0000"). If DeviceInstanceId is NULL or references a zero-length string, SetupDiOpenDeviceInfo adds a device information element to the supplied device information set, if one does not already exist, for the root device in the device tree.
[in, optional] hwndParent
The handle to the top-level window to use for any user interface related to installing the device.
[in] OpenFlags
A variable of DWORD type that controls how the device information element is opened. The value of this parameter can be one or more of the following:
DIOD_CANCEL_REMOVE
If this flag is specified and the device had been marked for pending removal, the operating system cancels the pending removal.
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.
[out, optional] DeviceInfoData
A pointer to a caller-supplied SP_DEVINFO_DATA structure that receives information about the device information element for the device instance that is specified by DeviceInstanceId. The caller must set cbSize to sizeof(SP_DEVINFO_DATA). This parameter is optional and can be NULL.
Return value
SetupDiOpenDeviceInfo returns TRUE if it is successful. Otherwise, the function returns FALSE and the logged error can be retrieved with a call to GetLastError.
Remarks
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.
Note
The setupapi.h header defines SetupDiOpenDeviceInfo 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 |
|---|---|
| Minimum supported client | Available in Microsoft Windows 2000 and later versions of Windows. |
| Target Platform | Desktop |
| Header | setupapi.h (include Setupapi.h) |
| Library | Setupapi.lib |
| API set | ext-ms-win-setupapi-classinstallers-l1-1-1 (introduced in Windows 8.1) |