IAudioSessionControl2 interface

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:

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.

Method Description
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

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

See also

Core Audio Interfaces

IAudioSessionControl

Using a Communication Device