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 WINAPI CM_Register_Notification( _In_ PCM_NOTIFY_FILTER pFilter, _In_opt_ PVOID pContext, _In_ PCM_NOTIFY_CALLBACK pCallback, _Out_ PHCMNOTIFICATION pNotifyContext );
- pFilter [in]
Pointer to a CM_NOTIFY_FILTER structure.
The structure's cbSize member must be filled in with the size of the structure.
The structure's Flags member can have one of the following flags set:
Register to receive notifications for PnP events for all device interface classes. The memory at pFilter->u.DeviceInterface.ClassGuid must be zeroes. Do not use this flag with CM_NOTIFY_FILTER_FLAG_ALL_DEVICE_INSTANCES. This flag is only valid if pFilter->FilterType is CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE.
Register to receive notifications for PnP events for all devices. pFilter->u.DeviceInstance.InstanceId must be an empty string. Do not use this flag with CM_NOTIFY_FILTER_FLAG_ALL_INTERFACE_CLASSES. This flag is only valid if pFilter->FilterType is CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE.
The structure's FilterType member must be one of the following values:
Register for notifications for device interface events. pFilter->u.DeviceInterface.ClassGuid should be filled in with the GUID of the device interface class to receive notifications for.
Register for notifications for device handle events. pFilter->u.DeviceHandle.hTarget must be filled in with a handle to the device to receive notifications for.
Register for notifications for device instance events. pFilter->u.DeviceInstance.InstanceId should be filled in with the device instance ID of the device to receive notifications for.
The structure's Reserved member must be 0.
- pContext [in, optional]
Pointer to a caller-allocated buffer containing the context to be passed to the callback routine in pCallback.
- 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:
- pNotifyContext [out]
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.
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 an example, see Registering for Notification of Device Interface Arrival and Device Removal.
|Available in Microsoft Windows 8 and later versions of Windows.|
- Registering for Notification of Device Interface Arrival and Device Removal
- Using Device Interfaces