Метод IMMDevice::Activate (mmdeviceapi.h)

Статья
03/15/2023

Метод 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 . Кроме того, клиент может избежать введения ограничений контекста, указав 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	Пользователь удалил устройство конечной точки аудио или адаптер, к которому подключается устройство конечной точки.

Этот метод создает COM-объект с интерфейсом, заданным параметром iid . Метод аналогичен функции Windows CoCreateInstance , за исключением того, что вызывающий объект не предоставляет ИДЕНТИФИКАТОР CLSID в качестве параметра. Дополнительные сведения о CoCreateInstance см. в документации по Windows SDK.

Клиент может вызвать метод Activate интерфейса IMMDevice для определенного устройства конечной точки звука, чтобы получить подсчитываемую ссылку на интерфейс на этом устройстве. Метод может активировать следующие интерфейсы:

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 вызывающий объект может в качестве параметра указать значение, отличное от NULL , для pActivationParams. В этом случае pActivationParams указывает на структуру PROPVARIANT , содержащую сведения об инициализации потока. Задайте для элемента vt структуры значение VT_BLOB. Задайте член blob.pBlobData , чтобы он указывал на DIRECTX_AUDIO_ACTIVATION_PARAMS структуру, содержащую GUID звукового сеанса и флаги инициализации потока. Задайте для члена blob.cbSize значение sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Пример кода см. в разделе Роли устройств для приложений DirectShow. Дополнительные сведения о PROPVARIANT см. в документации по Windows SDK.

Экземпляр интерфейса IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture или IDirectSoundCapture8 , созданный методом Activate , инкапсулирует поток на устройстве конечной точки звука. Во время вызова Activate системный модуль DirectSound создает поток, вызывая метод IAudioClient::Initialize . Если значение pActivationParams не равно NULL, DirectSound предоставляет guid аудиосеанса и флаги инициализации потока из структуры DIRECTX_AUDIO_ACTIVATION_PARAMS в качестве входных параметров для вызова Initialize . Если pActivationParams имеет значение NULL, DirectSound задает для параметров AudioSessionGuid и StreamFlags метода Initialize соответствующие значения по умолчанию NULL и 0. Эти значения указывают методу назначить поток конкретному процессу сеансу, который определяется значением GUID сеанса GUID_NULL.

Активировать можно активировать интерфейс IDirectSound или IDirectSound8 только на устройстве конечной точки отрисовки. Он может активировать интерфейс IDirectSoundCapture или IDirectSoundCapture8 только на устройстве конечной точки захвата. Вызов Activate для активации интерфейса IDirectSound или IDirectSoundCapture8 на устройстве захвата или интерфейса IDirectSoundCapture или IDirectSoundCapture8 на устройстве отрисовки завершается сбоем и возвращает код ошибки E_NOINTERFACE.

В Windows 7 клиент может вызвать IMMDevice::Activate и указать , IID_IMFTrustedOutput, чтобы создать объект центра доверия вывода (OTA) и получить указатель на интерфейс IMFTrustedOutput объекта. OTA могут работать внутри или за пределами защищенного пути мультимедиа Media Foundation (PMP) и отправлять содержимое за пределы конвейера Media Foundation. Если вызывающий объект находится за пределами PMP, то OTA может не работать в PMP, и параметры защиты менее надежны. Сведения об использовании защищенных объектов для звука и пример кода см. в разделе Защищенный звук в пользовательском режиме (PUMA).

Общие сведения о защищенных объектах и IMFTrustedOutput см. в разделе "Защищенный путь к мультимедиа" в документации Media Foundation.

Примечание При использовании интерфейсов ISpatialAudioClient в заголовке пакета средств разработки Xbox One (XDK) необходимо сначала вызвать EnableSpatialAudio перед вызовом IMMDeviceEnumerator::EnumAudioEndpoints или IMMDeviceEnumerator::GetDefaultAudioEndpoint. Невыполнение этого действия приведет к E_NOINTERFACE ошибке, возвращаемой из вызова activate. EnableSpatialAudio доступен только для названий XDK и не требуется вызывать для универсальная платформа Windows приложений, работающих на Xbox One, а также для устройств, не относящихся к Xbox One.

Примеры кода, вызывающие метод Activate , см. в следующих разделах:

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	mmdeviceapi.h