通过

SetupDiOpenDeviceInterfaceA 函数 （setupapi.h）

  • 项目

SetupDiOpenDeviceInterface 函数检索有关设备接口的信息，并将接口添加到本地系统或远程系统的指定设备信息集。

语法

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

参数

[in] DeviceInfoSet

指向 设备信息集的指针，该信息集 包含或将包含一个表示支持打开接口的设备的设备信息元素。

[in] DevicePath

指向 NULL 终止的字符串的指针，该字符串提供要打开的设备接口的名称。 此名称是 Win32 设备路径，通常在 PnP 通知结构中接收，或通过先前调用 SetupDiEnumDeviceInterfaces 及其相关功能获取。

[in] OpenFlags

确定如何打开设备接口元素的标志。 唯一有效的标志如下所示：

DIODI_NO_ADD

指定如果指定的 设备信息集中中尚不存在该元素，则不会创建基础设备的设备信息元素。 有关详细信息，请参阅以下 备注 部分。

[out, optional] DeviceInterfaceData

指向调用方初始化的 SP_DEVICE_INTERFACE_DATA 结构的指针，该结构接收请求的接口数据。 此指针是可选的，可以 NULL。 如果提供了缓冲区，调用方必须在调用 SetupDiOpenDeviceInterface之前，将结构的 cbSize 成员设置为 sizeof（SP_DEVICE_INTERFACE_DATA）。 有关详细信息，请参阅以下 备注 部分。

返回值

SetupDiOpenDeviceInterface 在函数完成时返回 true（如果函数未出错）。 如果函数以错误完成，则返回 FALSE，可以通过调用 getLastError来检索失败的错误代码。

言论

如果 DeviceInfoSet中已存在接口的设备接口元素，SetupDiOpenDeviceInterface 更新标志。 因此，此函数可用于更新设备接口的标志。 例如，首次打开接口时可能处于非活动状态，但随后会变为活动状态。 如果基础设备的设备信息元素尚未存在于 DeviceInfoSet中，此函数将创建一个元素并将其添加到 deviceInfoSet。

如果函数成功打开新设备接口，但调用方未在 DeviceInterfaceData 参数中提供有效结构，该函数将返回 FALSE，后续调用 GetLastError 将返回ERROR_INVALID_USER_BUFFER。 但是，在这种情况下，SetupDiOpenDeviceInterface 会向设备信息集添加请求的接口。

如果新设备接口已成功打开，但调用方提供的 DeviceInterfaceData 缓冲区无效，则此函数返回 FALSE，GetLastError 返回ERROR_INVALID_USER_BUFFER。 调用方的缓冲区错误不会阻止打开接口。

如果为 OpenFlags 参数指定了DIODI_NO_ADD标志，并且基础设备的设备信息元素尚未存在于指定的 设备信息集中，则此函数将返回 FALSE，GetLastError 返回ERROR_NO_SUCH_DEVICE_INTERFACE。

应用程序使用 SetupDiOpenDeviceInterface 检索到的信息后， 应用程序必须调用 setupDiDeleteDeviceInterfaceData。

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK 属性可以作为 SetupDiOpenDeviceInterface 函数的 DevicePath 参数的值传入。

注意

setupapi.h 标头将 SetupDiOpenDeviceInterface 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Microsoft Windows 2000 及更高版本的 Windows 中可用。
目标平台 桌面
标头 setupapi.h （包括 Setupapi.h）
库 Setupapi.lib

另请参阅

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces