共用方式為


ActivateAudioInterfaceAsync 函式 (mmdeviceapi.h)

可讓 Windows 市集應用程式存取 WASAPI 系列中預先存在的元件物件模型 (COM) 介面。

語法

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

參數

[in] deviceInterfacePath

音訊裝置的裝置介面標識碼。 這通常是從 DeviceInformation 物件或 MediaDevice 類別的其中一個方法擷取。

GUID DEVINTERFACE_AUDIO_CAPTURE 和DEVINTERFACE_AUDIO_RENDER分別代表預設音訊擷取和轉 裝置。 呼叫 StringFromIID,將這些 GUID 轉換成 LPCWSTR 以用於這個自變數。

指定 VIRTUAL_AUDIO_DEVICE_PROCESS_LOOPBACK 以啟用進程回送擷取的音訊介面。 如需示範進程回送擷取案例的範例程式代碼,請參閱 應用程式回送 API 擷取範例

[in] riid

WASAPI 系列中 COM 介面的 IID,例如 IAudioClient

[in] activationParams

介面特定的啟用參數。 如需詳細資訊,請參閱 IMMDevice::Activate 中的 pActivationParams 參數。

從 Windows 10 組建 20438 開始,您可以指定 AUDIOCLIENT_ACTIVATION_PARAMS 來啟用介面,以包含或排除與指定進程標識符相關聯的音訊數據流。

[in] completionHandler

呼叫端所實作的介面,可在啟用程序的結果可供使用時由 Windows 呼叫。

activationOperation

會傳回 IActivateAudioInterfaceAsyncOperation 介面,表示啟動所要求 WASAPI 介面的異步作。

返回值

函式會傳回 HRESULT。 可能的值包括但不限於下表中的值。

回傳碼 說明
S_OK
已成功建立基礎對象和異步作。
E_ILLEGAL_METHOD_CALL
在 Windows 10 之前的 Windows 版本上,如果函式從不正確的 COM Apartment 呼叫,或傳遞的 IActivateAudioInterfaceCompletionHandler 未在敏捷式對象上實作(匯總自由線程封送處理器),則此錯誤可能會造成。

備註

此函式可讓 Windows 市集應用程式在 Windows.DevicesWindows.Media.Devices 命名空間中使用 Windows 運行時間 API 來選取音訊裝置之後,啟用特定的 WASAPI COM 介面。

對於許多實作,應用程式必須從主要UI線程呼叫此函式,以啟動 WASAPI 系列中的 COM 介面,讓系統可以向使用者顯示對話框。 應用程式會透過 completionHandler 傳遞 IActivateAudioInterfaceCompletionHandler 回呼 COM 介面。 當啟用結果可用時,Windows 會從 COM 多線程 Apartment (MTA) 中的背景工作線程呼叫應用程式 IActivateAudioInterfaceCompletionHandler 介面中的方法。 然後,應用程式可以在 IActivateAudioInterfaceAsyncOperation 介面中呼叫方法,以擷取結果碼和要求的 WASAPI 介面。 有一些明確安全的啟用,因此不需要從主要UI線程呼叫此函式。 這些明確安全的啟用包括:

  • 使用指定音頻轉譯裝置的 deviceInterfacePath 和指定 IAudioClient 介面的 riid 呼叫 ActivateAudioInterfaceAsync
  • 使用指定音訊轉譯裝置的 deviceInterfacePath 呼叫 ActivateAudioInterfaceAsync,以及指定 IAudioEndpointVolume 介面的 riid
  • 從會話 0 服務呼叫 ActivateAudioInterfaceAsync 。 如需詳細資訊,請參閱 服務
Windows 會保存應用程式的 IActivateAudioInterfaceCompletionHandler 介面參考,直到作業完成,且應用程式會釋放 IActivateAudioInterfaceAsyncOperation 介面。
重要  

在完成處理程式回呼執行之前,應用程式不得釋放實作 IActivateAudioInterfaceCompletionHandler 的物件。

 
視啟動 WASAPI 介面而定,此函式可能會在第一次呼叫時顯示同意提示。 例如,當應用程式呼叫此函式來啟用 IAudioClient 以存取麥克風時,同意提示的目的是取得應用程式存取麥克風的許可權。 如需同意提示的詳細資訊,請參閱 存取個人資料之裝置的指導方針

必須在主要UI線程上呼叫ActivateAudioInterfaceAsync,才能顯示同意提示。 如果無法顯示同意提示,使用者就無法授與裝置對應用程式的存取權。

在 Windows 10 之前的 Windows 版本上,在開啟裝置進行音訊擷取時,必須在 COM Single-Threaded Apartment (STA) 的線程上呼叫 ActivateAudioInterfaceAsync 。 傳遞至 ActivateAudioInterfaceAsynccompletionHandler 必須實作 IAgileObject,以確保從 MTA 呼叫 completionHandler 時沒有死結。 否則,會發生 E_ILLEGAL_METHOD_CALL

需求

要求 價值觀
最低支援的用戶端 Windows 8 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2012 [傳統型應用程式 |UWP 應用程式]
目標平臺 窗戶
頁眉 mmdeviceapi.h (include Mmdevapi.idl)
圖書館 Mmdevapi.lib
DLL Mmdevapi.dll
IRQL

另請參閱

核心音訊函式

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler