Fungsi ActivateAudioInterfaceAsync (mmdeviceapi.h)

  • Artikel

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

Sintaks

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 masing-masing tangkapan audio dan perangkat render default. Panggil StringFromIID untuk mengonversi salah satu GUID ini ke LPCWSTR untuk digunakan untuk argumen ini.

Tentukan AUDIOCLIENT_ACTIVATION_TYPE_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::Activate.

Dimulai dengan TBD, 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.

Nilai kembali

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

Menampilkan 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 IActivateAudioInterfaceCompletionHandler yang diteruskan tidak diimplementasikan pada objek tangkas (menggabungkan marshaler utas bebas).

Keterangan

Fungsi ini memungkinkan aplikasi Windows Store untuk 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 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 secara eksplisit aman ini meliputi:

  • Memanggil ActivateAudioInterfaceAsync dengan deviceInterfacePath yang menentukan perangkat render audio dan riid yang menentukan antarmuka IAudioClient .
  • Memanggil ActivateAudioInterfaceAsync dengan deviceInterfacePath yang menentukan perangkat render audio dan riid yang menentukan antarmuka IAudioEndpointVolume .
  • Memanggil ActivateAudioInterfaceAsync dari layanan sesi 0. Untuk informasi selengkapnya, lihat Layanan.
Windows memegang referensi ke antarmuka IActivateAudioInterfaceCompletionHandler aplikasi sampai operasi selesai dan aplikasi merilis antarmuka IActivateAudioInterfaceAsyncOperation .
Penting  

Aplikasi tidak boleh membebaskan objek yang mengimplementasikan IActivateAudioInterfaceCompletionHandler sampai callback 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 completionHandler dipanggil dari MTA. Jika tidak, E_ILLEGAL_METHOD_CALL akan terjadi.

Persyaratan

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

Lihat juga

Fungsi Audio Inti

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler