IMMDevice：：Activate 方法 (mmdeviceapi.h)

项目
02/29/2024

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。如果失败，可能的返回代码包括但不限于下表中显示的值。

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

注解

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

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

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

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


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 的一般信息，请参阅媒体基础文档中的“受保护的媒体路径”。

注意在 Xbox One 开发工具包上使用 ISpatialAudioClient 接口 (XDK) 游戏时，必须先调用 EnableSpatialAudio ，然后再调用 IMMDeviceEnumerator：：EnumAudioEndpoints 或 IMMDeviceEnumerator：：GetDefaultAudioEndpoint。如果不这样做，将导致调用激活时返回E_NOINTERFACE错误。 EnableSpatialAudio 仅适用于 XDK 游戏，无需为 Xbox One 上运行的通用 Windows 平台应用或任何非 Xbox One 设备调用。

有关调用 Activate 方法的代码示例，请参阅以下主题：

要求

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