Функция ActivateAudioInterfaceAsync (mmdeviceapi.h)

Позволяет приложениям Магазина Windows получать доступ к уже существовающим com-интерфейсам в семействе WASAPI .

Синтаксис

HRESULT ActivateAudioInterfaceAsync(
  [in] LPCWSTR                                  deviceInterfacePath,
  [in] REFIID                                   riid,
  [in] PROPVARIANT                              *activationParams,
  [in] IActivateAudioInterfaceCompletionHandler *completionHandler,
       IActivateAudioInterfaceAsyncOperation    **activationOperation
);

Параметры

[in] deviceInterfacePath

Идентификатор интерфейса устройства для звукового устройства. Обычно он извлекается из объекта DeviceInformation или одного из методов класса MediaDevice .

Идентификаторы GUID DEVINTERFACE_AUDIO_CAPTURE и DEVINTERFACE_AUDIO_RENDER представляют устройство захвата и отрисовки звука по умолчанию соответственно. Вызовите StringFromIID для преобразования любого из этих идентификаторов GUID в LPCWSTR для использования для этого аргумента.

Укажите AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK для активации звукового интерфейса для захвата замыкания на себя процесса. Пример кода, демонстрирующий сценарий отслеживания замыкания на себя процесса, см. в разделе Пример отслеживания API замыкания на себя.

[in] riid

Идентификатор IID COM-интерфейса в семействе WASAPI , например IAudioClient.

[in] activationParams

Параметры активации для конкретного интерфейса. Дополнительные сведения см. в разделе параметр pActivationParams в IMMDevice::Activate.

Начиная с TBD можно указать AUDIOCLIENT_ACTIVATION_PARAMS активации интерфейса для включения или исключения звуковых потоков, связанных с указанным идентификатором процесса.

[in] completionHandler

Интерфейс, реализованный вызывающим абонентом, который вызывается Windows, когда доступен результат процедуры активации.

activationOperation

Возвращает интерфейс IActivateAudioInterfaceAsyncOperation , представляющий асинхронную операцию активации запрошенного интерфейса WASAPI .

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

Функция возвращает HRESULT. Допустимые значения включают, но не ограничиваются, значения, приведенные в следующей таблице.

Код возврата	Описание
S_OK	Базовый объект и асинхронная операция успешно созданы.
E_ILLEGAL_METHOD_CALL	В версиях Windows, предшествующих Windows 10, эта ошибка может возникать, если функция вызывается из неправильного подразделения COM или если переданный объект IActivateAudioInterfaceCompletionHandler не реализован в объекте agile (агрегирование маршалера с произвольным потоком).

Комментарии

Эта функция позволяет приложениям Магазина Windows активировать определенные COM-интерфейсы WASAPI после использования api среда выполнения Windows в пространствах имен Windows.Devices и Windows.Media.Devices для выбора звукового устройства.

Во многих реализациях приложение должно вызывать эту функцию из потока пользовательского интерфейса main, чтобы активировать COM-интерфейс в семействе WASAPI, чтобы система смогла показать пользователю диалоговое окно. Приложение передает COM-интерфейс обратного вызова IActivateAudioInterfaceCompletionHandler через completionHandler. Windows вызывает метод в интерфейсе IActivateAudioInterfaceCompletionHandler приложения из рабочего потока в многопотоковом объекте COM (MTA), когда результаты активации доступны. Затем приложение может вызвать метод в интерфейсе IActivateAudioInterfaceAsyncOperation , чтобы получить код результата и запрошенный интерфейс WASAPI . Некоторые активации являются явно безопасными и поэтому не требуют вызова этой функции из потока пользовательского интерфейса main. К этим явно безопасным активациям относятся:

• Вызов Метода ActivateAudioInterfaceAsync с deviceInterfacePath , который указывает устройство отрисовки звука, и riid , указывающий интерфейс IAudioClient .
• Вызов Метода ActivateAudioInterfaceAsync с помощью deviceInterfacePath , указывающего устройство отрисовки звука, и идентификатор riid , указывающий интерфейс IAudioEndpointVolume .
• Вызов ActivateAudioInterfaceAsync из службы сеанса 0. Дополнительные сведения см. в разделе Службы.

Windows хранит ссылку на интерфейс IActivateAudioInterfaceCompletionHandler приложения, пока операция не будет завершена и приложение не освобождает интерфейс IActivateAudioInterfaceAsyncOperation .

Важно  

Приложения не должны освобождать объект, реализующий IActivateAudioInterfaceCompletionHandler , пока не будет выполнен обратный вызов обработчика завершения.

 

В зависимости от того, какой интерфейс WASAPI активирован, эта функция может отображать запрос согласия при первом вызове. Например, когда приложение вызывает эту функцию для активации IAudioClient для доступа к микрофону, цель запроса согласия — получить разрешение пользователя на доступ к микрофону. Дополнительные сведения о запросе согласия см. в разделе Рекомендации для устройств, которые обращаются к персональным данным.

Метод ActivateAudioInterfaceAsync должен вызываться в потоке пользовательского интерфейса main, чтобы можно было отображать запрос согласия. Если запрос согласия не отображается, пользователь не сможет предоставить устройству доступ к приложению.

В версиях Windows, предшествующих Windows 10, при открытии устройства для захвата звука необходимо вызывать ActivateAudioInterfaceAsync в потоке в com-Single-Threaded Apartment (STA). CompletionHandler, передаваемый в ActivateAudioInterfaceAsync, должен реализовать IAgileObject, чтобы гарантировать отсутствие взаимоблокировки при вызове completionHandler из MTA. В противном случае произойдет E_ILLEGAL_METHOD_CALL .

Требования

Минимальная версия клиента	Windows 8 [классические приложения | Приложения UWP]
Минимальная версия сервера	Windows Server 2012 [классические приложения | Приложения UWP]
Целевая платформа	Windows
Header	mmdeviceapi.h (включая Mmdevapi.idl)
Библиотека	Mmdevapi.lib
DLL	Mmdevapi.dll
IRQL	Нет

См. также раздел

Основные звуковые функции

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler