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

[アーティクル]
11/20/2024

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

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

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 オブジェクトを作成します。メソッドは、呼び出し元がパラメーターとして CLSID を指定しない点を除き、Windows CoCreateInstance 関数に似ています。 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 のドキュメントを参照してください。

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

Activate 呼び出しで、IDirectSound、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 のドキュメントを参照してください。

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

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

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

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

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

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

ストリームのレンダリングの
デバイストポロジ
IKsControl インターフェイスを使用してオーディオプロパティにアクセスするをする
レガシオーディオアプリケーションのオーディオイベントの
空間オーディオオブジェクトを使用して空間サウンドをレンダリングする

必要条件

要件	価値
サポートされる最小クライアント	Windows Vista [デスクトップアプリのみ]
サポートされる最小サーバー	Windows Server 2008 [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	mmdeviceapi.h

次の方法で共有

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

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース