IMMDevice::Activate メソッド (mmdeviceapi.h)

[アーティクル]
08/24/2023

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

構文

HRESULT Activate(
  [in]  REFIID      iid,
  [in]  DWORD       dwClsCtx,
  [in]  PROPVARIANT *pActivationParams,
  [out] void        **ppInterface
);

パラメーター

[in] iid

インターフェイス識別子。このパラメーターは、呼び出し元がアクティブ化を要求するインターフェイスを識別する 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

詳細については、「解説」を参照してください。

[in] dwClsCtx

新しく作成されたオブジェクトを管理するコードが実行される実行コンテキスト。呼び出し元は、このパラメーターを 1 つ以上の CLSCTX 列挙値のビットごとの OR に設定することで、コンテキストを制限できます。または、CLSCTX_ALLを指定することで、クライアントがコンテキスト制限を課さないようにすることもできます。 CLSCTX の詳細については、Windows SDKドキュメントを参照してください。

[in] pActivationParams

オーディオエンドポイントデバイスで IAudioClient、IAudioEndpointVolume、IAudioMeterInformation、IAudioSessionManager、または IDeviceTopology インターフェイスをアクティブ化するには、NULL に設定します。デバイスで IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture、または IDirectSoundCapture8 インターフェイスをアクティブ化する場合、呼び出し元はストリーム初期化情報を含む PROPVARIANT 構造体へのポインターを指定できます。詳細については、「解説」を参照してください。

[out] ppInterface

メソッドがパラメーター iid で指定されたインターフェイスのアドレスを書き込むポインター変数へのポインター。このメソッドを使用して、呼び出し元はインターフェイスへのカウントされた参照を取得します。呼び出し元は、インターフェイスの Release メソッドを呼び出すことによって、不要になったインターフェイスを解放する必要があります。 Activate 呼び出しが失敗した場合、*ppInterface は NULL です。

戻り値

メソッドが成功した場合は、S_OK を返します。エラーが発生した場合、次の表に示す値が、可能なリターンコードに含まれますが、これらに限定されません。

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

注釈

このメソッドは、 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ドキュメントを参照してください。

オーディオエンドポイントデバイスの IAudioClient、IAudioEndpointVolume、IAudioMeterInformation、IAudioSessionManager、または IDeviceTopology インターフェイスを作成するには、Activate 呼び出しの pActivationParams パラメーターを NULL にする必要があります。

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

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

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

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

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

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

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

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	mmdeviceapi.h