ホーム › Media.Audio › IMMDevice

IMMDevice

COM

📘 Microsoft Learn (日本語) · English

IIDd666063f-1587-4e43-81f1-b948e807363f継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IMMDevice インターフェイスは、マルチメディアデバイスリソースの汎用的な機能をカプセル化します。

メソッド 4

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

vtbl 3 HRESULT Activate(GUID* iid, CLSCTX dwClsCtx, PROPVARIANT* pActivationParams, void** ppInterface)

Activate メソッドは、指定されたインターフェイスを持つ COM オブジェクトを作成します。

iid	GUID*	in	インターフェイス識別子。このパラメーターは、呼び出し元がアクティブ化を要求するインターフェイスを識別する GUID への参照です。呼び出し元は、このインターフェイスを使用して COM オブジェクトと通信します。このパラメーターには、次のいずれかのインターフェイス識別子を設定します。 IID_IAudioClient IID_IAudioEndpointVolume IID_IAudioMeterInformation IID_IAudioSessionManager IID_IAudioSessionManager2 IID_IBaseFilter IID_IDeviceTopology IID_IDirectSound IID_IDirectSound8 IID_IDirectSoundCapture IID_IDirectSoundCapture8 IID_IMFTrustedOutput IID_ISpatialAudioClient IID_ISpatialAudioMetadataClient 詳細については、「解説」を参照してください。
dwClsCtx	CLSCTX	in	新しく作成されたオブジェクトを管理するコードが実行される実行コンテキスト。呼び出し元は、このパラメーターを 1 つ以上の CLSCTX 列挙値のビット単位の OR に設定することで、コンテキストを制限できます。または、CLSCTX_ALL を指定することで、コンテキストの制限を課さないようにすることもできます。CLSCTX の詳細については、Windows SDK のドキュメントを参照してください。
pActivationParams	PROPVARIANT*	inoptional	オーディオエンドポイントデバイス上で IAudioEndpointVolume、IAudioMeterInformation、IAudioSessionManager、または IDeviceTopology インターフェイスをアクティブ化する場合は、NULL を設定します。デバイス上で IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture、または IDirectSoundCapture8 インターフェイスをアクティブ化する場合、呼び出し元はストリーム初期化情報を含む PROPVARIANT 構造体へのポインターを指定できます。詳細については、「解説」を参照してください。
ppInterface	void**	out	パラメーター iid で指定されたインターフェイスのアドレスを、メソッドが書き込むポインター変数へのポインター。このメソッドを通じて、呼び出し元はインターフェイスへのカウント参照を取得します。呼び出し元は、インターフェイスが不要になったときに、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。Activate の呼び出しが失敗した場合、ppInterface は NULL* になります。

戻り値

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

戻り値	説明
E_NOINTERFACE	オブジェクトが要求されたインターフェイスの種類をサポートしていません。
E_POINTER	パラメーター ppInterface が NULL です。
E_INVALIDARG	指定されたインターフェイスでは pActivationParams パラメーターは NULL でなければなりません。または、pActivationParams が無効なデータを指しています。
E_OUTOFMEMORY	メモリ不足です。
AUDCLNT_E_DEVICE_INVALIDATED	ユーザーがオーディオエンドポイントデバイス、またはエンドポイントデバイスが接続されているアダプターデバイスのいずれかを取り外しました。

解説(Remarks)

このメソッドは、iid パラメーターで指定されたインターフェイスを持つ COM オブジェクトを作成します。このメソッドは Windows の CoCreateInstance 関数に似ていますが、呼び出し元がパラメーターとして CLSID を指定しない点が異なります。CoCreateInstance の詳細については、Windows SDK のドキュメントを参照してください。

クライアントは、特定のオーディオエンドポイントデバイスに対して IMMDevice インターフェイスの Activate メソッドを呼び出すことで、そのデバイス上のインターフェイスへのカウント参照を取得できます。このメソッドは、次のインターフェイスをアクティブ化できます。

IAudioClient
IAudioEndpointVolume
IAudioMeterInformation
IAudioSessionManager
IAudioSessionManager2
IBaseFilter
IDeviceTopology
IDirectSound
IDirectSound8
IDirectSoundCapture
IDirectSoundCapture8
IMFTrustedOutput

インターフェイスのインターフェイス ID を取得するには、__uuidof 演算子を使用します。たとえば、IAudioCaptureClient のインターフェイス ID は次のように定義されます。


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

__uuidof 演算子の詳細については、Windows SDK のドキュメントを参照してください。IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture、IDirectSoundCapture8、および IMFTrustedOutput の詳細については、Windows SDK のドキュメントを参照してください。

オーディオエンドポイントデバイスに対して IAudioEndpointVolume、IAudioMeterInformation、IAudioSessionManager、または IDeviceTopology インターフェイスを作成する Activate 呼び出しでは、pActivationParams パラメーターは NULL でなければなりません。Windows 10 Build 20348 以降では、IAudioClient をアクティブ化する呼び出し元は、pActivationParams に AUDIOCLIENT_ACTIVATION_PARAMS へのポインターを設定することで、プロセスフィルターを使用したループバックモードでオーディオクライアントを構成できます。

IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture、または IDirectSoundCapture8 インターフェイスを作成する Activate 呼び出しでは、呼び出し元はオプションとして pActivationParams に非 NULL の値を指定できます。この場合、pActivationParams はストリーム初期化情報を含む PROPVARIANT 構造体を指します。構造体の vt メンバーを VT_BLOB に設定します。blob.pBlobData メンバーを、オーディオセッション GUID とストリーム初期化フラグを含む DIRECTX_AUDIO_ACTIVATION_PARAMS 構造体を指すように設定します。blob.cbSize メンバーを sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS) に設定します。コード例については、Device Roles for DirectShow Applications を参照してください。PROPVARIANT の詳細については、Windows SDK のドキュメントを参照してください。

Activate メソッドによって作成される IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture、または IDirectSoundCapture8 インターフェイスのインスタンスは、オーディオエンドポイントデバイス上のストリームをカプセル化します。Activate 呼び出しの間に、DirectSound システムモジュールは IAudioClient::Initialize メソッドを呼び出してストリームを作成します。pActivationParams が非 NULL の場合、DirectSound は DIRECTX_AUDIO_ACTIVATION_PARAMS 構造体のオーディオセッション GUID とストリーム初期化フラグを、Initialize 呼び出しの入力パラメーターとして渡します。pActivationParams が NULL の場合、DirectSound は Initialize メソッドの AudioSessionGuid パラメーターと StreamFlags パラメーターを、それぞれの既定値である NULL と 0 に設定します。これらの値は、セッション GUID 値 GUID_NULL で識別されるプロセス固有のセッションにストリームを割り当てるようメソッドに指示します。

Activate は、レンダリングエンドポイントデバイス上でのみ IDirectSound または IDirectSound8 インターフェイスをアクティブ化できます。キャプチャエンドポイントデバイス上でのみ IDirectSoundCapture または IDirectSoundCapture8 インターフェイスをアクティブ化できます。キャプチャデバイス上で IDirectSound または IDirectSound8 インターフェイスをアクティブ化する、あるいはレンダリングデバイス上で IDirectSoundCapture または IDirectSoundCapture8 インターフェイスをアクティブ化する Activate 呼び出しは失敗し、エラーコード E_NOINTERFACE を返します。

Windows 7 では、クライアントは IMMDevice::Activate を呼び出して IID_IMFTrustedOutput を指定することで、Output Trust Authority (OTA) オブジェクトを作成し、そのオブジェクトの IMFTrustedOutput インターフェイスへのポインターを取得できます。OTA は Media Foundation の Protected Media Path (PMP) の内側または外側で動作でき、Media Foundation パイプラインの外部にコンテンツを送信できます。呼び出し元が PMP の外部にある場合、OTA は PMP 内では動作できず、保護設定はより堅牢性の低いものになります。オーディオ用の保護されたオブジェクトの使用方法とサンプルコードについては、Protected User Mode Audio (PUMA) を参照してください。

保護されたオブジェクトと IMFTrustedOutput に関する一般的な情報については、Media Foundation のドキュメントの「Protected Media Path」を参照してください。

注意 Xbox One Development Kit (XDK) タイトルで ISpatialAudioClient インターフェイスを使用する場合は、IMMDeviceEnumerator::EnumAudioEndpoints または IMMDeviceEnumerator::GetDefaultAudioEndpoint を呼び出す前に、まず EnableSpatialAudio を呼び出す必要があります。これを行わないと、Activate の呼び出しから E_NOINTERFACE エラーが返されます。EnableSpatialAudio は XDK タイトルでのみ使用でき、Xbox One 上で動作するユニバーサル Windows プラットフォームアプリや、Xbox One 以外のデバイスでは呼び出す必要はありません。

Activate メソッドを呼び出すコード例については、次のトピックを参照してください。

vtbl 4 HRESULT OpenPropertyStore(STGM stgmAccess, IPropertyStore** ppProperties)

OpenPropertyStore メソッドは、デバイスのプロパティストアへのインターフェイスを取得します。

stgmAccess

STGM

ストレージアクセスモード。このパラメーターは、プロパティストアを読み取りモード、書き込みモード、または読み取り/書き込みモードのいずれで開くかを指定します。このパラメーターには、次のいずれかの STGM 定数を設定します。

STGM_READ

STGM_WRITE

STGM_READWRITE

このメソッドでは、管理者として実行されているクライアントが、読み取り専用、書き込み専用、または読み取り/書き込みアクセスでストアを開くことができます。管理者として実行されていないクライアントは、読み取り専用アクセスに制限されます。STGM 定数の詳細については、Windows SDK のドキュメントを参照してください。

ppProperties

IPropertyStore**

out

デバイスのプロパティストアの IPropertyStore インターフェイスのアドレスを、メソッドが書き込むポインター変数へのポインター。このメソッドを通じて、呼び出し元はインターフェイスへのカウント参照を取得します。呼び出し元は、インターフェイスが不要になったときに、そのインターフェイスの Release メソッドを呼び出して解放する責任があります。OpenPropertyStore の呼び出しが失敗した場合、*ppProperties は NULL になります。IPropertyStore の詳細については、Windows SDK のドキュメントを参照してください。

戻り値

戻り値	説明
E_INVALIDARG	パラメーター stgmAccess が有効なアクセスモードではありません。
E_POINTER	パラメーター ppProperties が NULL です。
E_OUTOFMEMORY	メモリ不足です。

解説(Remarks)

一般に、デバイスのプロパティストア内のプロパティは、管理機能、システム機能、またはサービス機能を実行しないクライアントにとっては読み取り専用です。

OpenPropertyStore メソッドを呼び出すコード例については、次のトピックを参照してください。

vtbl 5 HRESULT GetId(LPWSTR* ppstrId)

GetId メソッドは、オーディオエンドポイントデバイスを識別するエンドポイント ID 文字列を取得します。

ppstrId

LPWSTR*

out

エンドポイントデバイス ID を含む、NULL 終端のワイド文字列のアドレスを、メソッドが書き込むポインター変数へのポインター。メソッドが文字列用の記憶領域を割り当てます。呼び出し元は、その記憶領域が不要になったときに、CoTaskMemFree 関数を呼び出して解放する責任があります。GetId の呼び出しが失敗した場合、*ppstrId は NULL になります。 CoTaskMemFree の詳細については、Windows SDK のドキュメントを参照してください。

戻り値

戻り値	説明
E_OUTOFMEMORY	メモリ不足です。
E_POINTER	パラメーター pwstrId が NULL です。

解説(Remarks)

このメソッドから取得されるエンドポイント ID 文字列は、IMMDevice インターフェイスインスタンスによって表されるオーディオエンドポイントデバイスを識別します。クライアントは、このエンドポイント ID 文字列を使用して、後の時点または別のプロセスで IMMDeviceEnumerator::GetDevice メソッドを呼び出すことで、オーディオエンドポイントデバイスのインスタンスを作成できます。クライアントは、エンドポイント ID 文字列の内容を不透明なものとして扱う必要があります。つまり、クライアントはデバイスに関する情報を取得するために文字列の内容を解析しようとすべきではありません。その理由は、文字列の形式が未定義であり、MMDevice API システムモジュールの実装によって異なる場合があるためです。

GetId メソッドを呼び出すコード例については、次のトピックを参照してください。

vtbl 6 HRESULT GetState(DEVICE_STATE* pdwState)

GetState メソッドは、現在のデバイスの状態を取得します。

pdwState

DEVICE_STATE*

out

デバイスの現在の状態を、メソッドが書き込む DWORD 変数へのポインター。デバイス状態の値は、次の DEVICE_STATE_XXX 定数のいずれかです。

DEVICE_STATE_ACTIVE

DEVICE_STATE_DISABLED

DEVICE_STATE_NOTPRESENT

DEVICE_STATE_UNPLUGGED

戻り値

戻り値	説明
E_POINTER	パラメーター pdwState が NULL です。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMMDevice "{D666063F-1587-4E43-81F1-B948E807363F}"
#usecom global IMMDevice IID_IMMDevice "{}"
#comfunc global IMMDevice_Activate           3 var,int,var,sptr
#comfunc global IMMDevice_OpenPropertyStore  4 int,sptr
#comfunc global IMMDevice_GetId              5 var
#comfunc global IMMDevice_GetState           6 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMMDevice "{D666063F-1587-4E43-81F1-B948E807363F}"
#usecom global IMMDevice IID_IMMDevice "{}"
#comfunc global IMMDevice_Activate           3 sptr,int,sptr,sptr
#comfunc global IMMDevice_OpenPropertyStore  4 int,sptr
#comfunc global IMMDevice_GetId              5 sptr
#comfunc global IMMDevice_GetState           6 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。