ActivateAudioInterfaceAsync 関数 (mmdeviceapi.h)

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

Windows ストアアプリが、WASAPI ファミリ内の既存のコンポーネントオブジェクトモデル (COM) インターフェイスにアクセスできるようにします。

構文

HRESULT ActivateAudioInterfaceAsync(
  [in] LPCWSTR                                  deviceInterfacePath,
  [in] REFIID                                   riid,
  [in] PROPVARIANT                              *activationParams,
  [in] IActivateAudioInterfaceCompletionHandler *completionHandler,
       IActivateAudioInterfaceAsyncOperation    **activationOperation
);

パラメーター

[in] deviceInterfacePath

オーディオデバイスのデバイスインターフェイス ID。これは通常、DeviceInformation オブジェクトまたは MediaDevice クラスのいずれかのメソッドから取得されます。

GUID DEVINTERFACE_AUDIO_CAPTURE と DEVINTERFACE_AUDIO_RENDER は、それぞれ既定のオーディオキャプチャとレンダーデバイスを表します。 StringFromIID 呼び出して、これらの GUID のいずれかを、この引数に使用する LPCWSTR に変換します。

プロセスループバックキャプチャのオーディオインターフェイスをアクティブ化する AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK を指定します。プロセスループバックキャプチャシナリオを示すサンプルコードについては、アプリケーションループバック API キャプチャのサンプルを参照してください。

[in] riid

IAudioClientなど、WASAPI ファミリ内の COM インターフェイスの IID。

[in] activationParams

インターフェイス固有のアクティブ化パラメーター。詳細については、IMMDevice::Activateの pActivationParams パラメーターを参照してください。

Windows 10 ビルド 20438 以降では、インターフェイスをアクティブ化する AUDIOCLIENT_ACTIVATION_PARAMS を指定して、指定したプロセス ID に関連付けられているオーディオストリームを含めたり除外したりできます。

[in] completionHandler

アクティブ化プロシージャの結果が使用可能な場合に Windows によって呼び出される呼び出し元によって実装されるインターフェイス。

activationOperation

要求された WASAPI インターフェイスをアクティブ化する非同期操作を表す IActivateAudioInterfaceAsyncOperation インターフェイスを返します。

戻り値

この関数は、HRESULTを返します。使用できる値には、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	形容
S_OK	基になるオブジェクトと非同期操作が正常に作成されました。
E_ILLEGAL_METHOD_CALL	Windows 10 より前のバージョンの Windows では、関数が正しくない COM アパートメントから呼び出された場合、または渡された IActivateAudioInterfaceCompletionHandler がアジャイルオブジェクトに実装されていない場合 (フリースレッドマーシャラーを集約する) 場合、このエラーが発生する可能性があります。

備考

この関数を使用すると、Windows ストアアプリは、Windows.Devices で Windows ランタイム API を使用した後、特定の WASAPI COM インターフェイスをアクティブ化し、Windows.Media.Devices 名前空間をしてオーディオデバイスを選択できます。

多くの実装では、システムがダイアログをユーザーに表示できるように、アプリケーションでメイン UI スレッドからこの関数を呼び出して、WASAPI ファミリの COM インターフェイスをアクティブ化する必要があります。アプリケーションは、completionHandlerを介して IActivateAudioInterfaceCompletionHandler コールバック COM インターフェイスを渡します。 Windows は、アクティブ化の結果が使用可能な場合、COM マルチスレッドアパートメント (MTA) のワーカースレッドから、アプリケーションの IActivateAudioInterfaceCompletionHandler インターフェイス内のメソッドを呼び出します。その後、アプリケーションは IActivateAudioInterfaceAsyncOperation インターフェイスでメソッドを呼び出して、結果コードと WASAPI インターフェイス要求されたメソッドを取得できます。明示的に安全であり、メイン UI スレッドからこの関数を呼び出す必要がないアクティブ化がいくつかあります。これらの明示的に安全なアクティブ化には、次のようなものがあります。

オーディオレンダーデバイス を指定する deviceInterfacePath と、IAudioClient インターフェイスを指定する riid を使用して、ActivateAudioInterfaceAsync を呼び出します。
オーディオレンダーデバイス 指定する deviceInterfacePath と、IAudioEndpointVolume インターフェイスを指定する riid を使用して、ActivateAudioInterfaceAsync を呼び出します。
セッション 0 サービスから ActivateAudioInterfaceAsync 呼び出します。詳細については、「Services」を参照してください。

Windows は、操作が完了し、アプリケーションが IActivateAudioInterfaceAsyncOperation インターフェイスを解放するまで、アプリケーションの IActivateAudioInterfaceCompletionHandler インターフェイスへの参照を保持します。

重要な

アプリケーションは、完了ハンドラーコールバックが実行されるまで、IActivateAudioInterfaceCompletionHandler を実装するオブジェクトを解放してはなりません。

WASAPI インターフェイスがアクティブ化されるによっては、この関数が初めて呼び出されたときに同意プロンプトが表示される場合があります。たとえば、アプリケーションがこの関数を呼び出して、マイクにアクセスするために IAudioClient アクティブ化する場合、同意プロンプトの目的は、アプリがマイクにアクセスするためのユーザーのアクセス許可を取得することです。同意プロンプトの詳細については、「個人データにアクセスするデバイスのガイドラインを参照してください。

ActivateAudioInterfaceAsync は、同意プロンプトを表示できるように、メイン UI スレッドで呼び出す必要があります。同意プロンプトを表示できない場合、ユーザーはデバイスにアプリへのアクセス権を付与できません。

Windows 10 より前のバージョンの Windows では、オーディオキャプチャ用にデバイスを開くときに、COM Single-Threaded アパートメント (STA) のスレッドで ActivateAudioInterfaceAsync を呼び出す必要があります。 ActivateAudioInterfaceAsync に渡される completionHandler は、completionHandler が MTA から呼び出されたときにデッドロックが発生しないように、IAgileObject を実装する必要があります。それ以外の場合は、E_ILLEGAL_METHOD_CALL が発生します。

必要条件

要件	価値
サポートされる最小クライアント	Windows 8 [デスクトップアプリ \|UWP アプリ]
サポートされる最小サーバー	Windows Server 2012 [デスクトップアプリ \|UWP アプリ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	mmdeviceapi.h (Mmdevapi.idl を含む)
ライブラリ	Mmdevapi.lib
DLL	Mmdevapi.dll
IRQL	いいえ

次の方法で共有

ActivateAudioInterfaceAsync 関数 (mmdeviceapi.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース