ホーム › Media.Audio › ActivateAudioInterfaceAsync

ActivateAudioInterfaceAsync

関数

指定デバイスのオーディオインターフェイスを非同期でアクティブ化する。

DLLMMDevAPI.dll呼出規約winapi対応OSwindows8.0

シグネチャ

// MMDevAPI.dll
#include <windows.h>

HRESULT ActivateAudioInterfaceAsync(
    LPCWSTR deviceInterfacePath,
    const GUID* riid,
    PROPVARIANT* activationParams,   // optional
    IActivateAudioInterfaceCompletionHandler* completionHandler,
    IActivateAudioInterfaceAsyncOperation** activationOperation
);

パラメーター

名前	型	方向	説明
deviceInterfacePath	LPCWSTR	in	オーディオデバイスのデバイスインターフェイス ID。通常は DeviceInformation オブジェクト、または MediaDevice クラスのいずれかのメソッドから取得します。 GUID DEVINTERFACE_AUDIO_CAPTURE と DEVINTERFACE_AUDIO_RENDER は、それぞれ既定のオーディオキャプチャデバイスとレンダリングデバイスを表します。これらの GUID を本引数に使用する LPCWSTR に変換するには、StringFromIID を呼び出してください。プロセスループバックキャプチャのためにオーディオインターフェイスをアクティブ化するには、VIRTUAL_AUDIO_DEVICE_PROCESS_LOOPBACK を指定します。プロセスループバックキャプチャのシナリオを示すサンプルコードについては、Application Loopback API Capture Sample を参照してください。
riid	GUID*	in	WASAPI ファミリに属する COM インターフェイスの IID。たとえば IAudioClient などです。
activationParams	PROPVARIANT*	inoptional	インターフェイス固有のアクティブ化パラメーター。詳細については、IMMDevice::Activate の pActivationParams パラメーターを参照してください。 Windows 10 Build 20438 以降では、指定したプロセス ID に関連付けられたオーディオストリームを含めたり除外したりするようにインターフェイスをアクティブ化するために、AUDIOCLIENT_ACTIVATION_PARAMS を指定できます。
completionHandler	IActivateAudioInterfaceCompletionHandler*	in	呼び出し元が実装するインターフェイスで、アクティブ化処理の結果が利用可能になったときに Windows によって呼び出されます。
activationOperation	IActivateAudioInterfaceAsyncOperation**	out	要求された WASAPI インターフェイスをアクティブ化する非同期操作を表す IActivateAudioInterfaceAsyncOperation インターフェイスを返します。

戻り値の型: HRESULT

公式ドキュメント

Windows ストアアプリが WASAPI ファミリの既存の Component Object Model (COM) インターフェイスにアクセスできるようにします。

戻り値

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

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

解説(Remarks)

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

多くの実装では、システムがユーザーにダイアログを表示できるように、アプリケーションはメイン UI スレッドからこの関数を呼び出して WASAPI ファミリの COM インターフェイスをアクティブ化する必要があります。アプリケーションは、IActivateAudioInterfaceCompletionHandler コールバック COM インターフェイスを completionHandler を通じて渡します。アクティブ化の結果が利用可能になると、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 では、オーディオキャプチャ用にデバイスを開くときに、ActivateAudioInterfaceAsync は COM のシングルスレッドアパートメント (STA) 内のスレッドで呼び出す必要があります。ActivateAudioInterfaceAsync に渡される completionHandler は、MTA から completionHandler が呼び出されたときにデッドロックが発生しないように、IAgileObject を実装する必要があります。そうでない場合は E_ILLEGAL_METHOD_CALL が発生します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// MMDevAPI.dll
#include <windows.h>

HRESULT ActivateAudioInterfaceAsync(
    LPCWSTR deviceInterfacePath,
    const GUID* riid,
    PROPVARIANT* activationParams,   // optional
    IActivateAudioInterfaceCompletionHandler* completionHandler,
    IActivateAudioInterfaceAsyncOperation** activationOperation
);

[DllImport("MMDevAPI.dll", ExactSpelling = true)]
static extern int ActivateAudioInterfaceAsync(
    [MarshalAs(UnmanagedType.LPWStr)] string deviceInterfacePath,   // LPCWSTR
    ref Guid riid,   // GUID*
    IntPtr activationParams,   // PROPVARIANT* optional
    IntPtr completionHandler,   // IActivateAudioInterfaceCompletionHandler*
    IntPtr activationOperation   // IActivateAudioInterfaceAsyncOperation** out
);

<DllImport("MMDevAPI.dll", ExactSpelling:=True)>
Public Shared Function ActivateAudioInterfaceAsync(
    <MarshalAs(UnmanagedType.LPWStr)> deviceInterfacePath As String,   ' LPCWSTR
    ByRef riid As Guid,   ' GUID*
    activationParams As IntPtr,   ' PROPVARIANT* optional
    completionHandler As IntPtr,   ' IActivateAudioInterfaceCompletionHandler*
    activationOperation As IntPtr   ' IActivateAudioInterfaceAsyncOperation** out
) As Integer
End Function

' deviceInterfacePath : LPCWSTR
' riid : GUID*
' activationParams : PROPVARIANT* optional
' completionHandler : IActivateAudioInterfaceCompletionHandler*
' activationOperation : IActivateAudioInterfaceAsyncOperation** out
Declare PtrSafe Function ActivateAudioInterfaceAsync Lib "mmdevapi" ( _
    ByVal deviceInterfacePath As LongPtr, _
    ByVal riid As LongPtr, _
    ByVal activationParams As LongPtr, _
    ByVal completionHandler As LongPtr, _
    ByVal activationOperation As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

ActivateAudioInterfaceAsync = ctypes.windll.mmdevapi.ActivateAudioInterfaceAsync
ActivateAudioInterfaceAsync.restype = ctypes.c_int
ActivateAudioInterfaceAsync.argtypes = [
    wintypes.LPCWSTR,  # deviceInterfacePath : LPCWSTR
    ctypes.c_void_p,  # riid : GUID*
    ctypes.c_void_p,  # activationParams : PROPVARIANT* optional
    ctypes.c_void_p,  # completionHandler : IActivateAudioInterfaceCompletionHandler*
    ctypes.c_void_p,  # activationOperation : IActivateAudioInterfaceAsyncOperation** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MMDevAPI.dll')
ActivateAudioInterfaceAsync = Fiddle::Function.new(
  lib['ActivateAudioInterfaceAsync'],
  [
    Fiddle::TYPE_VOIDP,  # deviceInterfacePath : LPCWSTR
    Fiddle::TYPE_VOIDP,  # riid : GUID*
    Fiddle::TYPE_VOIDP,  # activationParams : PROPVARIANT* optional
    Fiddle::TYPE_VOIDP,  # completionHandler : IActivateAudioInterfaceCompletionHandler*
    Fiddle::TYPE_VOIDP,  # activationOperation : IActivateAudioInterfaceAsyncOperation** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "mmdevapi")]
extern "system" {
    fn ActivateAudioInterfaceAsync(
        deviceInterfacePath: *const u16,  // LPCWSTR
        riid: *const GUID,  // GUID*
        activationParams: *mut PROPVARIANT,  // PROPVARIANT* optional
        completionHandler: *mut core::ffi::c_void,  // IActivateAudioInterfaceCompletionHandler*
        activationOperation: *mut *mut core::ffi::c_void  // IActivateAudioInterfaceAsyncOperation** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MMDevAPI.dll")]
public static extern int ActivateAudioInterfaceAsync([MarshalAs(UnmanagedType.LPWStr)] string deviceInterfacePath, ref Guid riid, IntPtr activationParams, IntPtr completionHandler, IntPtr activationOperation);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MMDevAPI_ActivateAudioInterfaceAsync' -Namespace Win32 -PassThru
# $api::ActivateAudioInterfaceAsync(deviceInterfacePath, riid, activationParams, completionHandler, activationOperation)

#uselib "MMDevAPI.dll"
#func global ActivateAudioInterfaceAsync "ActivateAudioInterfaceAsync" sptr, sptr, sptr, sptr, sptr
; ActivateAudioInterfaceAsync deviceInterfacePath, varptr(riid), varptr(activationParams), completionHandler, activationOperation   ; 戻り値は stat
; deviceInterfacePath : LPCWSTR -> "sptr"
; riid : GUID* -> "sptr"
; activationParams : PROPVARIANT* optional -> "sptr"
; completionHandler : IActivateAudioInterfaceCompletionHandler* -> "sptr"
; activationOperation : IActivateAudioInterfaceAsyncOperation** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "MMDevAPI.dll"
#cfunc global ActivateAudioInterfaceAsync "ActivateAudioInterfaceAsync" wstr, var, var, sptr, sptr
; res = ActivateAudioInterfaceAsync(deviceInterfacePath, riid, activationParams, completionHandler, activationOperation)
; deviceInterfacePath : LPCWSTR -> "wstr"
; riid : GUID* -> "var"
; activationParams : PROPVARIANT* optional -> "var"
; completionHandler : IActivateAudioInterfaceCompletionHandler* -> "sptr"
; activationOperation : IActivateAudioInterfaceAsyncOperation** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "MMDevAPI.dll"
#cfunc global ActivateAudioInterfaceAsync "ActivateAudioInterfaceAsync" wstr, sptr, sptr, sptr, sptr
; res = ActivateAudioInterfaceAsync(deviceInterfacePath, varptr(riid), varptr(activationParams), completionHandler, activationOperation)
; deviceInterfacePath : LPCWSTR -> "wstr"
; riid : GUID* -> "sptr"
; activationParams : PROPVARIANT* optional -> "sptr"
; completionHandler : IActivateAudioInterfaceCompletionHandler* -> "sptr"
; activationOperation : IActivateAudioInterfaceAsyncOperation** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。