ホーム › Media.Audio › IAudioSessionEvents

IAudioSessionEvents

COM

📘 Microsoft Learn (日本語) · English

IID24918acc-64b3-37c1-8ca9-74a66e9957a8継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IAudioSessionEvents インターフェイスは、音量レベル、表示名、セッション状態の変更など、セッションに関連するイベントの通知を提供します。

メソッド 7

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT OnDisplayNameChanged(LPWSTR NewDisplayName, GUID* EventContext)

OnDisplayNameChanged メソッドは、セッションの表示名が変更されたことをクライアントに通知します。

NewDisplayName	LPWSTR	in	セッションの新しい表示名です。このパラメーターは、新しい表示名を含む、null で終わるワイド文字列を指します。この文字列は呼び出しの間のみ有効です。
EventContext	GUID*	in	イベントコンテキスト値です。これは、セッションの表示名を変更した呼び出しで、呼び出し元が IAudioSessionControl::SetDisplayName に渡したのと同じ値です。詳細については、「解説」を参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

セッションマネージャーは、IAudioSessionControl::SetDisplayName メソッドの呼び出しによってセッションの表示名が変更されるたびに、このメソッドを呼び出します。Sndvol プログラムは、セッションの表示名を使用して、そのセッションの音量スライダーにラベルを付けます。

EventContext パラメーターは、クライアントが自ら開始した表示名の変更と、他のクライアントが開始した変更とを区別する手段を提供します。IAudioSessionControl::SetDisplayName メソッドを呼び出す際、クライアントは、自身の OnDisplayNameChanged メソッドの実装が認識できる EventContext パラメーター値を渡します。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

vtbl 4 HRESULT OnIconPathChanged(LPWSTR NewIconPath, GUID* EventContext)

OnIconPathChanged メソッドは、セッションの表示アイコンが変更されたことをクライアントに通知します。

NewIconPath	LPWSTR	in	セッションの新しい表示アイコンのパスです。このパラメーターは、新しいアイコンのパスを含む文字列を指します。この文字列ポインターは呼び出しの間のみ有効です。
EventContext	GUID*	in	イベントコンテキスト値です。これは、セッションの表示アイコンを変更した呼び出しで、呼び出し元が IAudioSessionControl::SetIconPath に渡したのと同じ値です。詳細については、「解説」を参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

セッションマネージャーは、IAudioSessionControl::SetIconPath メソッドの呼び出しによってセッションの表示アイコンが変更されるたびに、このメソッドを呼び出します。Sndvol プログラムは、セッションの表示アイコンを使用して、そのセッションの音量スライダーにラベルを付けます。

EventContext パラメーターは、クライアントが自ら開始した表示アイコンの変更と、他のクライアントが開始した変更とを区別する手段を提供します。IAudioSessionControl::SetIconPath メソッドを呼び出す際、クライアントは、自身の OnIconPathChanged メソッドの実装が認識できる EventContext パラメーター値を渡します。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

vtbl 5 HRESULT OnSimpleVolumeChanged(FLOAT NewVolume, BOOL NewMute, GUID* EventContext)

OnSimpleVolumeChanged メソッドは、オーディオセッションの音量レベルまたはミュート状態が変更されたことをクライアントに通知します。

NewVolume	FLOAT	in	オーディオセッションの新しい音量レベルです。このパラメーターは 0.0 から 1.0 の範囲の値で、0.0 は無音、1.0 は最大音量 (減衰なし) を表します。
NewMute	BOOL	in	新しいミュート状態です。TRUE の場合、ミュートが有効です。FALSE の場合、ミュートが無効です。
EventContext	GUID*	in	イベントコンテキスト値です。これは、セッションの音量レベルまたはミュート状態を変更した呼び出しで、呼び出し元が ISimpleAudioVolume::SetMasterVolume または ISimpleAudioVolume::SetMute に渡したのと同じ値です。詳細については、「解説」を参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

セッションマネージャーは、ISimpleAudioVolume::SetMasterVolume または ISimpleAudioVolume::SetMute メソッドの呼び出しによってセッションの音量レベルまたはミュート状態が変更されるたびに、このメソッドを呼び出します。

EventContext パラメーターは、クライアントが自ら開始した音量またはミュートの変更と、他のクライアントが開始した変更とを区別する手段を提供します。ISimpleAudioVolume::SetMasterVolume または ISimpleAudioVolume::SetMute メソッドを呼び出す際、クライアントは、自身の OnSimpleVolumeChanged メソッドの実装が認識できる EventContext パラメーター値を渡します。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

vtbl 6 HRESULT OnChannelVolumeChanged(DWORD ChannelCount, FLOAT* NewChannelVolumeArray, DWORD ChangedChannel, GUID* EventContext)

OnChannelVolumeChanged メソッドは、セッションサブミックス内のオーディオチャネルの音量レベルが変更されたことをクライアントに通知します。

ChannelCount	DWORD	in	チャネル数です。このパラメーターは、セッションサブミックス内のオーディオチャネルの数を指定します。
NewChannelVolumeArray	FLOAT*	in	音量レベルの配列へのポインターです。各要素は float 型の値で、特定のチャネルの音量レベルを指定します。各音量レベルは 0.0 から 1.0 の範囲の値で、0.0 は無音、1.0 は最大音量 (減衰なし) を表します。配列の要素数は ChannelCount パラメーターで指定されます。オーディオストリームに n 個のチャネルが含まれる場合、チャネルには 0 から n– 1 までの番号が付けられます。チャネル番号に一致するインデックスの配列要素には、そのチャネルの音量レベルが格納されます。この配列は呼び出しの間のみ有効であるとみなしてください。
ChangedChannel	DWORD	in	音量レベルが変更されたチャネルの番号です。この値を NewChannelVolumeArray 配列へのインデックスとして使用します。セッションサブミックスに n 個のチャネルが含まれる場合、チャネルには 0 から n– 1 までの番号が付けられます。複数のチャネルが変更された可能性がある場合 (たとえば IChannelAudioVolume::SetAllVolumes メソッドの呼び出しの結果として)、ChangedChannel の値は (DWORD)(–1) になります。
EventContext	GUID*	in	イベントコンテキスト値です。これは、チャネルの音量レベルの変更を開始した呼び出しで、呼び出し元が IChannelAudioVolume::SetChannelVolume または IChannelAudioVolume::SetAllVolumes メソッドに渡したのと同じ値です。詳細については、「解説」を参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

セッションマネージャーは、IChannelAudioVolume::SetChannelVolume または IChannelAudioVolume::SetAllVolumes メソッドの呼び出しがセッションサブミックス内の 1 つ以上のチャネルの音量レベルを正常に更新するたびに、このメソッドを呼び出します。OnChannelVolumeChanged の呼び出しは、新しいチャネル音量レベルが以前のチャネル音量レベルと値が異なるかどうかにかかわらず発生することに注意してください。

EventContext パラメーターは、クライアントが自ら開始したチャネル音量の変更と、他のクライアントが開始した変更とを区別する手段を提供します。IChannelAudioVolume::SetChannelVolume または IChannelAudioVolume::SetAllVolumes メソッドを呼び出す際、クライアントは、自身の OnChannelVolumeChanged メソッドの実装が認識できる EventContext パラメーター値を渡します。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

vtbl 7 HRESULT OnGroupingParamChanged(GUID* NewGroupingParam, GUID* EventContext)

OnGroupingParamChanged メソッドは、セッションのグループ化パラメーターが変更されたことをクライアントに通知します。

NewGroupingParam	GUID*	in	セッションの新しいグループ化パラメーターです。このパラメーターは、グループ化パラメーターの GUID を指します。
EventContext	GUID*	in	イベントコンテキスト値です。これは、セッションのグループ化パラメーターを変更した呼び出しで、呼び出し元が IAudioSessionControl::SetGroupingParam に渡したのと同じ値です。詳細については、「解説」を参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

セッションマネージャーは、IAudioSessionControl::SetGroupingParam メソッドの呼び出しによってセッションのグループ化パラメーターが変更されるたびに、このメソッドを呼び出します。

EventContext パラメーターは、クライアントが自ら開始したグループ化パラメーターの変更と、他のクライアントが開始した変更とを区別する手段を提供します。IAudioSessionControl::SetGroupingParam メソッドを呼び出す際、クライアントは、自身の OnGroupingParamChanged メソッドの実装が認識できる EventContext パラメーター値を渡します。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

vtbl 8 HRESULT OnStateChanged(AudioSessionState NewState)

OnStateChanged メソッドは、セッションのストリームアクティビティ状態が変更されたことをクライアントに通知します。

NewState

AudioSessionState

新しいセッション状態です。このパラメーターの値は、次の AudioSessionState 列挙値のいずれかです。

AudioSessionStateActive

AudioSessionStateInactive

AudioSessionStateExpired

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

クライアントはセッション状態変更イベントを生成できません。この種類のイベントの発生源は常にシステムです。したがって、他の一部の IAudioSessionEvents メソッドとは異なり、このメソッドはコンテキストパラメーターを提供しません。

システムは、クライアントがセッション内の最初のストリームを開いた時点で、セッションの状態を非アクティブからアクティブに変更します。クライアントは IAudioClient::Initialize メソッドを呼び出してストリームを開きます。システムは、クライアントがセッション内の最後のストリームを閉じた時点で、セッション状態をアクティブから非アクティブに変更します。IAudioClient オブジェクトへの最後の参照を解放したクライアントが、そのオブジェクトに関連付けられたストリームを閉じます。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

vtbl 9 HRESULT OnSessionDisconnected(AudioSessionDisconnectReason DisconnectReason)

OnSessionDisconnected メソッドは、オーディオセッションが切断されたことをクライアントに通知します。

DisconnectReason

AudioSessionDisconnectReason

オーディオセッションが切断された理由です。呼び出し元は、このパラメーターを次の表に示す AudioSessionDisconnectReason 列挙値のいずれかに設定します。

値	説明
DisconnectReasonDeviceRemoval	ユーザーがオーディオエンドポイントデバイスを取り外しました。
DisconnectReasonServerShutdown	Windows オーディオサービスが停止しました。
DisconnectReasonFormatChanged	オーディオセッションが接続されているデバイスのストリーム形式が変更されました。
DisconnectReasonSessionLogoff	ユーザーが、オーディオセッションが実行されていた Windows ターミナルサービス (WTS) セッションからログオフしました。
DisconnectReasonSessionDisconnected	オーディオセッションが実行されていた WTS セッションが切断されました。
DisconnectReasonExclusiveModeOverride	排他モード接続のためにオーディオエンドポイントデバイスを使用可能にする目的で、(共有モードの) オーディオセッションが切断されました。

WTS セッションの詳細については、Windows SDK のドキュメントを参照してください。

戻り値

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

解説(Remarks)

セッションを切断する際、セッションマネージャーはそのセッションに属するストリームを閉じ、それらのストリームに対する未処理のサービス要求をすべて無効にします。クライアントは切断に応答して、閉じられたストリームの IAudioClient インターフェイスへの参照をすべて解放し、以前に IAudioClient::GetService メソッドの呼び出しを通じて取得したサービスインターフェイスへの参照をすべて解放する必要があります。

切断後、切断されたセッション内の閉じられたストリームに関連付けられた WASAPI インターフェイスのメソッドの多くは、エラーコード AUDCLNT_E_DEVICE_INVALIDATED を返します (たとえば IAudioClient::GetCurrentPadding を参照)。このエラーからの回復方法については、「Recovering from an Invalid-Device Error」を参照してください。

Windows オーディオサービスが予期せず終了した場合、シャットダウン中であることをクライアントに通知する機会がありません。その場合、クライアントは、IAudioClient::GetCurrentPadding のようなメソッドを呼び出したときに、サービスがもう実行されていないことが判明してエラーコード AUDCLNT_E_SERVICE_NOT_RUNNING で失敗することで、サービスが停止したことを知ります。

クライアントはセッション切断イベントを生成できません。この種類のイベントの発生源は常にシステムです。したがって、他の一部の IAudioSessionEvents メソッドとは異なり、このメソッドにはコンテキストパラメーターがありません。

IAudioSessionEvents インターフェイスのメソッドを実装するコード例については、「Audio Session Events」を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IAudioSessionEvents "{24918ACC-64B3-37C1-8CA9-74A66E9957A8}"
#usecom global IAudioSessionEvents IID_IAudioSessionEvents "{}"
#comfunc global IAudioSessionEvents_OnDisplayNameChanged    3 wstr,var
#comfunc global IAudioSessionEvents_OnIconPathChanged       4 wstr,var
#comfunc global IAudioSessionEvents_OnSimpleVolumeChanged   5 float,int,var
#comfunc global IAudioSessionEvents_OnChannelVolumeChanged  6 int,var,int,var
#comfunc global IAudioSessionEvents_OnGroupingParamChanged  7 var,var
#comfunc global IAudioSessionEvents_OnStateChanged          8 int
#comfunc global IAudioSessionEvents_OnSessionDisconnected   9 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IAudioSessionEvents "{24918ACC-64B3-37C1-8CA9-74A66E9957A8}"
#usecom global IAudioSessionEvents IID_IAudioSessionEvents "{}"
#comfunc global IAudioSessionEvents_OnDisplayNameChanged    3 wstr,sptr
#comfunc global IAudioSessionEvents_OnIconPathChanged       4 wstr,sptr
#comfunc global IAudioSessionEvents_OnSimpleVolumeChanged   5 float,int,sptr
#comfunc global IAudioSessionEvents_OnChannelVolumeChanged  6 int,sptr,int,sptr
#comfunc global IAudioSessionEvents_OnGroupingParamChanged  7 sptr,sptr
#comfunc global IAudioSessionEvents_OnStateChanged          8 int
#comfunc global IAudioSessionEvents_OnSessionDisconnected   9 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。