Функция 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, используемый для этого аргумента.

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

[in] riid

IID com-интерфейса в семействе WASAPI , например IAudioClient.

[in] activationParams

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

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

[in] completionHandler

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

activationOperation

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

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

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

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

Замечания

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

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

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

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

Важный  

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

 

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

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

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

Требования

Требование	Ценность
Минимальный поддерживаемый клиент	Windows 8 [классические приложения | Приложения UWP]
Минимальный поддерживаемый сервер	Windows Server 2012 [классические приложения | Приложения UWP]
Целевая платформа	Виндоус
Заголовок	mmdeviceapi.h (include Mmdevapi.idl)
библиотеки	Mmdevapi.lib
Библиотека dll	Mmdevapi.dll
IRQL	Нет

См. также

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

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler