CM_Register_Notification 函数 (cfgmgr32.h)

项目
03/05/2024

CM_Register_Notification 函数注册在发生指定类型的 PnP 事件时要调用的应用程序回调例程。

如果你的代码面向 Windows 7 或更早版本的 Windows，请使用 RegisterDeviceNotification 而不是 CM_Register_Notification 。内核模式调用方应改用 IoRegisterPlugPlayNotification 。

语法

CMAPI CONFIGRET CM_Register_Notification(
  [in]           PCM_NOTIFY_FILTER   pFilter,
  [in, optional] PVOID               pContext,
  [in]           PCM_NOTIFY_CALLBACK pCallback,
  [out]          PHCMNOTIFICATION    pNotifyContext
);

参数

[in] pFilter

指向 CM_NOTIFY_FILTER 结构的指针。

[in, optional] pContext

指向调用方分配的缓冲区的指针，该缓冲区包含要传递到 pCallback 中的回调例程的上下文。

[in] pCallback

指向在指定 PnP 事件发生时要调用的例程的指针。有关回调函数的原型，请参阅 “备注 ”部分。

回调例程的 Action 参数将是 CM_NOTIFY_ACTION 枚举中的值。

收到通知后，回调检查通知的方式将取决于回调例程的 EventData 参数的 FilterType 成员：

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

回调应检查 EventData-u.DeviceInterface>。

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

回调应检查 EventData-u.DeviceHandle>。

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

回调应检查 EventData-u.DeviceInstance>。

[out] pNotifyContext

用于接收对应于注册调用的 HCMNOTIFICATION 句柄的指针。

返回值

如果操作成功，函数将返回CR_SUCCESS。否则，它将返回 Cfgmgr32.h 中定义的CR_前缀错误代码之一。

注解

请确保尽快处理即插即用设备事件。如果事件处理程序执行的任何操作可能会阻止执行 (（例如 I/O) ），则最好启动另一个线程以异步方式执行该操作。

CM_Register_Notification 函数不提供现有设备接口的通知。若要检索现有接口，请先调用 CM_Register_Notification，然后调用 CM_Get_Device_Interface_List。如果在驱动程序调用 CM_Register_Notification之后启用接口，但在驱动程序调用 CM_Get_Device_Interface_List之前，驱动程序会收到接口到达的通知，并且接口也会显示在 CM_Get_Device_Interface_List返回的设备接口实例列表中。

当CM_Register_Notification返回的 HCMNOTIFICATION 句柄不再需要时，必须通过调用 CM_Unregister_Notification 函数将其关闭。

回调例程使用以下函数原型：

typedef __callback DWORD (CALLBACK *PCM_NOTIFY_CALLBACK)(
    _In_ HCMNOTIFICATION       hNotify,
    _In_opt_ PVOID             Context,
    _In_ CM_NOTIFY_ACTION      Action,
    _In_reads_bytes_(EventDataSize) PCM_NOTIFY_EVENT_DATA EventData,
    _In_ DWORD                 EventDataSize
    );

如果响应 CM_NOTIFY_ACTION_DEVICEQUERYREMOVE 通知，PCM_NOTIFY_CALLBACK回调应根据需要返回ERROR_SUCCESS或ERROR_CANCELLED。否则，回调应返回ERROR_SUCCESS。回调不应返回任何其他值。有关其他操作的说明，请参阅 CM_NOTIFY_ACTION 文档。另请参阅 CM_NOTIFY_EVENT_DATA ，了解有关此回调在 EventData 参数中接收的结构的信息。

示例

有关示例，请参阅注册设备接口到达和设备删除通知。

要求

要求	值
最低受支持的客户端	在 Microsoft Windows 8 及更高版本的 Windows 中可用。
目标平台	通用
标头	cfgmgr32.h (包括 Cfgmgr32.h)
Library	Cfgmgr32.lib;Windows 10 上的 OneCoreUAP.lib
DLL	CfgMgr32.dll