Export (0) Print
Expand All
Expand Minimize

CM_Register_Notification function

Use RegisterDeviceNotification instead of CM_Register_Notification if your code targets Windows 7 or earlier versions of Windows.

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

Syntax


CMAPI
CONFIGRET
WINAPI CM_Register_Notification(
  _In_      PCM_NOTIFY_FILTER pFilter,
  _In_opt_  PVOID pContext,
  _In_      PCM_NOTIFY_CALLBACK pCallback,
  _Out_     PHCMNOTIFICATION pNotifyContext
);

Parameters

pFilter [in]

Pointer to a CM_NOTIFY_FILTER structure.

The structure's cbSize submember must be filled in with the size of the structure.

The structure's Flags submember can have one of the following flags set:

CM_NOTIFY_FILTER_FLAG_ALL_INTERFACE_CLASSES

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.

CM_NOTIFY_FILTER_FLAG_ALL_DEVICE_INSTANCES

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 submember must be one of the following values:

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

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.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

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.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

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 submember 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:

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.

pNotifyContext [out]

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.

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 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.

Requirements

Version

Available in Microsoft Windows 8 and later versions of Windows.

Header

Cfgmgr32.h (include Cfgmgr32.h)

Library

Cfgmgr32.lib

See also

RegisterDeviceNotification
CM_Unregister_Notification

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft