可讓 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。 可能的值包括但不限於下表中的值。
回傳碼 | 說明 |
---|---|
|
已成功建立基礎對象和異步作。 |
|
在 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 (MTA) 中的背景工作線程呼叫應用程式 IActivateAudioInterfaceCompletionHandler 介面中的方法。 然後,應用程式可以在 IActivateAudioInterfaceAsyncOperation 介面中呼叫方法,以擷取結果碼和要求的 WASAPI 介面。 有一些明確安全的啟用,因此不需要從主要UI線程呼叫此函式。 這些明確安全的啟用包括:
- 使用指定音頻轉譯裝置的 deviceInterfacePath 和指定 IAudioClient 介面的 riid 呼叫 ActivateAudioInterfaceAsync。
- 使用指定音訊轉譯裝置的 deviceInterfacePath 呼叫 ActivateAudioInterfaceAsync,以及指定 IAudioEndpointVolume 介面的 riid。
- 從會話 0 服務呼叫 ActivateAudioInterfaceAsync 。 如需詳細資訊,請參閱 服務。
在完成處理程式回呼執行之前,應用程式不得釋放實作 IActivateAudioInterfaceCompletionHandler 的物件。
必須在主要UI線程上呼叫ActivateAudioInterfaceAsync,才能顯示同意提示。 如果無法顯示同意提示,使用者就無法授與裝置對應用程式的存取權。
在 Windows 10 之前的 Windows 版本上,在開啟裝置進行音訊擷取時,必須在 COM Single-Threaded Apartment (STA) 的線程上呼叫 ActivateAudioInterfaceAsync 。 傳遞至 ActivateAudioInterfaceAsync 的 completionHandler 必須實作 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 | 否 |