RegisterDeviceNotificationA function (winuser.h)

Article
03/11/2023

Registers the device or type of device for which a window will receive notifications.

Note

You can use CM_Register_Notification instead of RegisterDeviceNotification if your code targets Windows 8 or newer versions of Windows. The advantage of CM_Register_Notification is that it does not require a window handle to work.

Syntax

HDEVNOTIFY RegisterDeviceNotificationA(
  [in] HANDLE hRecipient,
  [in] LPVOID NotificationFilter,
  [in] DWORD  Flags
);

Parameters

[in] hRecipient

A handle to the window or service that will receive device events for the devices specified in the NotificationFilter parameter. The same window handle can be used in multiple calls to RegisterDeviceNotification.

Services can specify either a window handle or service status handle.

[in] NotificationFilter

A pointer to a block of data that specifies the type of device for which notifications should be sent. This block always begins with the DEV_BROADCAST_HDR structure. The data following this header is dependent on the value of the dbch_devicetype member, which can be DBT_DEVTYP_DEVICEINTERFACE or DBT_DEVTYP_HANDLE. For more information, see Remarks.

[in] Flags

This parameter can be one of the following values.

Value	Meaning
DEVICE_NOTIFY_WINDOW_HANDLE 0x00000000	The hRecipient parameter is a window handle.
DEVICE_NOTIFY_SERVICE_HANDLE 0x00000001	The hRecipient parameter is a service status handle.

In addition, you can specify the following value.

Value	Meaning
DEVICE_NOTIFY_ALL_INTERFACE_CLASSES 0x00000004	Notifies the recipient of device interface events for all device interface classes. (The dbcc_classguid member is ignored.) This value can be used only if the dbch_devicetype member is DBT_DEVTYP_DEVICEINTERFACE.

Return value

If the function succeeds, the return value is a device notification handle.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Applications send event notifications using the BroadcastSystemMessage function. Any application with a top-level window can receive basic notifications by processing the WM_DEVICECHANGE message. Applications can use the RegisterDeviceNotification function to register to receive device notifications.

Services can use the RegisterDeviceNotification function to register to receive device notifications. If a service specifies a window handle in the hRecipient parameter, the notifications are sent to the window procedure. If hRecipient is a service status handle, SERVICE_CONTROL_DEVICEEVENT notifications are sent to the service control handler. For more information about the service control handler, see HandlerEx.

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

Device notification handles returned by RegisterDeviceNotification must be closed by calling the UnregisterDeviceNotification function when they are no longer needed.

The DBT_DEVICEARRIVAL and DBT_DEVICEREMOVECOMPLETE events are automatically broadcast to all top-level windows for port devices. Therefore, it is not necessary to call RegisterDeviceNotification for ports, and the function fails if the dbch_devicetype member is DBT_DEVTYP_PORT. Volume notifications are also broadcast to top-level windows, so the function fails if dbch_devicetype is DBT_DEVTYP_VOLUME. OEM-defined devices are not used directly by the system, so the function fails if dbch_devicetype is DBT_DEVTYP_OEM.

Examples

For an example, see Registering for device notification.

Note

The winuser.h header defines RegisterDeviceNotification as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows XP
Minimum supported server	Windows Server 2003
Target Platform	Windows
Header	winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll
API set	ext-ms-win-ntuser-misc-l1-1-0 (introduced in Windows 8)

Share via