Fungsi ActivateAudioInterfaceAsync (mmdeviceapi.h)

Memungkinkan aplikasi Windows Store untuk mengakses antarmuka Model Objek Komponen (COM) yang sudah ada sebelumnya dalam keluarga WASAPI .

Sintaksis

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

Parameter

[in] deviceInterfacePath

ID antarmuka perangkat untuk perangkat audio. Ini biasanya diambil dari objek DeviceInformation atau salah satu metode kelas MediaDevice.

GUID DEVINTERFACE_AUDIO_CAPTURE dan DEVINTERFACE_AUDIO_RENDER mewakili perangkat pengambilan dan penyajian audio default. Panggil StringFromIID untuk mengonversi salah satu GUID ini ke LPCWSTR yang akan digunakan untuk argumen ini.

Tentukan VIRTUAL_AUDIO_DEVICE_PROCESS_LOOPBACK untuk mengaktifkan antarmuka audio untuk pengambilan loopback proses. Untuk kode sampel yang menunjukkan skenario pengambilan loopback proses, lihat Sampel Pengambilan API Loopback Aplikasi .

[in] riid

IID antarmuka COM dalam keluarga WASAPI, seperti IAudioClient.

[in] activationParams

Parameter aktivasi khusus antarmuka. Untuk informasi selengkapnya, lihat parameter pActivationParams di IMMDevice::Aktifkan.

Dimulai dengan Windows 10 Build 20438, Anda dapat menentukan AUDIOCLIENT_ACTIVATION_PARAMS untuk mengaktifkan antarmuka untuk menyertakan atau mengecualikan aliran audio yang terkait dengan ID proses tertentu.

[in] completionHandler

Antarmuka yang diimplementasikan oleh pemanggil yang dipanggil oleh Windows ketika hasil prosedur aktivasi tersedia.

activationOperation

Mengembalikan antarmuka IActivateAudioInterfaceAsyncOperation yang mewakili operasi asinkron untuk mengaktifkan antarmuka WASAPI yang diminta.

Mengembalikan nilai

Fungsi mengembalikanHRESULT . Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.

Mengembalikan kode	Deskripsi
S_OK	Objek yang mendasar dan operasi asinkron berhasil dibuat.
E_ILLEGAL_METHOD_CALL	Pada versi Windows sebelumnya ke Windows 10, kesalahan ini dapat mengakibatkan jika fungsi dipanggil dari apartemen COM yang salah, atau jika yang diteruskan IActivateAudioInterfaceCompletionHandler tidak diimplementasikan pada objek agile (menggabungkan marshaler utas bebas).

Komentar

Fungsi ini memungkinkan aplikasi Windows Store mengaktifkan antarmuka WASAPI COM tertentu setelah menggunakan WINDOWS Runtime API di namespace Windows.Devices dan Windows.Media.Devices untuk memilih perangkat audio.

Untuk banyak implementasi, aplikasi harus memanggil fungsi ini dari utas UI utama untuk mengaktifkan antarmuka COM dalam keluarga WASAPI sehingga sistem dapat menampilkan dialog kepada pengguna. Aplikasi ini melewati antarmuka COM panggilan balik IActivateAudioInterfaceCompletionHandler melalui completionHandler. Windows memanggil metode dalam antarmuka IActivateAudioInterfaceCompletionHandler aplikasi dari utas pekerja di COM Multi-threaded Apartment (MTA) ketika hasil aktivasi tersedia. Aplikasi kemudian dapat memanggil metode di antarmuka IActivateAudioInterfaceAsyncOperation untuk mengambil kode hasil dan antarmuka WASAPI yang diminta. Ada beberapa aktivasi yang secara eksplisit aman dan oleh karena itu tidak mengharuskan fungsi ini dipanggil dari utas UI utama. Aktivasi yang aman secara eksplisit ini meliputi:

• Memanggil ActivateAudioInterfaceAsync dengan perangkat InterfacePath yang menentukan perangkat render audio dan riid yang menentukan antarmuka IAudioClient .
• Memanggil ActivateAudioInterfaceAsync dengan perangkat InterfacePath yang menentukan perangkat render audio dan riid yang menentukan antarmuka IAudioEndpointVolume .
• Memanggil ActivateAudioInterfaceAsync dari layanan sesi 0. Untuk informasi selengkapnya, lihatLayanan .

Windows menyimpan referensi ke antarmuka aplikasi IActivateAudioInterfaceCompletionHandler hingga operasi selesai dan aplikasi merilis antarmuka IActivateAudioInterfaceAsyncOperation.

Penting  

Aplikasi tidak boleh membebaskan objek yang mengimplementasikan IActivateAudioInterfaceCompletionHandler hingga panggilan balik handler penyelesaian telah dijalankan.

 

Bergantung pada antarmuka WASAPI mana yang diaktifkan, fungsi ini dapat menampilkan permintaan persetujuan saat pertama kali dipanggil. Misalnya, ketika aplikasi memanggil fungsi ini untuk mengaktifkan IAudioClient untuk mengakses mikrofon, tujuan dari permintaan persetujuan adalah untuk mendapatkan izin pengguna agar aplikasi dapat mengakses mikrofon. Untuk informasi selengkapnya tentang permintaan persetujuan, lihat Panduan untuk perangkat yang mengakses data pribadi.

ActivateAudioInterfaceAsync harus dipanggil pada utas UI utama sehingga prompt persetujuan dapat ditampilkan. Jika permintaan persetujuan tidak dapat ditampilkan, pengguna tidak dapat memberikan akses perangkat ke aplikasi.

Pada versi Windows sebelumnya ke Windows 10, ActivateAudioInterfaceAsync harus dipanggil pada utas di COM Single-Threaded Apartment (STA), saat membuka perangkat untuk pengambilan audio. completionHandler yang diteruskan ke ActivateAudioInterfaceAsync perlu menerapkan IAgileObject untuk memastikan bahwa tidak ada kebuntuan ketika penyelesaian Handler dipanggil dari MTA. Jika tidak, E_ILLEGAL_METHOD_CALL akan terjadi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 8 [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung	Windows Server 2012 [aplikasi desktop | Aplikasi UWP]
Platform Target	Windows
Header	mmdeviceapi.h (termasuk Mmdevapi.idl)
Pustaka	Mmdevapi.lib
DLL	Mmdevapi.dll
IRQL	Tidak

Lihat juga

Core Audio Functions

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler