SetupDiRegisterDeviceInfo 函数 (setupapi.h)

  • 项目

SetupDiRegisterDeviceInfo 函数是DIF_REGISTERDEVICE请求的默认处理程序。

语法

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

参数

[in] DeviceInfoSet

设备信息集的句柄，其中包含表示要注册的设备的设备信息元素。 设备信息集不得包含任何远程元素。

[in, out] DeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，该结构指定 DeviceInfoSet 中的设备信息元素。 这是 IN-OUT 参数，因为 DeviceInfoData。返回时，DevInst 可能会使用新的句柄值进行更新。

[in] Flags

控制设备注册方式的标志值，可以是零或以下值：

SPRDI_FIND_DUPS

搜索与 DeviceInfoData 表示的设备相对应的以前存在的设备实例。 如果未指定此标志，则无论设备实例是否已存在，都会注册设备实例。

如果调用方提供 CompareProc，则调用方还必须设置此标志。

[in, optional] CompareProc

指向要用于重复检测的比较回调函数的指针。 此参数是可选的，可以为 NULL。 如果指定此参数，则会对与所注册的设备实例具有相同类的每个设备实例调用回调函数。 回调函数的原型如下所示：

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

如果 compare 函数发现两个设备是重复的，则必须返回ERROR_DUPLICATE_FOUND。 否则，它应返回NO_ERROR。 如果遇到其他错误，回调函数应返回相应的ERROR_* 代码以指示失败。

如果未指定 CompareProc 并请求重复检测，则使用默认比较行为。 默认设置是将新设备的检测签名与 类中所有其他设备的检测签名进行比较。 检测签名包含在设备启动日志配置的特定于类的资源描述符中。

[in, optional] CompareContext

指向传入回调函数的调用方提供的上下文缓冲区的指针。 如果未指定 CompareProc ，则忽略此参数。

[out, optional] DupDeviceInfoData

指向 SP_DEVINFO_DATA 结构的指针，用于接收因尝试注册此设备而发现的重复设备实例（如果有）的相关信息。 此参数是可选的，可以为 NULL。 如果指定此参数，则调用方必须设置 DupDeviceInfoData。cbSize 为 sizeof (SP_DEVINFO_DATA) 。 如果函数返回 FALSE，并且 GetLastError 返回ERROR_DUPLICATE_FOUND，则会填充此内容。 此设备信息元素将添加为指定 DeviceInfoSet 的成员（如果还不是成员）。 如果未指定 DupDeviceInfoData ，则不会将重复项添加到设备信息集中。

如果在处理 DIF_REGISTERDEVICE 请求时调用此函数， 则 DupDeviceInfoData 参数必须为 NULL。

返回值

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

注解

SetupDiRegisterDeviceInfo 主要用于向本地计算机上的 即插即用 (PnP) 管理器注册非 PnP 设备。 尽管如果设备信息集用于远程计算机， 则 SetupDiRegisterDeviceInfo 不会失败，但结果是有限的，因为设备信息集随后无法与不支持远程计算机上的操作的 DIF_Xxx 安装请求或 SetupDiXxx 函数一起使用。 例如，调用 SetupDiCreateDevRegKey 为远程计算机上新注册的设备执行 INF 部分将失败。

注意 只有类安装程序应调用 SetupDiRegisterDeviceInfo ，并且仅在类安装程序必须在 SetupDiRegisterDeviceInfo 完成默认设备注册操作后执行设备注册操作的情况下调用。 在这种情况下，当安装程序处理DIF_REGISTERDEVICE请求时，类安装程序必须直接调用 SetupDiRegisterDeviceInfo 。 有关调用默认处理程序的详细信息，请参阅 调用默认 DIF 代码处理程序。
 
注册设备信息元素后，调用方应更新与此设备关联的 DevInst 句柄的任何存储副本。 这是必需的，因为在注册期间句柄值可能已更改。 调用方不必再次检索SP_DEVINFO_DATA结构，因为结构的 DevInst 字段会更新以反映句柄的当前值。

不要直接为 PnP 设备实例调用此函数。 PnP 设备实例由操作系统自动注册。 但是，必须通过以下方式之一注册非 PnP 设备实例：

  1. 如果安装应用程序使用 DIF_DETECT 请求成功检测设备，则它还应使用DIF_REGISTERDEVICE请求来注册设备实例。 应以默认方式处理请求。 (默认情况下， SetupDiCallClassInstaller 首先调用类安装程序和类辅助安装程序来执行重复检测并注册设备实例。如果这些安装程序未注册设备实例， SetupDiCallClassInstaller 会调用 SetupDiRegisterDeviceInfo 来执行重复检测并注册设备实例。)
  2. 例如，如果安装应用程序 (通过调用 SetupDiCreateDeviceInfo) 创建设备实例，但不执行重复检测，则安装应用程序应使用DIF_REGISTERDEVICE请求来注册设备实例。 应按前面所述的默认方式处理请求。
  3. 如果安装应用程序创建新设备并执行重复检测，则安装应用程序应使用DIF_REGISTERDEVICE请求，但应阻止 SetupDiCallClassInstaller 调用 SetupDiRegisterDeviceInfo。 若要防止 SetupDiCallClassInstaller 调用 SetupDiRegisterDeviceInfo，请在设备实例的 SP_DEVINSTALL_PARAMS 结构的 Flags 成员中设置DI_NODI_DEFAULTACTION标志。

    如果 SetupDiCallClassInstaller 为DIF_REGISTERDEVICE请求返回 TRUE ，则类安装程序或类辅助安装程序已注册设备实例。 在这种情况下，安装应用程序可以继续安装设备。

    如果 SetupDiCallClassInstaller 为DIF_REGISTERDEVICE请求返回 FALSE ，则类安装程序或类辅助安装程序未注册设备实例。 在这种情况下，安装应用程序应执行以下操作之一，具体取决于 GetLastError 为请求返回的最后一个错误：

    • 如果最后一个错误ERROR_DI_DO_DEFAULT，则安装应用程序可以直接调用 SetupDiRegisterDeviceInfo 并提供 CompareProc 来执行重复检测。 如果此调用成功且未找到重复项，则设备安装可以继续。 如果找到重复项， SetupDiRegisterDeviceInfo 将返回 FALSE，并且安装应用程序必须终止设备安装。
    • 如果未ERROR_DI_DO_DEFAULT最后一个错误，则安装应用程序必须终止设备安装。
    SetupDiRegisterDeviceInfo 的调用方必须是 Administrators 组的成员。

要求

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

另请参阅

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS