IAudioEndpointVolumeCallback Interface

IAudioEndpointVolumeCallback Interface

The IAudioEndpointVolumeCallback interface provides notifications of changes in the volume level and muting state of an audio endpoint device. Unlike the other interfaces in this section, which are implemented by the WASAPI system component, an EndpointVolume API client implements the IAudioEndpointVolumeCallback interface. To receive event notifications, the client passes a pointer to its IAudioEndpointVolumeCallback interface to the IAudioEndpointVolume::RegisterControlChangeNotify method.

After registering its IAudioEndpointVolumeCallback interface, the client receives event notifications in the form of callbacks through the OnNotify method in the interface. These event notifications occur when one of the following methods causes a change in the volume level or muting state of an endpoint device:

• IAudioEndpointVolume::SetChannelVolumeLevel
• IAudioEndpointVolume::SetChannelVolumeLevelScalar
• IAudioEndpointVolume::SetMasterVolumeLevel
• IAudioEndpointVolume::SetMasterVolumeLevelScalar
• IAudioEndpointVolume::SetMute
• IAudioEndpointVolume::VolumeStepDown
• IAudioEndpointVolume::VolumeStepUp

If an audio endpoint device implements hardware volume and mute controls, the IAudioEndpointVolume interface uses the hardware controls to manage the device's volume. Otherwise, the IAudioEndpointVolume interface implements volume and mute controls in software, transparently to the client.

If a device has hardware volume and mute controls, changes made to the volume and mute settings through the methods in the preceding list affect the device's volume in both shared mode and exclusive mode. If a device lacks hardware volume and mute controls, changes made to the software volume and mute controls through these methods affect the device's volume in shared mode, but not in exclusive mode. In exclusive mode, the client and the device exchange audio data directly, bypassing the software controls. However, changes made to the software controls through these methods generate event notifications regardless of whether the device is operating in shared mode or in exclusive mode. Changes made to the software volume and mute controls while the device operates in exclusive mode take effect when the device switches to shared mode.

To determine whether a device has hardware volume and mute controls, call the IAudioEndpointVolume::QueryHardwareSupport method.

In implementing the IAudioEndpointVolumeCallback interface, the client should observe these rules to avoid deadlocks:

• The methods in the interface must be nonblocking. The client should never wait on a synchronization object during an event callback.
• The client should never call the IAudioEndpointVolume::UnregisterControlChangeNotify method during an event callback.
• The client should never release the final reference on an EndpointVolume API object during an event callback.

For a code example that implements the IAudioEndpointVolumeCallback interface, see Endpoint Volume Controls.

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

Requirements

Client: Windows Vista

Header: Include Endpointvolume.h.

See Also

• EndpointVolume API
• IAudioEndpointVolume::RegisterControlChangeNotify
• IAudioEndpointVolume::UnregisterControlChangeNotify