SetupDiOpenDeviceInterfaceA function (setupapi.h)

Article
02/09/2023

The SetupDiOpenDeviceInterface function retrieves information about a device interface and adds the interface to the specified device information set for a local system or a remote system.

Syntax

WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parameters

[in] DeviceInfoSet

A pointer to a device information set that contains, or will contain, a device information element that represents the device that supports the interface to open.

[in] DevicePath

A pointer to a NULL-terminated string that supplies the name of the device interface to be opened. This name is a Win32 device path that is typically received in a PnP notification structure or obtained by a previous call to SetupDiEnumDeviceInterfaces and its related functions.

[in] OpenFlags

Flags that determine how the device interface element is to be opened. The only valid flag is as follows:

DIODI_NO_ADD

Specifies that the device information element for the underlying device will not be created if that element is not already present in the specified device information set. For more information, see the following Remarks section.

[out, optional] DeviceInterfaceData

A pointer to a caller-initialized SP_DEVICE_INTERFACE_DATA structure that receives the requested interface data. This pointer is optional and can be NULL. If a buffer is supplied, the caller must set the cbSize member of the structure to sizeof(SP_DEVICE_INTERFACE_DATA) before calling SetupDiOpenDeviceInterface. For more information, see the following Remarks section.

Return value

SetupDiOpenDeviceInterface returns TRUE if the function completed without error. If the function completed with an error, it returns FALSE and the error code for the failure can be retrieved by calling GetLastError.

Remarks

If a device interface element for the interface already exists in DeviceInfoSet, SetupDiOpenDeviceInterface updates the flags. Therefore, this function can be used to update 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 device information element for the underlying device is not already present in DeviceInfoSet, this function creates one and adds it to DeviceInfoSet.

If the function successfully opens the new device interface but the caller did not supply a valid structure in the DeviceInterfaceData parameter, the function will return FALSE and a subsequent call to GetLastError will return ERROR_INVALID_USER_BUFFER. However, in this situation, SetupDiOpenDeviceInterface does add the requested interface to the device information set.

If the new device interface is successfully opened, but the caller-supplied DeviceInterfaceData buffer is invalid, this function returns FALSE and GetLastError returns ERROR_INVALID_USER_BUFFER. The caller's buffer error does not prevent the interface from being opened.

If the DIODI_NO_ADD flag is specified for the OpenFlags parameter, and a device information element for the underlying device is not already present in the specified device information set, this function returns FALSE and GetLastError returns ERROR_NO_SUCH_DEVICE_INTERFACE.

When the application has finished using the information that SetupDiOpenDeviceInterface retrieved, the application must call SetupDiDeleteDeviceInterfaceData.

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK attribute can be passed in as the value of the DevicePath argument of the SetupDiOpenDeviceInterface function.

Note

The setupapi.h header defines SetupDiOpenDeviceInterface 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

Share via