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 可激活音频终结点设备上的 IAudioClientIAudioEndpointVolumeIAudioMeterInformationIAudioSessionManagerIDeviceTopology 接口。 在设备上激活 IBaseFilterIDirectSoundIDirectSound8IDirectSoundCaptureIDirectSoundCapture8 接口时,调用方可以指定指向包含流初始化信息的 PROPVARIANT 结构的指针。 有关详细信息,请参阅“备注”。

[out] ppInterface

指向指针变量的指针,方法在其中写入参数 iid 指定的接口的地址。 通过此方法,调用方获取对 接口的计数引用。 调用方负责在不再需要接口时通过调用接口的 Release 方法释放接口。 如果 Activate 调用失败, 则 *ppInterfaceNULL

返回值

如果该方法成功,则它会返回 S_OK。 如果失败,可能的返回代码包括但不限于下表中显示的值。

返回代码 说明
E_NOINTERFACE
对象不支持请求的接口类型。
E_POINTER
参数 ppInterfaceNULL
E_INVALIDARG
对于指定的接口, pActivationParams 参数必须为 NULL ;或 pActivationParams 指向无效数据。
E_OUTOFMEMORY
内存不足。
AUDCLNT_E_DEVICE_INVALIDATED
用户已删除音频终结点设备或终结点设备连接到的适配器设备。

注解

此方法使用 iid 参数指定的接口创建 COM 对象。 方法类似于 Windows CoCreateInstance 函数,只是调用方不提供 CLSID 作为参数。 有关 CoCreateInstance 的详细信息,请参阅Windows SDK文档。

客户端可以为特定音频终结点设备调用 IMMDevice 接口的 Activate 方法,以获取对该设备接口的计数引用。 方法可以激活以下接口:

若要获取接口的接口 ID,请使用 __uuidof 运算符。 例如, IAudioCaptureClient 的接口 ID 定义如下:

const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

有关 __uuidof 运算符的信息,请参阅 Windows SDK 文档。 有关 IBaseFilterIDirectSoundIDirectSound8IDirectSoundCaptureIDirectSoundCapture8IMFTrustedOutput 的信息,请参阅Windows SDK文档。

对于为音频终结点设备创建 IAudioClientIAudioEndpointVolumeIAudioMeterInformationIAudioSessionManagerIDeviceTopology 接口的 Activate 调用,pActivationParams 参数应为 NULL

对于用于创建 IBaseFilterIDirectSound、IDirectSound8IDirectSoundCaptureIDirectSoundCapture8 接口的 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 方法创建的 IBaseFilterIDirectSoundIDirectSound、IDirectSoundCaptureIDirectSoundCapture8 接口实例封装音频终结点设备上的流。 Activate 调用期间,DirectSound 系统模块通过调用 IAudioClient::Initialize 方法创建流。 如果 pActivationParams 为非 NULL,DirectSound 会将来自 DIRECTX_AUDIO_ACTIVATION_PARAMS 结构的音频会话 GUID 和流初始化标志作为输入参数提供给 Initialize 调用。 如果 pActivationParamsNULL,DirectSound 会将 Initialize 方法的 AudioSessionGuidStreamFlags 参数设置为各自的默认值 NULL 和 0。 这些值指示方法将流分配给由会话 GUID 值GUID_NULL标识的特定于进程的会话。

Activate 只能在呈现终结点设备上激活 IDirectSoundIDirectSound8 接口。 它只能在捕获终结点设备上激活 IDirectSoundCapture 或 IDirectSoundCapture8 接口。 激活调用以激活捕获设备上的 IDirectSoundIDirectSoundCapture8 接口或呈现设备上的 IDirectSoundCaptureIDirectSoundCapture8 接口失败,并返回错误代码E_NOINTERFACE。

在 Windows 7 中,客户端可以调用 IMMDevice::Activate 并指定 (IID_IMFTrustedOutput)以 (OTA) 对象创建输出信任机构,并检索指向对象的 IMFTrustedOutput 接口的指针。 OTA 可以在媒体基础的受保护媒体路径内部或外部运行, (PMP) 并在媒体基础管道外发送内容。 如果调用方在 PMP 外部,则 OTA 可能无法在 PMP 中运行,并且保护设置不太可靠。 有关将受保护的对象用于音频和示例代码的信息,请参阅 受保护的用户模式音频 (PUMA)

有关受保护对象和 IMFTrustedOutput 的一般信息,请参阅媒体基础文档中的“受保护的媒体路径”。

注意 在 Xbox One 开发工具包上使用 ISpatialAudioClient 接口 (XDK) 游戏时,必须先调用 EnableSpatialAudio ,然后再调用 IMMDeviceEnumerator::EnumAudioEndpointsIMMDeviceEnumerator::GetDefaultAudioEndpoint。 如果不这样做,将导致调用激活时返回E_NOINTERFACE错误。 EnableSpatialAudio 仅适用于 XDK 游戏,无需为 Xbox One 上运行的通用 Windows 平台应用或任何非 Xbox One 设备调用。
 
有关调用 Activate 方法的代码示例,请参阅以下主题:

要求

要求
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 mmdeviceapi.h

另请参阅

IAudioClient 接口

IAudioEndpointVolume 接口

IAudioMeterInformation 接口

IAudioSessionManager 接口

IDeviceTopology 接口

IMMDevice 接口