SetupDiCreateDeviceInterfaceA 函数 (setupapi.h)

  • 项目

SetupDiCreateDeviceInterface 函数在本地系统或远程系统上注册设备接口。

语法

WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA          DeviceInfoData,
  [in]            const GUID                *InterfaceClassGuid,
  [in, optional]  PCSTR                     ReferenceString,
  [in]            DWORD                     CreationFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

参数

[in] DeviceInfoSet

设备信息集的句柄。 此集包含一个设备信息元素，该元素表示要为其注册接口的设备。 此句柄通常由 SetupDiGetClassDevs 返回。

[in] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构指定 DeviceInfoSet 中的设备信息元素。

[in] InterfaceClassGuid

指向类 GUID 的指针，该 GUID 指定新接口的接口类。

[in, optional] ReferenceString

指向提供引用字符串的以 NULL 结尾的字符串的指针。 此指针是可选的，可以为 NULL。 引用字符串仅由使用设备接口作为按需创建的软件设备的占位符的少数总线驱动程序使用。

[in] CreationFlags

保留。 必须为零。

[out, optional] DeviceInterfaceData

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

返回值

如果函数完成且未出错，SetupDiCreateDeviceInterface 将返回 TRUE。 如果函数完成时出现错误，它将返回 FALSE ，并且可以通过调用 GetLastError 来检索失败的错误代码。

注解

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

SetupDiCreateDeviceInterface 为设备注册接口。 如果设备有多个接口，请为注册的每个接口调用一次此函数。

如果此函数成功为与指定设备信息元素对应的设备注册接口，它还会将 接口添加到与指定设备信息集中的设备信息元素关联的接口列表。

在应用程序和其他系统组件可以使用已注册的接口之前，驱动程序必须为设备启用该接口。

此函数为新设备接口创建注册表项。 此函数的调用方可以使用 SetupDiOpenDeviceInterfaceRegKey 访问此密钥下的非易失性存储。

如果 SetupDiCreateDeviceInterface 成功创建新的设备接口，但 DeviceInterfaceData 参数中调用方提供的缓冲区无效，则此函数将返回 FALSE ，并且对 GetLastError 的后续调用将返回ERROR_INVALID_USER_BUFFER。 但是，函数会创建并注册新的设备接口。

注意

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

要求

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

另请参阅

SetupDiOpenDeviceInterfaceRegKey

SetupDiRemoveDeviceInterface