IMMDevice::Activate 方法 (mmdeviceapi.h)
Activate 方法使用指定的接口创建 COM 对象。
语法
HRESULT Activate(
[in] REFIID iid,
[in] DWORD dwClsCtx,
[in] PROPVARIANT *pActivationParams,
[out] void **ppInterface
);
参数
[in] iid
接口标识符。 此参数是对 GUID 的引用,该 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。 如果失败,可能的返回代码包括但不限于下表中显示的值。
返回代码 | 说明 |
---|---|
|
对象不支持请求的接口类型。 |
|
参数 ppInterface 为 NULL。 |
|
对于指定的接口, pActivationParams 参数必须为 NULL ;或 pActivationParams 指向无效数据。 |
|
内存不足。 |
|
用户已删除音频终结点设备或终结点设备连接到的适配器设备。 |
注解
此方法使用 iid 参数指定的接口创建 COM 对象。 方法类似于 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文档。
对于为音频终结点设备创建 IAudioClient、IAudioEndpointVolume、IAudioMeterInformation、IAudioSessionManager 或 IDeviceTopology 接口的 Activate 调用,pActivationParams 参数应为 NULL。
对于用于创建 IBaseFilter、IDirectSound、IDirectSound8、IDirectSoundCapture 或 IDirectSoundCapture8 接口的 Activate 调用,调用方可以指定 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、IDirectSound、IDirectSoundCapture 或 IDirectSoundCapture8 接口实例封装音频终结点设备上的流。 在 Activate 调用期间,DirectSound 系统模块通过调用 IAudioClient::Initialize 方法创建流。 如果 pActivationParams 为非 NULL,DirectSound 会将来自 DIRECTX_AUDIO_ACTIVATION_PARAMS 结构的音频会话 GUID 和流初始化标志作为输入参数提供给 Initialize 调用。 如果 pActivationParams 为 NULL,DirectSound 会将 Initialize 方法的 AudioSessionGuid 和 StreamFlags 参数设置为各自的默认值 NULL 和 0。 这些值指示方法将流分配给由会话 GUID 值GUID_NULL标识的特定于进程的会话。
Activate 只能在呈现终结点设备上激活 IDirectSound 或 IDirectSound8 接口。 它只能在捕获终结点设备上激活 IDirectSoundCapture 或 IDirectSoundCapture8 接口。 激活调用以激活捕获设备上的 IDirectSound 或 IDirectSoundCapture8 接口或呈现设备上的 IDirectSoundCapture 或 IDirectSoundCapture8 接口失败,并返回错误代码E_NOINTERFACE。
在 Windows 7 中,客户端可以调用 IMMDevice::Activate 并指定 (IID_IMFTrustedOutput)以 (OTA) 对象创建输出信任机构,并检索指向对象的 IMFTrustedOutput 接口的指针。 OTA 可以在媒体基础的受保护媒体路径内部或外部运行, (PMP) 并在媒体基础管道外发送内容。 如果调用方在 PMP 外部,则 OTA 可能无法在 PMP 中运行,并且保护设置不太可靠。 有关将受保护的对象用于音频和示例代码的信息,请参阅 受保护的用户模式音频 (PUMA) 。
有关受保护对象和 IMFTrustedOutput 的一般信息,请参阅媒体基础文档中的“受保护的媒体路径”。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows Vista [仅限桌面应用] |
最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
目标平台 | Windows |
标头 | mmdeviceapi.h |