IAudioSessionEnumerator interface (audiopolicy.h)

The IAudioSessionEnumerator interface enumerates audio sessions on an audio device. To get a reference to the IAudioSessionEnumerator interface of the session enumerator object, the application must call IAudioSessionManager2::GetSessionEnumerator.

Inheritance

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

Methods

The IAudioSessionEnumerator interface has these methods.

IAudioSessionEnumerator::GetCount The GetCount method gets the total number of audio sessions that are open on the audio device.
IAudioSessionEnumerator::GetSession The GetSession method gets the audio session specified by an audio session number.

Remarks

If an application wants to be notified when new sessions are created, it must register its implementation of IAudioSessionNotification with the session manager. Upon successful registration, the session manager sends create-session notifications to the application in the form of callbacks. These notifications contain a reference to the IAudioSessionControl pointer of the newly created session.

The session enumerator maintains a list of current sessions by holding references to each session's IAudioSessionControl pointer. However, the session enumerator might not be aware of the new sessions that are reported through IAudioSessionNotification. In that case, the application would have access to only a partial list of sessions. This might occur if the IAudioSessionControl pointer (in the callback) is released before the session enumerator is initialized. Therefore, if an application wants a complete set of sessions for the audio endpoint, the application should maintain its own list.

The application must perform the following steps to receive session notifications and manage a list of current sessions.

1. Initialize COM with the Multithreaded Apartment (MTA) model by calling CoInitializeEx(NULL, COINIT_MULTITHREADED) in a non-UI thread. If MTA is not initialized, the application does not receive session notifications from the session manager.
   Note  Threads that run the user interface of an application should be initialized with the apartment threading model.
    
2. Activate an IAudioSessionManager2 interface from the audio endpoint device. Call IMMDevice::Activate with parameter iid set to IID_IAudioSessionManager2. This call receives a reference to the session manager's IAudioSessionManager2 interface in the ppInterface parameter.
3. Implement the IAudioSessionNotification interface to provide the callback behavior.
4. Call IAudioSessionManager2::RegisterSessionNotification to register the application's implementation of IAudioSessionNotification.
5. Create and initialize the session enumerator object by calling IAudioSessionManager2::GetSessionEnumerator. This method generates a list of current sessions available for the endpoint and adds the IAudioSessionControl pointers for each session in the list, if they are not already present.
6. Use the IAudioSessionEnumerator interface returned in the previous step to retrieve and enumerate the list of sessions. The session control for each session can be retrieved by calling IAudioSessionEnumerator::GetSession. Make sure you call AddRef for each session control to maintain the reference count.
7. When the application gets a create-session notification, add the IAudioSessionControl pointer of the new session (received in IAudioSessionNotification::OnSessionCreated) to the list of existing sessions.

Because the application maintains this list of sessions and manages the lifetime of the session based on the application's requirements, there is no expiration mechanism enforced by the audio system on the session control objects.

A session control is valid as long as the application has a reference to the session control in the list.

Examples

The following example code shows how to create the session enumerator object and then enumerate sessions.

HRESULT EnumSessions(IAudioSessionManager2* pSessionManager)
{
    if (!pSessionManager)
    {
        return E_INVALIDARG;
    }

    HRESULT hr = S_OK;
    
    int cbSessionCount = 0;
    LPWSTR pswSession = NULL;
    
    IAudioSessionEnumerator* pSessionList = NULL;
    IAudioSessionControl* pSessionControl = NULL;
    
    // Get the current list of sessions.
    CHECK_HR( hr = pSessionManager->GetSessionEnumerator(&pSessionList));
    
    // Get the session count.
    CHECK_HR( hr = pSessionList->GetCount(&cbSessionCount));

    for (int index = 0 ; index < cbSessionCount ; index++)
    {
        CoTaskMemFree(pswSession);
        SAFE_RELEASE(pSessionControl);
        
        // Get the <n>th session.
        CHECK_HR(hr = pSessionList->GetSession(index, &pSessionControl));

        CHECK_HR(hr = pSessionControl->GetDisplayName(&pswSession));

        wprintf_s(L"Session Name: %s\n", pswSession);
    }

done:
    CoTaskMemFree(pswSession);
    SAFE_RELEASE(pSessionControl);
    SAFE_RELEASE(pSessionList);

    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

See also

Core Audio Interfaces