IAudioSessionControl2

IAudioSessionControl2 インターフェイスは、クライアントがオーディオセッションに関する情報を取得するために使用できます。

このインターフェイスは、Windows 7 で追加された新機能であるストリーム減衰(ダッキング)のカスタム実装をサポートします。メディアストリームを再生しているアプリケーションは、既定の通信デバイスで新しい通信ストリームが開かれたときに、その動作を変更できます。たとえば、新しい通信ストリームが開いている間、元のメディアストリームを一時停止することができます。この機能の詳細については、既定のダッキングエクスペリエンスを参照してください。

アプリケーションは、このインターフェイスを使用して次のタスクを実行できます。

• システムが提供する既定のストリーム減衰エクスペリエンスをオプトアウトすることを指定します。
• ストリームに関連付けられているオーディオセッション識別子を取得します。この識別子は通知の登録時に必要です。アプリケーションは、システムからダッキング通知を受け取るように自身を登録できます。
• オーディオセッションに関連付けられているストリームがシステムサウンドかどうかを確認します。

例

次のサンプルコードは、IAudioSessionControl2 インターフェイスへの参照を取得し、そのメソッドを呼び出して、オーディオセッションに関連付けられているストリームがシステムサウンドかどうかを判別する方法を示します。

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;
}

GetSessionIdentifier メソッドは、オーディオセッション識別子を取得します。

メソッドが成功すると S_OK を返します。 失敗した場合に返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。

各オーディオセッションは識別子文字列によって識別されます。このセッション識別子文字列は、すべてのインスタンスにわたって一意ではありません。アプリケーションのインスタンスが 2 つ再生されている場合、両方のインスタンスは同じセッション識別子を持ちます。GetSessionIdentifier によって取得される識別子は、すべてのセッションにわたって一意であるセッションインスタンス識別子とは異なります。セッションインスタンス識別子を取得するには、IAudioSessionControl2::GetSessionInstanceIdentifier を呼び出します。

GetSessionIdentifier は、既定のデバイスでセッションが切断されているかどうかを確認します。このメソッドは、デバイスのオーディオクライアントによってキャッシュされている識別子文字列を取得します。セッション識別子が見つからない場合、このメソッドはオーディオエンジンから取得します。

GetSessionInstanceIdentifier メソッドは、オーディオセッションインスタンスの識別子を取得します。

メソッドが成功すると S_OK を返します。 失敗した場合に返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。

各オーディオセッションインスタンスは、一意の文字列によって識別されます。この文字列はオーディオセッションの特定のインスタンスを表し、セッション識別子とは異なり、すべてのインスタンスにわたって一意です。アプリケーションのインスタンスが 2 つ再生されている場合、それらは異なるセッションインスタンス識別子を持ちます。GetSessionInstanceIdentifier によって取得される識別子は、すべてのセッションインスタンスで共有されるセッション識別子とは異なります。セッション識別子を取得するには、IAudioSessionControl2::GetSessionIdentifier を呼び出します。

GetSessionInstanceIdentifier は、既定のデバイスでセッションが切断されているかどうかを確認します。このメソッドは、デバイスのオーディオクライアントによってキャッシュされている識別子文字列を取得します。セッションインスタンス識別子が見つからない場合、このメソッドはオーディオエンジンから取得します。セッションインスタンス識別子を取得するサンプルコードについては、通信デバイスからのダッキングイベントの取得を参照してください。

GetProcessId メソッドは、オーディオセッションのプロセス識別子を取得します。

メソッドが成功すると S_OK を返します。 失敗した場合に返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。

このメソッドは、アプリケーションが pRetVal で渡した値を上書きします。

GetProcessId は、既定のデバイスでオーディオセッションが切断されているかどうか、またはセッションが別のストリームに切り替わったかどうかを確認します。ストリームの切り替えが発生した場合、このメソッドは新しいストリームの状態情報をセッションに転送します。状態情報には、ボリュームコントロール、メタデータ情報(表示名、アイコンパス)、およびセッションのプロパティストアが含まれます。

IsSystemSoundsSession メソッドは、セッションがシステムサウンドセッションかどうかを示します。

返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。

SetDuckingPreference メソッドは、システムが提供する既定のストリーム減衰エクスペリエンス(自動ダッキング)を有効または無効にします。

メソッドが成功すると S_OK を返します。 失敗した場合に返される可能性のあるコードには、次の表に示す値が含まれますが、これらに限定されません。

既定では、システムが通信セッションを開始し、既定の通信デバイスで新しい通信ストリームを受信すると、システムは現在再生中のすべてのサウンドのボリュームを調整します。この機能の詳細については、通信デバイスの使用を参照してください。

アプリケーションが optOut に TRUE を渡すと、システムは既定のダッキングエクスペリエンスを無効にします。詳細については、既定のダッキングエクスペリエンスの無効化を参照してください。

カスタム実装を提供するには、アプリケーションは通信ストリームを開いたり閉じたりするときにシステムから通知を受け取る必要があります。通知を受け取るには、アプリケーションは IAudioSessionManager2::RegisterForDuckNotification を呼び出して自身を登録する前に、このメソッドを呼び出す必要があります。詳細とサンプルコードについては、ダッキングイベントの取得を参照してください。

アプリケーションが optOut に FALSE を渡すと、アプリケーションはシステムが提供する既定のストリーム減衰エクスペリエンスを利用します。

アプリケーションは、ストリームの作成時に SetDuckingPreference を呼び出すことをお勧めします。ただし、このメソッドはセッション中に動的に呼び出して、初期設定を変更することもできます。