Share via

SwDeviceCreate 函数 (swdevice.h)

  • 项目

启动软件设备的枚举。

语法

HRESULT SwDeviceCreate(
  [in]           PCWSTR                      pszEnumeratorName,
  [in]           PCWSTR                      pszParentDeviceInstance,
  [in]           const SW_DEVICE_CREATE_INFO *pCreateInfo,
  [in]           ULONG                       cPropertyCount,
  [in, optional] const DEVPROPERTY           *pProperties,
  [in]           SW_DEVICE_CREATE_CALLBACK   pCallback,
  [in, optional] PVOID                       pContext,
  [out]          PHSWDEVICE                  phSwDevice
);

参数

[in] pszEnumeratorName

一个字符串，用于命名软件设备的枚举器。 选择表示枚举设备的组件的名称。

[in] pszParentDeviceInstance

一个字符串，指定作为软件设备的父级的设备的设备实例 ID。

这可以是 HTREE\ROOT\0，但我们建议将根设备的子级保留为最少。 我们还建议软件设备的首选父级是软件设备扩展其功能的真实设备。 在软件设备没有此类自然父级的情况下，请创建一个设备作为根的子级，以收集组件将枚举的所有软件设备;然后，将实际软件设备枚举为此设备分组节点的子级。 这会将根设备的子级保留为一个可管理的数字。

[in] pCreateInfo

指向 SW_DEVICE_CREATE_INFO 结构的指针，该结构描述 PnP 用于创建设备的信息。

[in] cPropertyCount

pProperties 数组中的 DEVPROPERTY 结构数。

[in, optional] pProperties

DEVPROPERTY 结构的可选数组。 这些属性在创建设备后但在发送已创建设备的通知之前在设备上设置。 有关详细信息，请参阅备注。 此指针可以为 NULL。

[in] pCallback

操作系统在 PnP 枚举设备后调用的 SW_DEVICE_CREATE_CALLBACK 回调函数。

[in, optional] pContext

操作系统传递给回调函数的可选客户端上下文。 此指针可以为 NULL。

[out] phSwDevice

指向变量的指针，该变量接收表示设备的 HSWDEVICE 句柄。 在客户端应用希望 PnP 删除设备后，调用 SwDeviceClose 关闭此句柄。


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

返回值

如果成功启动设备枚举，则返回S_OK。 这并不意味着已成功枚举设备。 检查SW_DEVICE_CREATE_CALLBACK回调函数的 CreateResult 参数以确定设备是否已成功枚举。

注解

SwDeviceCreate 返回表示设备的句柄。 关闭此句柄后，PnP 将删除设备。

调用进程必须具有管理员访问权限才能启动软件设备的枚举。

PnP 将软件设备的设备实例 ID 形成为“SWD<pszEnumeratorName><pszInstanceId>“，但此字符串可能会更改，或者 PnP 可能会修饰名称。 始终从回调函数获取设备实例 ID。

作为 SwDeviceCreate 调用的一部分设置的属性与稍后通过调用 SwDevicePropertySet 设置的属性之间存在细微差别。 作为 SwDeviceCreate 的一部分设置的属性存储在内存中;如果设备已卸载或 null 驱动程序擦除属性存储，则当 PnP 重新枚举设备时，软件设备 API 功能会再次写出这些属性。 这对客户端都是透明的。 枚举后使用 SwDevicePropertySet 设置的属性不会保留在内存中。 但是，如果使用 SwDeviceCreate 设置属性，则可以使用 SwDevicePropertySet 更新值，此更新将应用于内存中值以及持久存储。

建议尽可能将所有属性指定为对 SwDeviceCreate 的 调用的一部分，并为每次调用 SwDeviceCreate 指定这些属性。

注意操作系统可能会在对 SwDeviceCreate 的调用返回之前调用 SW_DEVICE_CREATE_CALLBACK。 出于此原因，设备的软件设备句柄作为参数提供给回调函数。
 
可以将软件设备创建为当时不存在的父级的子级。 PnP 将在父设备出现后枚举软件设备。

要求

要求 值
最低受支持的客户端 Windows 8
最低受支持的服务器 Windows Server 2012
目标平台 通用
标头 swdevice.h
Library Swdevice.lib;Windows 10 上的 OneCoreUAP.lib
DLL Cfgmgr32.dll

另请参阅

SW_DEVICE_CREATE_CALLBACK