IMMDevice：：Activate 方法 (mmdeviceapi.h)

發行項
03/05/2024

Activate 方法會建立具有指定介面的 COM 物件。

語法

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

參數

[in] iid

介面識別碼。此參數是 GUID 的參考，可識別呼叫端要求啟動的介面。呼叫端會使用此介面與 COM 物件通訊。將此參數設定為下列其中一個介面識別碼：

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

如需詳細資訊，請參閱＜備註＞。

[in] dwClsCtx

執行內容，其中管理新建立物件的程式代碼將會執行。呼叫端可以藉由將此參數設定為一或多個 CLSCTX 列舉值的位 OR 來限制內容。或者，用戶端可以藉由指定CLSCTX_ALL來避免造成任何內容限制。如需 CLSCTX 的詳細資訊，請參閱 Windows SDK 檔。

[in] pActivationParams

設定為 NULL 以啟動音訊端點裝置上的 IAudioClient、 IAudioEndpointVolume、 IAudioMeterInformation、 IAudioSessionManager 或 IDeviceTopology 介面。在裝置上啟動 IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture 或 IDirectSoundCapture8 介面時，呼叫端可以指定包含數據流初始化資訊的 PROPVARIANT 結構的指標。如需詳細資訊，請參閱＜備註＞。

[out] ppInterface

指標變數的指標，方法會寫入參數 iid 所指定的介面位址。透過這個方法，呼叫端會取得介面的計數參考。呼叫端負責藉由呼叫介面的 Release 方法，在不再需要介面時釋出介面。如果 Activate 呼叫失敗， *ppInterface 為 NULL。

傳回值

如果方法成功，它會傳回 S_OK。如果失敗，可能的傳回碼包括，但不限於下表所示的值。

傳回碼	Description
E_NOINTERFACE	物件不支援要求的介面類型。
E_POINTER	參數 ppInterface 為 NULL。
E_INVALIDARG	pActivationParams 參數必須是指定介面的 NULL;或 pActivationParams 指向無效的數據。
E_OUTOFMEMORY	記憶體不足。
AUDCLNT_E_DEVICE_INVALIDATED	使用者已移除音訊端點裝置或端點裝置所連線的適配卡裝置。

備註

這個方法會建立 COM 物件，其中包含 iid 參數所指定的介面。方法類似於 Windows CoCreateInstance 函式，不同之處在於呼叫端未提供 CLSID 做為參數。如需 CoCreateInstance 的詳細資訊，請參閱 Windows SDK 檔。

用戶端可以針對特定音訊端點裝置呼叫 IMMDevice 介面的 Activate 方法，以取得該裝置上介面的計數參考。方法可以啟用下列介面：

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

若要取得介面的介面標識碼，請使用 __uuidof 運算符。例如， IAudioCaptureClient 的介面標識碼定義如下：


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

如需__uuidof運算符的相關信息，請參閱 Windows SDK 檔。如需 IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture、IDirectSoundCapture8 和 IMFTrustedOutput 的相關信息，請參閱 Windows SDK 檔。

pActivationParams 參數應該是 NULL，可讓 Activate 呼叫建立音訊端點裝置的 IAudioClient、IAudioEndpointVolume、IAudioMeterInformation、IAudioSessionManager 或 IDeviceTopology 介面。

若要讓 Activate 呼叫建立 IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture 或 IDirectSoundCapture8 介面，呼叫端可以做為選項指定 pActivationParams 的非 NULL 值。在此情況下， pActivationParams 會指向包含數據流初始化資訊的 PROPVARIANT 結構。將結構的 vt 成員設定為 VT_BLOB。將 blob.pBlobData 成員設定為指向包含音訊會話 GUID 和數據流初始化旗標的 DIRECTX_AUDIO_ACTIVATION_PARAMS 結構。將 blob.cbSize 成員設定為 sizeof (DIRECTX_AUDIO_ACTIVATION_PARAMS) 。如需程式代碼範例，請參閱 DirectShow 應用程式的裝置角色。如需 PROPVARIANT 的詳細資訊，請參閱 Windows SDK 檔。

由 Activate 方法所建立的 IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture 或 IDirectSoundCapture8 介面實例會封裝音頻端點裝置上的數據流。在 Activate 呼叫期間，DirectSound 系統模組會呼叫 IAudioClient：：Initialize 方法來建立數據流。如果 pActivationParams 不是 NULL，DirectSound 會從 DIRECTX_AUDIO_ACTIVATION_PARAMS 結構提供音訊會話 GUID 和數據流初始化旗標作為初始化呼叫的輸入參數。如果 pActivationParams 為 NULL，DirectSound 會將 Initialize 方法的 AudioSessionGuid 和 StreamFlags 參數設定為其各自的預設值 NULL 和 0。這些值會指示方法將數據流指派給會話 GUID 值所識別的進程特定會話GUID_NULL。

Activate 只能在轉譯端點裝置上啟用 IDirectSound 或 IDirectSound8 介面。它只能在擷取端點裝置上啟用 IDirectSoundCapture 或 IDirectSoundCapture8 介面。在擷取裝置或轉譯裝置上的 IDirectSoundCapture8 介面或 IDirectSoundCapture8 介面上啟動 IDirectSound 或 IDirectSoundCapture8 介面的 Activate 呼叫會失敗，並傳回錯誤碼E_NOINTERFACE。

在 Windows 7 中，用戶端可以呼叫 IMMDevice：：Activate 並指定 、IID_IMFTrustedOutput，以建立輸出信任授權單位 (OTA) 物件，並擷取物件的 IMFTrustedOutput 介面指標。 OTA 可以在媒體基礎的受保護媒體路徑內部或外部運作， (PMP) ，並在 Media Foundation 管線外部傳送內容。如果呼叫端位於 PMP 外部，則 OTA 可能無法在 PMP 中運作，且保護設定較不健全。如需使用受保護物件進行音訊和範例程式代碼的相關信息，請參閱受保護的使用者模式音訊 (PUMA) 。

如需受保護物件和 IMFTrustedOutput的一般資訊，請參閱媒體基礎檔中的。

注意在 Xbox One 開發工具包上使用 ISpatialAudioClient 介面 (XDK) 標題時，您必須先呼叫 EnableSpatialAudio ，再呼叫 IMMDeviceEnumerator：：EnumAudioEndpoints 或 IMMDeviceEnumerator：：GetDefaultAudioEndpoint。若無法這麼做，會導致從呼叫 Activate 傳回E_NOINTERFACE錯誤。 EnableSpatialAudio 僅適用於 XDK 標題，不需要針對在 Xbox One 上執行的通用 Windows 平台應用程式呼叫，也不需要針對任何非 Xbox One 裝置呼叫。

如需呼叫 Activate 方法的程式代碼範例，請參閱下列主題：

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	mmdeviceapi.h