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

Статья
11/20/2024

Метод 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. Кроме того, клиент может избежать каких-либо ограничений контекста, указав CLSCTX_ALL. Дополнительные сведения о CLSCTXсм. в документации по пакету SDK для Windows.

[in] pActivationParams

Установите значение NULL для активации IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManagerили интерфейса IDeviceTopology на звуковом устройстве конечной точки. Начиная с Сборки Windows 10 20348 вызывающие абоненты, активирующие IAudioClient, могут задать pActivationParams указатель на AUDIOCLIENT_ACTIVATION_PARAMS для настройки звукового клиента в режиме обратного цикла с фильтром процесса.

При активации IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCaptureили интерфейса IDirectSoundCapture8 на устройстве, Вызывающий объект может указать указатель на структуру PROPVARIANT, содержащую сведения о инициализации потока. Дополнительные сведения см. в разделе "Примечания".

[out] ppInterface

Указатель на переменную указателя, в которую метод записывает адрес интерфейса, указанный параметром iid. С помощью этого метода вызывающий объект получает подсчитываемую ссылку на интерфейс. Вызывающий объект отвечает за освобождение интерфейса, если он больше не нужен, вызывая метод release интерфейса. Если вызов активации завершается ошибкой, *ppInterface равно NULL.

Возвращаемое значение

Если метод выполнен успешно, он возвращает S_OK. В случае сбоя возможные коды возврата включаются, но не ограничиваются значениями, приведенными в следующей таблице.

Возвращаемый код	Описание
E_NOINTERFACE	Объект не поддерживает запрошенный тип интерфейса.
E_POINTER	Параметр ppInterfaceNULL.
E_INVALIDARG	Параметр pActivationParams должен быть значение NULL для указанного интерфейса; или pActivationParams указывает на недопустимые данные.
E_OUTOFMEMORY	Вне памяти.
AUDCLNT_E_DEVICE_INVALIDATED	Пользователь удалил устройство аудио конечной точки или устройство адаптера, к которому подключается устройство конечной точки.

Замечания

Этот метод создает COM-объект с интерфейсом, заданным параметром iid. Метод аналогичен функции CoCreateInst ance Windows CoCreateInstance, за исключением того, что вызывающий объект не предоставляет CLSID в качестве параметра. Дополнительные сведения о CoCreateInstanceсм. в документации по пакету SDK для Windows.

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

IAudioClient
IAudioEndpointVolume
IAudioMeterInformation
IAudioSessionManager
IAudioSessionManager2
IBaseFilter
IDeviceTopology
IDirectSound
IDirectSound8
IDirectSoundCapture
IDirectSoundCapture8
МВФTrustedOutput

Чтобы получить идентификатор интерфейса для интерфейса, используйте оператор __uuidof. Например, идентификатор интерфейса IAudioCaptureClient определяется следующим образом:


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Сведения о операторе __uuidof см. в документации по пакету SDK для Windows. Сведения о IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8и IMFTrustedOutput см. в документации по пакету SDK для Windows.

Параметр pActivationParams должен быть null для вызова активировать для создания IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManagerили IDeviceTopology для устройства звуковой конечной точки. Начиная с Сборки Windows 10 20348 вызывающие абоненты, активирующие IAudioClient, могут задать pActivationParams указатель на AUDIOCLIENT_ACTIVATION_PARAMS для настройки звукового клиента в режиме обратного цикла с фильтром процесса.

Для вызова активации для создания IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCaptureили интерфейса IDirectSoundCapture8, Вызывающий объект может указывать значение, отличное отNULL для pActivationParams. В этом случае pActivationParams указывает на структуру PROPVARIANT, содержащую сведения о потоковой инициализации. Задайте для элемента VT_BLOB . Задайте элементу blob.pBlobData указывать на структуру DIRECTX_AUDIO_ACTIVATION_PARAMS, содержащую GUID сеанса аудио и флаги инициализации потока. Задайте для элемента blob.cbSize значение sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Пример кода см. в разделе роли устройств для приложений DirectShow. Дополнительные сведения о PROPVARIANTсм. в документации по пакету SDK для Windows.

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

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

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

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

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	mmdeviceapi.h