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 成员设置为 size of (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)
Library Setupapi.lib

另请参阅

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces