IAudioSessionManager2 interface (audiopolicy.h)

Article
10/05/2021

The IAudioSessionManager2 interface enables an application to manage submixes for the audio device.

To a get a reference to an IAudioSessionManager2 interface, the application must activate it on the audio device by following these steps:

Use one of the techniques described on the IMMDevice interface page to obtain a reference to the IMMDevice interface for an audio endpoint device.
Call the IMMDevice::Activate method with parameter iid set to IID_IAudioSessionManager2.

When the application wants to release the IAudioSessionManager2 interface instance, the application must call the interface's Release method.

The application thread that uses this interface must be initialized for COM. For more information about COM initialization, see the description of the CoInitializeEx function in the Windows SDK documentation.

Inheritance

The IAudioSessionManager2 interface inherits from IAudioSessionManager. IAudioSessionManager2 also has these types of members:

Methods

The IAudioSessionManager2 interface has these methods.


IAudioSessionManager2::GetSessionEnumerator The GetSessionEnumerator method gets a pointer to the audio session enumerator object.
IAudioSessionManager2::RegisterDuckNotification The RegisterDuckNotification method registers the application with the session manager to receive ducking notifications.
IAudioSessionManager2::RegisterSessionNotification The RegisterSessionNotification method registers the application to receive a notification when a session is created.
IAudioSessionManager2::UnregisterDuckNotification The UnregisterDuckNotification method deletes a previous registration by the application to receive notifications.
IAudioSessionManager2::UnregisterSessionNotification The UnregisterSessionNotification method deletes the registration to receive a notification when a session is created.

Remarks

An application can use this interface to perform the following tasks:

Register to receive ducking notifications.
Register to receive a notification when a session is created.
Enumerate sessions on the audio device that was used to get the interface pointer.

This interface supports custom implementations for stream attenuation or ducking, a new feature in Windows 7. An application playing a media stream can make the it behave differently when a new communication stream is opened on the default communication device. For example, the original media stream can be paused while the new communication stream is open. For more information about this feature, see Using a Communication Device.

An application that manages the media streams and wants to provide a custom ducking implementation, must register to receive notifications when session events occur. For stream attenuation, a session event is raised by the system when a communication stream is opened or closed on the default communication device. For more information, see Providing a Custom Ducking Behavior.

Examples

The following example code shows how to get a reference to the IAudioSessionManager2 interface of the audio device.

HRESULT CreateSessionManager(IAudioSessionManager2** ppSessionManager)
{
 
    HRESULT hr = S_OK;
    
    IMMDevice* pDevice = NULL;
    IMMDeviceEnumerator* pEnumerator = NULL;
    IAudioSessionManager2* pSessionManager = NULL;


    // Create the device enumerator.
    CHECK_HR( hr = CoCreateInstance(
        __uuidof(MMDeviceEnumerator), 
        NULL, CLSCTX_ALL, 
        __uuidof(IMMDeviceEnumerator), 
        (void**)&pEnumerator));

    // Get the default audio device.
    CHECK_HR( hr = pEnumerator->GetDefaultAudioEndpoint(
                    eRender, eConsole, &pDevice));

    // Get the session manager.
    CHECK_HR( hr = pDevice->Activate(
        __uuidof(IAudioSessionManager2), CLSCTX_ALL,
        NULL, (void**)&pSessionManager));

    // Return the pointer to the caller.
    *(ppSessionManager) = pSessionManager;
    (*ppSessionManager)->AddRef();

done:

    // Clean up.
    SAFE_RELEASE(pSessionManager);
    SAFE_RELEASE(pEnumerator);
    SAFE_RELEASE(pDevice);

    return hr;
}

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