SetupDiOpenDeviceInfoA 函数 (setupapi.h)

项目
03/05/2024

如果设备信息集中尚不存在设备信息元素， SetupDiOpenDeviceInfo 函数会将设备实例的设备信息元素添加到设备信息集中，并检索标识设备信息集中设备实例的设备信息元素的信息。

语法

WINSETUPAPI BOOL SetupDiOpenDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceInstanceId,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            OpenFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

参数

[in] DeviceInfoSet

设备信息集的句柄， SetupDiOpenDeviceInfo 为 DeviceInstanceId 指定的设备实例添加设备信息元素（如果尚不存在）。

[in] DeviceInstanceId

指向以 NULL 结尾的字符串的指针，该字符串提供设备实例标识符， (例如“Root*PNP0500\0000”) 。如果 DeviceInstanceId 为 NULL 或引用长度为零的字符串， 则 SetupDiOpenDeviceInfo 会将设备信息元素添加到设备树中根设备的信息集（如果尚不存在）。

[in, optional] hwndParent

顶级窗口的句柄，用于与安装设备相关的任何用户界面。

[in] OpenFlags

一个 DWORD 类型的变量，用于控制设备信息元素的打开方式。此参数的值可以是以下一个或多个值：

DIOD_CANCEL_REMOVE

如果指定了此标志，并且设备已标记为待删除，操作系统将取消挂起的删除。

DIOD_INHERIT_CLASSDRVS

如果指定了此标志，则生成的设备信息元素将继承与设备信息集关联的类驱动程序列表（如果有）。此外，如果为设备信息集选择了驱动程序，则会为新设备信息元素选择相同的驱动程序。

如果设备信息元素已存在，则其类驱动程序列表（如果有）将替换为继承的列表。

[out, optional] DeviceInfoData

指向调用方提供的 SP_DEVINFO_DATA 结构的指针，该结构接收有关 DeviceInstanceId 指定的设备实例的设备信息元素的信息。调用方必须将 cbSize 设置为 sizeof (SP_DEVINFO_DATA) 。此参数是可选的，可以为 NULL。

返回值

如果 SetupDiOpenDeviceInfo 成功，则返回 TRUE 。否则，函数返回 FALSE ，并且可以通过调用 GetLastError 来检索记录的错误。

注解

如果将此设备实例添加到具有关联类的集中，则设备类必须相同，否则调用将失败。在这种情况下，对 GetLastError 的调用将返回ERROR_CLASS_MISMATCH。

如果新设备信息元素已成功打开，但调用方提供的 DeviceInfoData 缓冲区无效，则此函数返回 FALSE。在这种情况下，对 GetLastError 的调用将返回ERROR_INVALID_USER_BUFFER。但是，设备信息元素将添加为集的新成员。

注意

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

要求

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