CM_Register_Notification function (cfgmgr32.h)

Article
10/13/2021

The CM_Register_Notification function registers an application callback routine to be called when a PnP event of the specified type occurs.

Use RegisterDeviceNotification instead of CM_Register_Notification if your code targets Windows 7 or earlier versions of Windows. Kernel mode callers should use IoRegisterPlugPlayNotification instead.

Syntax

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

Parameters

[in] pFilter

Pointer to a CM_NOTIFY_FILTER structure.

[in, optional] pContext

Pointer to a caller-allocated buffer containing the context to be passed to the callback routine in pCallback.

[in] pCallback

Pointer to the routine to be called when the specified PnP event occurs. See the Remarks section for the callback function's prototype.

The callback routine’s Action parameter will be a value from the CM_NOTIFY_ACTION enumeration.

Upon receiving a notification, how the callback examines the notification will depend on the FilterType member of the callback routine's EventData parameter:

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

The callback should examine EventData->u.DeviceInterface.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

The callback should examine EventData->u.DeviceHandle.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

The callback should examine EventData->u.DeviceInstance.

[out] pNotifyContext

Pointer to receive the HCMNOTIFICATION handle that corresponds to the registration call.

Return value

If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the CR_-prefixed error codes defined in Cfgmgr32.h.

Remarks

Be sure to handle Plug and Play device events as quickly as possible. If your event handler performs any operation that may block execution (such as I/O), it is best to start another thread to perform the operation asynchronously.

The CM_Register_Notification function does not provide notification of existing device interfaces. To retrieve existing interfaces, first call CM_Register_Notification, and then call CM_Get_Device_Interface_List. If the interface is enabled after your driver calls CM_Register_Notification, but before your driver calls CM_Get_Device_Interface_List, the driver receives a notification for the interface arrival, and the interface also appears in the list of device interface instances returned by CM_Get_Device_Interface_List.

HCMNOTIFICATION handles returned by CM_Register_Notification must be closed by calling the CM_Unregister_Notification function when they are no longer needed.

A callback routine uses the following function prototype:

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
    );

If responding to a CM_NOTIFY_ACTION_DEVICEQUERYREMOVE notification, the PCM_NOTIFY_CALLBACK callback should return either ERROR_SUCCESS or ERROR_CANCELLED, as appropriate. Otherwise, the callback should return ERROR_SUCCESS. The callback should not return any other values. For a description of other actions, please refer to the CM_NOTIFY_ACTION documentation. Also see CM_NOTIFY_EVENT_DATA for information about the structure that this callback receives in the EventData parameter.

Examples

For an example, see Registering for Notification of Device Interface Arrival and Device Removal.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows 8 and later versions of Windows.
Target Platform	Universal
Header	cfgmgr32.h (include Cfgmgr32.h)
Library	Cfgmgr32.lib; OneCoreUAP.lib on Windows 10
DLL	CfgMgr32.dll