SetupDiOpenDeviceInterface

The SetupDiOpenDeviceInterface function retrieves information about an existing device interface and adds it to the specified device information set. This function creates a device information instance for the underlying device if an instance is not already present in the device information set.

BOOL SetupDiOpenDeviceInterface(
  HDEVINFO DeviceInfoSet,
  PCTSTR DevicePath,
  DWORD OpenFlags,
  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parameters

DeviceInfoSet

[in] Pointer to a device information set that contains, or will contain, the device that exposes the interface to be opened.

DevicePath

[in] Pointer to a string containing the name of the device interface to be opened. This name is a Win32 device path typically received in a PnP notification structure or through a call to the SetupDiEnumDeviceInterfaces function.

OpenFlags

Reserved; must be zero.

DeviceInterfaceData

[out] An optional pointer to a buffer that receives a completed SP_DEVICE_INTERFACE_DATA structure that identifies the interface. You must set the cbSize member to sizeof(SP_DEVICE_INTERFACE_DATA) before calling this function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If a device interface instance for the interface already exists in the DeviceInfoSet parameter, SetupDiOpenDeviceInterface updates the flags. Therefore, this function can be used to refresh the flags for a device interface. For example, an interface might have been inactive when it was first opened, but has subsequently become active.

If the new device interface is successfully opened, but the DeviceInterfaceData buffer is invalid, this function returns FALSE and GetLastError returns ERROR_INVALID_USER_BUFFER. This error does not prevent the interface from being opened.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 98.
  Header: Declared in Setupapi.h.
  Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiEnumDeviceInterfaces, SP_DEVICE_INTERFACE_DATA