IMMDeviceEnumerator::RegisterEndpointNotificationCallback

IMMDeviceEnumerator::RegisterEndpointNotificationCallback

The RegisterEndpointNotificationCallback method registers a client's notification callback interface.

HRESULT RegisterEndpointNotificationCallback(
  IMMNotificationClient  *pNotify
);

Parameters

pNotify

[in]  Pointer to the IMMNotificationClient interface that the client is registering for notification callbacks. If the method succeeds, it calls the AddRef method on the client's IMMNotificationClient interface.

Return Value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Remarks

This method registers an IMMNotificationClient interface to be called by the system when the roles, state, existence, or properties of an endpoint device change. The caller implements the IMMNotificationClient interface.

When notifications are no longer needed, the client can call the IMMDeviceEnumerator::UnregisterEndpointNotificationCallback method to terminate the notifications.

Before the client releases its final reference to the IMMNotificationClient interface, it should call UnregisterEndpointNotificationCallback to unregister the interface. Otherwise, the application leaks the resources held by the IMMNotificationClient and IMMDeviceEnumerator objects. Note that RegisterEndpointNotificationCallback calls the client's IMMNotificationClient::AddRef method, and UnregisterEndpointNotificationCallback calls the IMMNotificationClient::Release method. If the client errs by releasing its reference to the IMMNotificationClient interface before calling UnregisterEndpointNotificationCallback, the device enumerator never releases its reference to the IMMNotificationClient interface. For example, a poorly designed IMMNotificationClient implementation might call UnregisterEndpointNotificationCallback from the destructor for the IMMNotificationClient object. In this case, the client will not call UnregisterEndpointNotificationCallback until the device enumerator releases its reference to the IMMNotificationClient interface, and the device enumerator will not release its reference to the IMMNotificationClient interface until the client calls UnregisterEndpointNotificationCallback. For more information about the AddRef and Release methods, see the discussion of the IUnknown interface in the Windows SDK documentation.

Requirements

Client: Windows Vista

Header: Include Mmdeviceapi.h.

See Also

• IMMDeviceEnumerator::UnregisterEndpointNotificationCallback
• IMMDeviceEnumerator Interface
• IMMNotificationClient Interface