Skip to content

Latest commit

 

History

History
134 lines (95 loc) · 6.56 KB

nf-cfgmgr32-cm_register_notification.md

File metadata and controls

134 lines (95 loc) · 6.56 KB
Raw
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NF:cfgmgr32.CM_Register_Notification
CM_Register_Notification function (cfgmgr32.h)
The CM_Register_Notification function registers an application callback routine to be called when a PnP event of the specified type occurs.
CM_Register_Notification
CM_Register_Notification function [Device and Driver Installation]
cfgmgr32/CM_Register_Notification
devinst.cm_register_notification
devinst\cm_register_notification.htm
devinst
15847F9C-9F2A-453F-9EF8-0AF63CFF93C9
12/05/2018
CM_Register_Notification, CM_Register_Notification function [Device and Driver Installation], cfgmgr32/CM_Register_Notification, devinst.cm_register_notification
cfgmgr32.h
Cfgmgr32.h
Universal
Available in Microsoft Windows 8 and later versions of Windows.
Cfgmgr32.lib; OneCoreUAP.lib on Windows 10
CfgMgr32.dll
Windows
19H1
CM_Register_Notification
cfgmgr32/CM_Register_Notification
c++
APIRef
kbSyntax
DllExport
CfgMgr32.dll
API-MS-Win-devices-config-l1-1-0.dll
API-MS-Win-devices-config-l1-1-1.dll
CM_Register_Notification

CM_Register_Notification function

-description

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.

-parameters

-param pFilter [in]

Pointer to a CM_NOTIFY_FILTER structure.

-param pContext [in, optional]

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

-param pCallback [in]

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.

-param pNotifyContext [out]

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

-returns

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.

-see-also

CM_NOTIFY_ACTION

CM_NOTIFY_FILTER

CM_Unregister_Notification

RegisterDeviceNotification

Registering for Notification of Device Interface Arrival and Device Removal

Using Device Interfaces