IAudioSessionControl

IAudioSessionControl インターフェイスを使用すると、クライアントはオーディオセッションの制御パラメーターを構成し、セッション内のイベントを監視できます。

GetState メソッドは、オーディオセッションの現在の状態を取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

このメソッドは、セッションの状態がアクティブ、非アクティブ、または期限切れのいずれであるかを示します。セッションに実行中のストリームが1つ以上ある場合、状態はアクティブです。セッション内で最後に実行中だったストリームが停止すると、状態はアクティブから非アクティブに変わります。クライアントがストリームオブジェクトへのすべての参照を解放してセッション内の最後のストリームを破棄すると、セッション状態は期限切れに変わります。

Sndvol プログラムは、アクティブおよび非アクティブ状態のセッションについて音量とミュートのコントロールを表示します。セッションが期限切れになると、Sndvol はそのセッションのコントロールの表示を停止します。以前に期限切れになったセッションであっても、（セッション内のストリームが実行を開始したために）状態がアクティブに変わったり、（クライアントがセッションに新しいストリームを割り当てたために）非アクティブに変わったりした場合、Sndvol はそのセッションのコントロールの表示を再開します。

クライアントは、IAudioClient::Initialize メソッドを呼び出してストリームを作成します。ストリームを作成する時点で、クライアントはそのストリームをセッションに割り当てます。セッションは、クライアントが最初のストリームをセッションに割り当てた時点で開始します。当初、セッションは非アクティブ状態です。セッション内の最初のストリームが実行を開始すると、セッション状態はアクティブに変わります。クライアントがセッション内に残っている最後のストリームオブジェクトへの最終参照を解放すると、セッションは終了します。

GetDisplayName メソッドは、オーディオセッションの表示名を取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

クライアントが IAudioSessionControl::SetDisplayName を呼び出して表示名を設定していない場合、文字列は空になります。Sndvol プログラムは、空の名前文字列を表示する代わりに、既定の自動生成された名前を使用してオーディオセッションの音量コントロールにラベルを付けます。

SetDisplayName メソッドは、現在のセッションに表示名を割り当てます。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

Windows Vista では、システム提供のプログラム Sndvol.exe が表示名を使用してセッションの音量コントロールにラベルを付けます。クライアントが SetDisplayName を呼び出してセッションに表示名を割り当てていない場合、Sndvol プログラムは既定の自動生成された名前を使用してセッションにラベルを付けます。この既定の名前には、オーディオアプリケーションのウィンドウタイトルやバージョンリソースなどの情報が組み込まれます。

クライアントに複数のアクティブなセッションがある場合、クライアントが指定した表示名は、さまざまなセッションの音量コントロールを区別するのに特に役立ちます。

クロスプロセスセッションの場合、そのセッションには既定の表示名を生成する元となる、アプリケーション名やプロセス ID などの識別情報がありません。したがって、意味のない既定の表示名が表示されるのを避けるため、クライアントは SetDisplayName を呼び出す必要があります。

表示名は IAudioSessionControl オブジェクトの有効期間を超えて保持されません。したがって、オブジェクトへのすべての参照が解放された後に（同じアプリケーション、同じセッション GUID、同じエンドポイントデバイスで）新たに作成されたバージョンのオブジェクトは、クライアントが SetDisplayName を呼び出すまで、再び既定の自動生成された表示名を持つことになります。

クライアントは、IAudioSessionControl::GetDisplayName メソッドを呼び出してセッションの表示名を取得できます。

GetIconPath メソッドは、オーディオセッションの表示アイコンのパスを取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

クライアントが IAudioSessionControl::SetIconPath を呼び出して表示アイコンを設定していない場合、文字列は空になります。クライアントが指定したアイコンが利用できない場合、Sndvol プログラムはクライアントのアプリケーションウィンドウのアイコンを使用してオーディオセッションの音量コントロールにラベルを付けます。

SetIconPath メソッドは、現在のセッションに表示アイコンを割り当てます。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

Windows Vista では、システム提供のプログラム Sndvol.exe が表示アイコンを（表示名とともに）使用してセッションの音量コントロールにラベルを付けます。クライアントが SetIconPath を呼び出してセッションにアイコンを割り当てていない場合、Sndvol プログラムはアプリケーションウィンドウのアイコンをセッションの既定のアイコンとして使用します。

クロスプロセスセッションの場合、そのセッションは単一のアプリケーションプロセスに関連付けられていません。したがって、Sndvol には既定で使用するアプリケーション固有のアイコンがなく、意味のないアイコンが表示されるのを避けるため、クライアントは SetIconPath を呼び出す必要があります。

表示アイコンは IAudioSessionControl オブジェクトの有効期間を超えて保持されません。したがって、オブジェクトへのすべての参照が解放された後に（同じアプリケーション、同じセッション GUID、同じエンドポイントデバイスで）新たに作成されたバージョンのオブジェクトは、クライアントが SetIconPath を呼び出すまで、再び既定のアイコンを持つことになります。

クライアントは、IAudioSessionControl::GetIconPath メソッドを呼び出してセッションの表示アイコンを取得できます。

GetGroupingParam メソッドは、オーディオセッションのグループ化パラメーターを取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

同じグループ化パラメーター値を持つすべてのオーディオセッションは、システムの音量制御プログラム Sndvol 内の同じ音量レベルスライダーの制御下に置かれます。詳細については、グループ化パラメーターを参照してください。

クライアントは、IAudioSessionControl::SetGroupingParam メソッドを呼び出してセッションのグループ化パラメーターを変更できます。

クライアントが SetGroupingParam を一度も呼び出してオーディオセッションにグループ化パラメーターを割り当てていない場合、セッションのグループ化パラメーター値は既定で GUID_NULL となり、GetGroupingParam の呼び出しはこの値を取得します。グループ化パラメーター値が GUID_NULL の場合、そのセッションはどのグループにも属していないことを示します。この場合、セッションは Sndvol プログラム内に独自の音量レベルスライダーを持ちます。

SetGroupingParam メソッドは、セッションをセッションのグループ化に割り当てます。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

クライアントは、このメソッドを呼び出してセッションのグループ化パラメーターを変更します。同じグループ化パラメーター値を持つすべてのオーディオセッションは、システムの音量制御プログラム Sndvol 内の同じ音量レベルスライダーの制御下に置かれます。詳細については、グループ化パラメーターを参照してください。

クライアントは、IAudioSessionControl::GetGroupingParam メソッドを呼び出してセッションの現在のグループ化パラメーターを取得できます。

クライアントが SetGroupingParam を一度も呼び出してセッションにグループ化パラメーターを割り当てていない場合、そのセッションはどのグループにも属していません。どのグループにも属していないセッションは、Sndvol プログラム内に独自の専用音量レベルスライダーを持ちます。

RegisterAudioSessionNotification メソッドは、ストリーム状態の変化を含むセッションイベントの通知を受け取るためにクライアントを登録します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

このメソッドは、クライアントが実装した IAudioSessionEvents インターフェイスをセッションマネージャーに渡します。このメソッドの呼び出しが成功すると、セッションマネージャーは IAudioSessionEvents インターフェイス内のメソッドを呼び出して、さまざまなセッションイベントをクライアントに通知します。これらのメソッドを通じて、クライアントは次のセッション関連イベントの通知を受け取ります。

• 表示名の変更
• 音量レベルの変更
• セッション状態の変更（非アクティブからアクティブ、またはアクティブから非アクティブ）
• グループ化パラメーターの変更
• クライアントとセッションの接続解除（ユーザーによるオーディオエンドポイントデバイスの取り外し、セッションマネージャーのシャットダウン、またはストリーム形式の変更によって発生）

クライアントは、IAudioSessionEvents インターフェイスへの最終参照を解放する前に、UnregisterAudioSessionNotification を呼び出してインターフェイスの登録を解除する必要があります。そうしないと、アプリケーションは IAudioSessionEvents オブジェクトと IAudioSessionControl オブジェクトが保持するリソースをリークします。RegisterAudioSessionNotification はクライアントの IAudioSessionEvents::AddRef メソッドを呼び出し、UnregisterAudioSessionNotification は IAudioSessionEvents::Release メソッドを呼び出すことに注意してください。クライアントが誤って UnregisterAudioSessionNotification を呼び出す前に IAudioSessionEvents インターフェイスへの参照を解放すると、セッションマネージャーは IAudioSessionEvents インターフェイスへの参照を決して解放しません。たとえば、設計が不十分な IAudioSessionEvents 実装では、IAudioSessionEvents オブジェクトのデストラクターから UnregisterAudioSessionNotification を呼び出す可能性があります。この場合、セッションマネージャーが IAudioSessionEvents インターフェイスへの参照を解放するまでクライアントは UnregisterAudioSessionNotification を呼び出さず、クライアントが UnregisterAudioSessionNotification を呼び出すまでセッションマネージャーは IAudioSessionEvents インターフェイスへの参照を解放しません。AddRef メソッドと Release メソッドの詳細については、Windows SDK ドキュメントの IUnknown インターフェイスに関する説明を参照してください。

さらに、クライアントは、IAudioSessionControl オブジェクトと IAudioSessionManager オブジェクトへのすべての参照を解放する前に UnregisterAudioSessionNotification を呼び出す必要があります。クライアントがこれら 2 つのオブジェクトのうち少なくとも 1 つへの参照を保持していない限り、セッションマネージャーは登録情報を保持するために割り当てたストレージをリークします。通知インターフェイスを登録した後、クライアントはこれら 2 つのオブジェクトのうち少なくとも 1 つが存在する間だけ通知を受け取り続けます。

RegisterAudioSessionNotification メソッドを呼び出すコード例については、レガシーオーディオアプリケーションのオーディオイベントを参照してください。

UnregisterAudioSessionNotification メソッドは、通知を受け取るためにクライアントが行った以前の登録を削除します。

メソッドが成功した場合は S_OK を返します。失敗した場合、戻り値には次の表に示す値が含まれますが、これらに限定されません。

クライアントは、通知を受け取る必要がなくなったときにこのメソッドを呼び出します。UnregisterAudioSessionNotification メソッドは、クライアントが以前に IAudioSessionControl::RegisterAudioSessionNotification メソッドを呼び出してセッションマネージャーに登録した IAudioSessionEvents インターフェイスの登録を削除します。

クライアントは、IAudioSessionEvents インターフェイスへの最終参照を解放する前に、UnregisterAudioSessionNotification を呼び出してインターフェイスの登録を解除する必要があります。そうしないと、アプリケーションは IAudioSessionEvents オブジェクトと IAudioSessionControl オブジェクトが保持するリソースをリークします。RegisterAudioSessionNotification はクライアントの IAudioSessionEvents::AddRef メソッドを呼び出し、UnregisterAudioSessionNotification は IAudioSessionEvents::Release メソッドを呼び出すことに注意してください。クライアントが誤って UnregisterAudioSessionNotification を呼び出す前に IAudioSessionEvents インターフェイスへの参照を解放すると、セッションマネージャーは IAudioSessionEvents インターフェイスへの参照を決して解放しません。たとえば、設計が不十分な IAudioSessionEvents 実装では、IAudioSessionEvents オブジェクトのデストラクターから UnregisterAudioSessionNotification を呼び出す可能性があります。この場合、セッションマネージャーが IAudioSessionEvents インターフェイスへの参照を解放するまでクライアントは UnregisterAudioSessionNotification を呼び出さず、クライアントが UnregisterAudioSessionNotification を呼び出すまでセッションマネージャーは IAudioSessionEvents インターフェイスへの参照を解放しません。AddRef メソッドと Release メソッドの詳細については、Windows SDK ドキュメントの IUnknown インターフェイスに関する説明を参照してください。

UnregisterAudioSessionNotification メソッドを呼び出すコード例については、レガシーオーディオアプリケーションのオーディオイベントを参照してください。