SetupDiCreateDeviceInfoA 函数 (setupapi.h)

项目
08/26/2023

SetupDiCreateDeviceInfo 函数创建一个新的设备信息元素，并将其作为新成员添加到指定的设备信息集。

语法

WINSETUPAPI BOOL SetupDiCreateDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCSTR            DeviceDescription,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            CreationFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

参数

[in] DeviceInfoSet

为本地计算机设置的设备信息的句柄。

[in] DeviceName

指向以 NULL 结尾的字符串的指针，该字符串提供完整的设备实例 ID (例如，“Root*PNP0500\0000”) 或不带枚举器前缀和实例标识符后缀的根枚举设备 ID ， (例如“*PNP0500”) 。只有在 CreationFlags 参数中指定了DICD_GENERATE_ID标志时，才能使用根枚举的设备标识符。

[in] ClassGuid

指向设备的设备设置类 GUID 的指针。如果设备的设备设置类未知，请将 *ClassGuid 设置为GUID_NULL结构。

[in, optional] DeviceDescription

指向以 NULL 结尾的字符串的指针，该字符串提供设备的文本说明。此指针是可选的，可以为 NULL。

[in, optional] hwndParent

顶级窗口的句柄，用于与安装设备相关的任何用户界面。此句柄是可选的，可以为 NULL。

[in] CreationFlags

DWORD 类型的变量，用于控制如何创建设备信息元素。可以是以下值的组合：

DICD_GENERATE_ID

如果指定了此标志， 则 DeviceName 仅包含根枚举的设备 ID ，并且系统使用该 ID 为新设备信息元素生成完整的设备实例 ID 。

调用 SetupDiGetDeviceInstanceId 以检索为此设备信息元素生成的设备实例 ID。

DICD_INHERIT_CLASSDRVS

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

[out, optional] DeviceInfoData

指向接收新设备信息元素的 SP_DEVINFO_DATA 结构的指针。此指针是可选的，可以为 NULL。如果提供了结构，调用方必须在调用函数之前将此结构的 cbSize 成员设置为 sizeof (SP_DEVINFO_DATA) 。有关详细信息，请参阅以下 “备注” 部分。

返回值

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

注解

此函数的调用方必须是 Administrators 组的成员。

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

如果指定的设备实例与注册表中的现有设备实例项相同，则调用将失败。在这种情况下，对 GetLastError 的调用将返回ERROR_DEVINST_ALREADY_EXISTS。仅当未设置DICD_GENERATE_ID标志时，才会发生这种情况。

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

DeviceInfoSet 只能包含本地计算机上的元素。

注意

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

要求


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