IMMDevice::Aktifkan metode (mmdeviceapi.h)

Artikel
03/15/2023

Metode Aktifkan membuat objek COM dengan antarmuka yang ditentukan.

Sintaks

HRESULT Activate(
  [in]  REFIID      iid,
  [in]  DWORD       dwClsCtx,
  [in]  PROPVARIANT *pActivationParams,
  [out] void        **ppInterface
);

Parameter

[in] iid

Pengidentifikasi antarmuka. Parameter ini adalah referensi ke GUID yang mengidentifikasi antarmuka yang permintaan pemanggil diaktifkan. Pemanggil akan menggunakan antarmuka ini untuk berkomunikasi dengan objek COM. Atur parameter ini ke salah satu pengidentifikasi antarmuka berikut:

IID_IAudioClient

IID_IAudioEndpointVolume

IID_IAudioMeterInformation

IID_IAudioSessionManager

IID_IAudioSessionManager2

IID_IBaseFilter

IID_IDeviceTopology

IID_IDirectSound

IID_IDirectSound8

IID_IDirectSoundCapture

IID_IDirectSoundCapture8

IID_IMFTrustedOutput

IID_ISpatialAudioClient

IID_ISpatialAudioMetadataClient

Untuk informasi selengkapnya, lihat Keterangan.

[in] dwClsCtx

Konteks eksekusi di mana kode yang mengelola objek yang baru dibuat akan berjalan. Pemanggil dapat membatasi konteks dengan mengatur parameter ini ke bitwise OR dari satu atau beberapa nilai enumerasi CLSCTX . Atau, klien dapat menghindari pembatasan konteks apa pun dengan menentukan CLSCTX_ALL. Untuk informasi selengkapnya tentang CLSCTX, lihat dokumentasi Windows SDK.

[in] pActivationParams

Atur ke NULL untuk mengaktifkan antarmuka IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, atau IDeviceTopology pada perangkat titik akhir audio. Saat mengaktifkan antarmuka IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, atau IDirectSoundCapture8 pada perangkat, pemanggil dapat menentukan penunjuk ke struktur PROPVARIANT yang berisi informasi inisialisasi aliran. Untuk informasi selengkapnya, lihat Keterangan.

[out] ppInterface

Pointer ke variabel pointer tempat metode menulis alamat antarmuka yang ditentukan oleh parameter iid. Melalui metode ini, pemanggil mendapatkan referensi yang dihitung ke antarmuka. Pemanggil bertanggung jawab untuk merilis antarmuka, ketika tidak lagi diperlukan, dengan memanggil metode Rilis antarmuka. Jika panggilan Aktifkan gagal, *ppInterface adalah NULL.

Nilai kembali

Jika metode berhasil, metode akan mengembalikan S_OK. Jika gagal, kemungkinan kode pengembalian disertakan, tetapi tidak terbatas pada, nilai yang diperlihatkan dalam tabel berikut.

Menampilkan kode	Deskripsi
E_NOINTERFACE	Objek tidak mendukung tipe antarmuka yang diminta.
E_POINTER	Parameter ppInterface adalah NULL.
E_INVALIDARG	Parameter pActivationParams harus NULL untuk antarmuka yang ditentukan; atau pActivationParams menunjuk ke data yang tidak valid.
E_OUTOFMEMORY	Kehabisan memori.
AUDCLNT_E_DEVICE_INVALIDATED	Pengguna telah menghapus perangkat titik akhir audio atau perangkat adaptor tempat perangkat titik akhir tersambung.

Keterangan

Metode ini membuat objek COM dengan antarmuka yang ditentukan oleh parameter iid . Metode ini mirip dengan fungsi Windows CoCreateInstance , kecuali bahwa pemanggil tidak menyediakan CLSID sebagai parameter. Untuk informasi selengkapnya tentang CoCreateInstance, lihat dokumentasi Windows SDK.

Klien dapat memanggil metode Aktifkan antarmuka IMMDevice untuk perangkat titik akhir audio tertentu untuk mendapatkan referensi yang dihitung ke antarmuka pada perangkat tersebut. Metode ini dapat mengaktifkan antarmuka berikut:

IAudioClient
IAudioEndpointVolume
IAudioMeterInformation
IAudioSessionManager
IAudioSessionManager2
IBaseFilter
IDeviceTopology
IDirectSound
IDirectSound8
IDirectSoundCapture
IDirectSoundCapture8
IMFTrustedOutput

Untuk mendapatkan ID antarmuka untuk antarmuka, gunakan operator __uuidof . Misalnya, ID antarmuka IAudioCaptureClient didefinisikan sebagai berikut:


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Untuk informasi tentang operator __uuidof , lihat dokumentasi Windows SDK. Untuk informasi tentang IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8, dan IMFTrustedOutput lihat dokumentasi Windows SDK.

Parameter pActivationParams harus NULL untuk panggilan Aktifkan untuk membuat antarmuka IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, atau IDeviceTopology untuk perangkat titik akhir audio.

Untuk panggilan Aktifkan untuk membuat antarmuka IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, atau IDirectSoundCapture8 , pemanggil dapat, sebagai opsi, menentukan nilai non-NULL untuk pActivationParams. Dalam hal ini, pActivationParams menunjuk ke struktur PROPVARIANT yang berisi informasi inisialisasi aliran. Atur anggota vt struktur ke VT_BLOB. Atur anggota blob.pBlobData untuk menunjuk ke struktur DIRECTX_AUDIO_ACTIVATION_PARAMS yang berisi GUID sesi audio dan bendera inisialisasi aliran. Atur anggota blob.cbSize ke sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Untuk contoh kode, lihat Peran Perangkat untuk Aplikasi DirectShow. Untuk informasi selengkapnya tentang PROPVARIANT, lihat dokumentasi Windows SDK.

Instans antarmuka IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, atau IDirectSoundCapture8 yang dibuat oleh metode Activate merangkum aliran pada perangkat titik akhir audio. Selama panggilan Aktifkan , modul sistem DirectSound membuat aliran dengan memanggil metode IAudioClient::Initialize . Jika pActivationParamsnon-NULL, DirectSound menyediakan GUID sesi audio dan bendera stream-initialization dari struktur DIRECTX_AUDIO_ACTIVATION_PARAMS sebagai parameter input ke panggilan Inisialisasi . Jika pActivationParamsADALAH NULL, DirectSound mengatur parameter AudioSessionGuid dan StreamFlags metode Inisialisasi ke nilai default masing-masing, NULL dan 0. Nilai-nilai ini menginstruksikan metode untuk menetapkan aliran ke sesi khusus proses yang diidentifikasi oleh nilai GUID sesi GUID_NULL.

Aktifkan hanya dapat mengaktifkan antarmuka IDirectSound atau IDirectSound8 pada perangkat titik akhir penyajian. Ini dapat mengaktifkan antarmuka IDirectSoundCapture atau IDirectSoundCapture8 hanya pada perangkat titik akhir pengambilan. Panggilan Aktifkan untuk mengaktifkan antarmuka IDirectSound atau IDirectSoundCapture8 pada perangkat tangkapan atau antarmuka IDirectSoundCapture atau IDirectSoundCapture8 pada perangkat penyajian gagal dan mengembalikan kode kesalahan E_NOINTERFACE.

Di Windows 7, klien dapat memanggil IMMDevice::Aktifkan dan tentukan, IID_IMFTrustedOutput, untuk membuat objek otoritas kepercayaan output (OTA) dan mengambil penunjuk ke antarmuka IMFTrustedOutput objek. OTAs dapat beroperasi di dalam atau di luar jalur media yang dilindungi Media Foundation (PMP) dan mengirim konten di luar alur Media Foundation. Jika penelepon berada di luar PMP, maka OTA mungkin tidak beroperasi di PMP, dan pengaturan perlindungan kurang kuat. Untuk informasi tentang menggunakan objek yang dilindungi untuk audio dan kode contoh, lihat Audio Mode Pengguna Terlindungi (PUMA).

Untuk informasi umum tentang objek yang dilindungi dan IMFTrustedOutput, lihat "Jalur Media Terlindungi" dalam dokumentasi Media Foundation.

Catatan Saat menggunakan antarmuka ISpatialAudioClient pada judul Xbox One Development Kit (XDK), Anda harus terlebih dahulu memanggil EnableSpatialAudio sebelum memanggil IMMDeviceEnumerator::EnumAudioEndpoints atau IMMDeviceEnumerator::GetDefaultAudioEndpoint. Kegagalan untuk melakukannya akan mengakibatkan kesalahan E_NOINTERFACE dikembalikan dari panggilan ke Aktifkan. EnableSpatialAudio hanya tersedia untuk judul XDK, dan tidak perlu dipanggil untuk aplikasi Platform Windows Universal yang berjalan di Xbox One, atau untuk perangkat non-Xbox One.

Untuk contoh kode yang memanggil metode Aktifkan , lihat topik berikut:

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	mmdeviceapi.h