IMMNotificationClient interface (mmdeviceapi.h)

The IMMNotificationClient interface provides notifications when an audio endpoint device is added or removed, when the state or properties of an endpoint device change, or when there is a change in the default role assigned to an endpoint device. Unlike the other interfaces in this section, which are implemented by the MMDevice API system component, an MMDevice API client implements the IMMNotificationClient interface. To receive notifications, the client passes a pointer to its IMMNotificationClient interface instance as a parameter to the IMMDeviceEnumerator::RegisterEndpointNotificationCallback method.

After registering its IMMNotificationClient interface, the client receives event notifications in the form of callbacks through the methods of the interface.

Each method in the IMMNotificationClient interface receives, as one of its input parameters, an endpoint ID string that identifies the audio endpoint device that is the subject of the notification. The string uniquely identifies the device with respect to all of the other audio endpoint devices in the system. The methods in the IMMNotificationClient interface implementation should treat this string as opaque. That is, none of the methods should attempt to parse the contents of the string to obtain information about the device. The reason is that the string format is undefined and might change from one implementation of the MMDevice API system module to the next.

A client can use the endpoint ID string that it receives as an input parameter in a call to an IMMNotificationClient method in two ways:

• The client can create an instance of the device that the endpoint ID string identifies. The client does this by calling the IMMDeviceEnumerator::GetDevice method and supplying the endpoint ID string as an input parameter.
• The client can compare the endpoint ID string with the endpoint ID string of an existing device instance. To obtain the second endpoint ID string, the client calls the IMMDevice::GetId method of the device instance. If the two strings match, they identify the same device.

In implementing the IMMNotificationClient interface, the client should observe these rules to avoid deadlocks and undefined behavior:

• The methods of the interface must be nonblocking. The client should never wait on a synchronization object during an event callback.
• To avoid dead locks, the client should never call IMMDeviceEnumerator::RegisterEndpointNotificationCallback or IMMDeviceEnumerator::UnregisterEndpointNotificationCallback in its implementation of IMMNotificationClient methods.
• The client should never release the final reference on an MMDevice API object during an event callback.

For a code example that implements the IMMNotificationClient interface, see Device Events.

Inheritance

The IMMNotificationClient interface inherits from the IUnknown interface. IMMNotificationClient also has these types of members:

Methods

The IMMNotificationClient interface has these methods.

IMMNotificationClient::OnDefaultDeviceChanged The OnDefaultDeviceChanged method notifies the client that the default audio endpoint device for a particular device role has changed.
IMMNotificationClient::OnDeviceAdded The OnDeviceAdded method indicates that a new audio endpoint device has been added.
IMMNotificationClient::OnDeviceRemoved The OnDeviceRemoved method indicates that an audio endpoint device has been removed.
IMMNotificationClient::OnDeviceStateChanged The OnDeviceStateChanged method indicates that the state of an audio endpoint device has changed.
IMMNotificationClient::OnPropertyValueChanged The OnPropertyValueChanged method indicates that the value of a property belonging to an audio endpoint device has changed.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	mmdeviceapi.h

See also

Core Audio Interfaces

IMMDevice::GetId

IMMDeviceEnumerator::GetDevice

IMMDeviceEnumerator::RegisterEndpointNotificationCallback

IMMDeviceEnumerator::UnregisterEndpointNotificationCallback

MMDevice API