IMMNotificationClient Interface

IMMNotificationClient Interface

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.
• The client should never call the IMMDeviceEnumerator::UnregisterEndpointNotificationCallback method during an event callback.
• 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.

IMMNotificationClient inherits from the IUnknown interface. In addition to the methods inherited from IUnknown, IMMNotificationClient supports the following methods.

Requirements

Client: Windows Vista

Header: Include Mmdeviceapi.h.

See Also

• IMMDevice::GetId
• IMMDeviceEnumerator::GetDevice
• IMMDeviceEnumerator::RegisterEndpointNotificationCallback
• IMMDeviceEnumerator::UnregisterEndpointNotificationCallback
• MMDevice API