ActivateAudioInterfaceAsync 関数 (mmdeviceapi.h)

  • [アーティクル]

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を指定して、プロセス ループバック キャプチャのオーディオ インターフェイスをアクティブにします。 プロセス ループバック キャプチャ シナリオを示すサンプル コードについては、「 Application Loopback API Capture Sample」を参照してください。

[in] riid

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

[in] activationParams

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

TBD 以降では、 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.Media.Devices 名前空間でWindows 运行时 API を使用してオーディオ デバイスを選択した後、特定の WASAPI COM インターフェイスをアクティブ化できます。

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

  • オーディオ レンダリング デバイスを指定する deviceInterfacePath と IAudioClient インターフェイスを指定する riid を使用して ActivateAudioInterfaceAsync を呼び出します。
  • オーディオ レンダリング デバイスを指定する deviceInterfacePath と IAudioEndpointVolume インターフェイスを指定する riid を使用して ActivateAudioInterfaceAsync を呼び出します。
  • セッション 0 サービスから ActivateAudioInterfaceAsync を呼び出す。 詳細については、「 サービス」を参照してください。
Windows は、操作が完了し、アプリケーションが IActivateAudioInterfaceAsyncOperation インターフェイスを解放するまで、アプリケーションの IActivateAudioInterfaceCompletionHandler インターフェイスへの参照を保持します。
重要  

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

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

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

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

要件

   
サポートされている最小のクライアント Windows 8 [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2012 [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー mmdeviceapi.h (mmdevapi.idl を含む)
Library Mmdevapi.lib
[DLL] Mmdevapi.dll
IRQL いいえ

関連項目

コア オーディオ関数

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler