Поделиться через

Функция 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 Loopback API Capture.

[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 активировать определенные WASAPI COM-интерфейсы после использования API среды выполнения Windows в Windows.Devices и пространства имен Windows.Media.Devices для выбора звукового устройства.

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

  • Вызов ActivateAudioInterfaceAsync с deviceInterfacePath, который задает устройство отрисовки звука и riid, указывающий интерфейс IAudioClient.
  • Вызов ActivateAudioInterfaceAsync с deviceInterfacePath, который задает устройство отрисовки звука и riid, который задает интерфейс IAudioEndpointVolume.
  • Вызов ActivateAudioInterfaceAsync из службы сеанса 0. Дополнительные сведения см. в службах.
Windows содержит ссылку на интерфейс приложения IActivateAudioInterfaceCompletionHandler, пока операция не завершится, и приложение освобождает интерфейс 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