IMMDevice::Activate 方法 (mmdeviceapi.h)
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 |
---|---|
|
物件不支援要求的介面類型。 |
|
參數 ppInterface 為 NULL。 |
|
pActivationParams 參數必須是指定介面的 NULL;或 pActivationParams 指向無效的數據。 |
|
記憶體不足。 |
|
使用者已移除音訊端點裝置或端點裝置所連線的適配卡裝置。 |
備註
這個方法會建立 COM 物件,其中包含 iid 參數所指定的介面。 方法類似於 Windows CoCreateInstance 函式,不同之處在於呼叫端未提供 CLSID 做為參數。 如需 CoCreateInstance 的詳細資訊,請參閱 Windows SDK 檔。
用戶端可以針對特定音訊端點裝置呼叫 IMMDevice 介面的 Activate 方法,以取得該裝置上介面的計數參考。 方法可以啟用下列介面:
- IAudioClient
- IAudioEndpointVolume
- IAudioMeterInformation
- IAudioSessionManager
- IAudioSessionManager2
- IBaseFilter
- IDeviceTopology
- IDirectSound
- IDirectSound8
- IDirectSoundCapture
- IDirectSoundCapture8
- IMFTrustedOutput
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的一般資訊,請參閱媒體基礎檔中的。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | mmdeviceapi.h |