IAudioVolumeDuckNotification interface (audiopolicy.h)

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.

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

See also

Core Audio Interfaces

Using a Communication Device