IAudioVolumeDuckNotification interface (audiopolicy.h)

Article
10/05/2021

The IAudioVolumeDuckNotification interface is used to by the system to send notifications about stream attenuation changes.Stream Attenuation, or ducking, is a feature introduced in Windows 7, where the system adjusts the volume of a non-communication stream when a new communication stream is opened. For more information about this feature, see Default Ducking Experience.

Inheritance

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

Methods

The IAudioVolumeDuckNotification interface has these methods.


IAudioVolumeDuckNotification::OnVolumeDuckNotification The OnVolumeDuckNotification method sends a notification about a pending system ducking event.
IAudioVolumeDuckNotification::OnVolumeUnduckNotification The OnVolumeUnduckNotification method sends a notification about a pending system unducking event.

Remarks

If an application needs to opt out of the system attenuation experience provided by the system, it must call IAudioSessionControl2::SetDuckingPreference and specify that preference.

Unlike the other WASAPI interfaces, which are implemented by the WASAPI system component, the IAudioVolumeDuckNotification interface is implemented by the application to provide custom stream attenuation behavior. To receive event notifications, the application passes to the IAudioSessionManager2::RegisterDuckNotification method a pointer to the application's implementation of IAudioVolumeDuckNotification.

After the application has registered its IAudioVolumeDuckNotification interface, the session manager calls the IAudioVolumeDuckNotification implementation when it needs to send ducking notifications. The application receives event notifications in the form of callbacks through the methods of the interface.

When the application no longer needs to receive notifications, it calls the IAudioSessionManager2::UnregisterDuckNotification method. The UnregisterDuckNotification method removes the registration of an IAudioVolumeDuckNotification interface that the application previously registered.

The application must not register or unregister notification callbacks during an event callback.

For more information, see Implementation Considerations for Ducking Notifications.

Examples

The following example code shows a sample implementation of the IAudioVolumeDuckNotification interface.



class CDuckNotification : public IAudioVolumeDuckNotification
{
    LONG            _Cref;
    HWND            m_hwndMain;

    CDuckNotification (HWND hWnd) : 
        _Cref(1), 
        m_hwndMain (hWnd)
							 {}

    
    HRESULT OnVolumeDuckNotification (LPCWSTR SessionID, UINT32 CommunicationSessionCount)
    {
         PostMessage(m_hwndMain, WM_VOLUME_DUCK, 0, 0);
         return S_OK;
    }
    HRESULT OnVolumeUnduckNotification (LPCWSTR SessionID)
    {
         PostMessage(m_hwndMain, WM_VOLUME_UNDUCK, 0, 0);
         return S_OK;
    }

protected:
    ~CDuckNotification() {}

public:
    HRESULT QueryInterface (REFIID Iid, void** ReturnValue)
    {
        if (ReturnValue == NULL)
        {
            return E_POINTER;
        }
        *ReturnValue = NULL;
        if (iid == IID_IUnknown)
        {
            *ReturnValue = static_cast<IUnknown *>(static_cast<IAudioVolumeDuckNotification *>(this));
            AddRef();
        }
        else if (iid == __uuidof(IAudioVolumeDuckNotification))
        {
            *ReturnValue = static_cast<IAudioVolumeDuckNotification *>(this);
            AddRef();
        }
        else
        {
            return E_NOINTERFACE;
        }
        return S_OK;
    }
    ULONG AddRef()
    {
        return InterlockedIncrement(&_Cref);
    }

    ULONG Release()
    {
        LONG ref = InterlockedDecrement(&_Cref);
        if (ref == 0)
        {
            delete this;
        }
        return 0;
    }
};

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	audiopolicy.h