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.
The CM_Register_Notification function registers an application callback routine to be called when a PnP event of the specified type occurs.
CMAPI CONFIGRET CM_Register_Notification( PCM_NOTIFY_FILTER pFilter, PVOID pContext, PCM_NOTIFY_CALLBACK pCallback, PHCMNOTIFICATION pNotifyContext );
Pointer to a CM_NOTIFY_FILTER structure.
Pointer to a caller-allocated buffer containing the context to be passed to the callback routine 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:
The callback should examine EventData->u.DeviceInterface.
The callback should examine EventData->u.DeviceHandle.
The callback should examine EventData->u.DeviceInstance.
Pointer to receive the HCMNOTIFICATION handle that corresponds to the registration call.
If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the CR_-prefixed error codes defined in Cfgmgr32.h.
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.
For an example, see Registering for Notification of Device Interface Arrival and Device Removal.
|Windows version||Available in Microsoft Windows 8 and later versions of Windows.|
|Header||cfgmgr32.h (include Cfgmgr32.h)|
|Library||Cfgmgr32.lib; OneCoreUAP.lib on Windows 10|