IAudioSessionControl2 interface (audiopolicy.h)

Article
10/05/2021

The IAudioSessionControl2 interface can be used by a client to get information about the audio session.

To get a reference to the IAudioSessionControl2 interface, the application must call IAudioSessionControl::QueryInterface to request the interface pointer from the stream object's IAudioSessionControl interface. There are two ways an application can get a pointer to the IAudioSessionControl interface:

By calling IAudioClient::GetService on the audio client after opening a stream on the device. The audio client opens a stream for rendering or capturing, and associates it with an audio session by calling IAudioClient::Initialize.
By calling IAudioSessionManager::GetAudioSessionControl for an existing audio session without opening the stream.

When the application wants to release the IAudioSessionControl2 interface instance, the application must call the interface's Release method from the same thread as the call to IAudioClient::GetService that created the object.

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 IAudioSessionControl2 interface inherits from IAudioSessionControl. IAudioSessionControl2 also has these types of members:

Methods

The IAudioSessionControl2 interface has these methods.


IAudioSessionControl2::GetProcessId The GetProcessId method retrieves the process identifier of the audio session.
IAudioSessionControl2::GetSessionIdentifier The GetSessionIdentifier method retrieves the audio session identifier.
IAudioSessionControl2::GetSessionInstanceIdentifier The GetSessionInstanceIdentifier method retrieves the identifier of the audio session instance.
IAudioSessionControl2::IsSystemSoundsSession The IsSystemSoundsSession method indicates whether the session is a system sounds session.
IAudioSessionControl2::SetDuckingPreference The SetDuckingPreference method enables or disables the default stream attenuation experience (auto-ducking) provided by the system.

Remarks

This interface supports custom implementations for stream attenuation or ducking, a new feature in Windows 7. An application playing a media stream can make 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 Default Ducking Experience.

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

Specify that it wants to opt out of the default stream attenuation experience provided by the system.
Get the audio session identifier that is associated with the stream. The identifier is required during the notification registration. The application can register itself to receive ducking notifications from the system.
Check whether the stream associated with the audio session is a system sound.

Examples

The following example code shows how to get a reference to the IAudioSessionControl2 interface and call its methods to determine whether the stream associated with the audio session is a system sound.

HRESULT SetDuckingForSystemSounds()
{
 
    HRESULT hr = S_OK;
    
    IMMDevice* pDevice = NULL;
    IMMDeviceEnumerator* pEnumerator = NULL;
    IAudioSessionControl* pSessionControl = NULL;
    IAudioSessionControl2* pSessionControl2 = NULL;
    IAudioSessionManager* pSessionManager = NULL;

    CHECK_HR( hr = CoInitialize(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 audio client.
    CHECK_HR( hr = pDevice->Activate(
        __uuidof(IID_IAudioSessionManager), CLSCTX_ALL,
        NULL, (void**)&pSessionManager));

    // Get a reference to the session manager.
    CHECK_HR( hr = pSessionManager->GetAudioSessionControl (GUID_NULL, FALSE, &pSessionControl));
    
    // Get the extended session control interface pointer.
    CHECK_HR( hr = pSessionControl->QueryInterface(
        __uuidof(IAudioSessionControl2), (void**) &pSessionControl2));

    // Check whether this is a system sound.
    CHECK_HR( hr = pSessionControl2->IsSystemSoundsSession());

    // If it is a system sound, opt out of the default
    // stream attenuation experience.
    CHECK_HR( hr = pSessionControl2->SetDuckingPreference(TRUE));

done:

    // Clean up.
    SAFE_RELEASE(pSessionControl2);
    SAFE_RELEASE(pSessionControl);
    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