共用方式為

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 。

指定 AUDIOCLIENT_ACTI加值稅ION_TYPE_PROCESS_LOOPBACK 以啟用進程回送擷取的音訊介面。 如需示範進程回送擷取案例的範例程式碼，請參閱 應用程式回送 API 擷取範例。

[in] riid

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

[in] activationParams

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

從 TBD 開始，您可以指定 AUDIOCLIENT_ACTI加值稅ION_PARAMS 來啟用介面，以包含或排除與指定進程識別碼相關聯的音訊資料流程。

[in] completionHandler

當啟用程式的結果可供使用時，由 Windows 呼叫的呼叫端所實作的介面。

activationOperation

會傳回 IActivateAudioInterfaceAsyncOperation 介面，表示啟用所要求 WASAPI 介面的非同步作業。

傳回值

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

傳回碼 描述
S_OK
 已成功建立基礎物件和非同步作業。
E_ILLEGAL_METHOD_CALL
在先前Windows 10的 Windows 版本上，如果從不正確的 COM Apartment 呼叫函式，或傳遞的IActivateAudioInterfaceCompletionHandler未在敏捷式物件上實作， (匯總自由執行緒封送處理器) ，則可能會產生此錯誤。

備註

此函式可讓 Windows 市集應用程式在Windows.Devices和Windows.Media.Devices命名空間中使用Windows 執行階段 API 來啟用特定WASAPI COM 介面，以選取音訊裝置。

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

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

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

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

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

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

需求

   
最低支援的用戶端 Windows 8 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2012 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 mmdeviceapi.h (包含 Mmdevapi.idl)
程式庫 Mmdevapi.lib
Dll Mmdevapi.dll
IRQL 否

另請參閱

核心音訊函式

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler