Función ActivateAudioInterfaceAsync (mmdeviceapi.h)

  • Artículo

Permite que las aplicaciones de la Tienda Windows accedan a interfaces preexistentes del Modelo de objetos componentes (COM) en la familia WASAPI .

Sintaxis

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

Parámetros

[in] deviceInterfacePath

Un identificador de interfaz de dispositivo para un dispositivo de audio. Normalmente se recupera de un objeto DeviceInformation o uno de los métodos de la clase MediaDevice .

Los GUID DEVINTERFACE_AUDIO_CAPTURE y DEVINTERFACE_AUDIO_RENDER representan la captura de audio y el dispositivo de representación predeterminados, respectivamente. Llame a StringFromIID para convertir cualquiera de estos GUID en un LPCWSTR que se usará para este argumento.

Especifique AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK para activar la interfaz de audio para la captura de bucle invertido de proceso. Para obtener código de ejemplo que muestra el escenario de captura de bucle invertido de proceso, consulte ejemplo de captura de Application Loopback API.

[in] riid

IID de una interfaz COM en la familia WASAPI , como IAudioClient.

[in] activationParams

Parámetros de activación específicos de la interfaz. Para obtener más información, vea el parámetro pActivationParams en IMMDevice::Activate.

A partir de TBD, puede especificar AUDIOCLIENT_ACTIVATION_PARAMS para activar la interfaz para incluir o excluir secuencias de audio asociadas a un identificador de proceso especificado.

[in] completionHandler

Interfaz implementada por el autor de la llamada a la que llama Windows cuando el resultado del procedimiento de activación está disponible.

activationOperation

Devuelve una interfaz IActivateAudioInterfaceAsyncOperation que representa la operación asincrónica de activar la interfaz WASAPI solicitada.

Valor devuelto

La función devuelve un HRESULT. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros.

Código devuelto Descripción
S_OK
 El objeto subyacente y la operación asincrónica se crearon correctamente.
E_ILLEGAL_METHOD_CALL
En las versiones de Windows anteriores a Windows 10, este error puede dar lugar a este error si se llama a la función desde un apartamento COM incorrecto, o si el IActivateAudioInterfaceCompletionHandler pasado no se implementa en un objeto ágil (agregando un serializador sin subprocesos).

Comentarios

Esta función permite que las aplicaciones de la Tienda Windows activen determinadas interfaces COM wasAPI después de usar Windows Runtime API en los espacios de nombres Windows.Devices y Windows.Media.Devices para seleccionar un dispositivo de audio.

Para muchas implementaciones, una aplicación debe llamar a esta función desde el subproceso principal de la interfaz de usuario para activar una interfaz COM en la familia WASAPI para que el sistema pueda mostrar un cuadro de diálogo al usuario. La aplicación pasa una interfaz COM de devolución de llamada COM de IActivateAudioInterfaceCompletionHandler a través de completionHandler. Windows llama a un método en la interfaz IActivateAudioInterfaceCompletionHandler de la aplicación desde un subproceso de trabajo en el Apartamento multiproceso COM (MTA) cuando los resultados de activación están disponibles. A continuación, la aplicación puede llamar a un método en la interfaz IActivateAudioInterfaceAsyncOperation para recuperar el código de resultado y la interfaz WASAPI solicitada. Hay algunas activaciones que son explícitamente seguras y, por lo tanto, no requieren que se llame a esta función desde el subproceso principal de la interfaz de usuario. Estas activaciones seguras explícitamente incluyen:

  • Llamar a ActivateAudioInterfaceAsync con un deviceInterfacePath que especifica un dispositivo de representación de audio y un riid que especifica la interfaz IAudioClient .
  • Llamar a ActivateAudioInterfaceAsync con un deviceInterfacePath que especifica un dispositivo de representación de audio y un riid que especifica la interfaz IAudioEndpointVolume .
  • Llamar a ActivateAudioInterfaceAsync desde un servicio de sesión 0. Para obtener más información, consulte Servicios.
Windows contiene una referencia a la interfaz IActivateAudioInterfaceCompletionHandler de la aplicación hasta que se complete la operación y la aplicación libera la interfaz IActivateAudioInterfaceAsyncOperation .
Importante  

Las aplicaciones no deben liberar el objeto que implementa IActivateAudioInterfaceCompletionHandler hasta que se haya ejecutado la devolución de llamada del controlador de finalización.

 
Dependiendo de la interfaz WASAPI que se active, esta función puede mostrar un aviso de consentimiento la primera vez que se llama. Por ejemplo, cuando la aplicación llama a esta función para activar IAudioClient para acceder a un micrófono, el propósito del mensaje de consentimiento es obtener el permiso del usuario para que la aplicación acceda al micrófono. Para obtener más información sobre la solicitud de consentimiento, consulte Directrices para dispositivos que acceden a datos personales.

Se debe llamar a ActivateAudioInterfaceAsync en el subproceso principal de la interfaz de usuario para que se pueda mostrar el mensaje de consentimiento. Si no se puede mostrar el mensaje de consentimiento, el usuario no puede conceder acceso al dispositivo a la aplicación.

En las versiones de Windows anteriores a Windows 10, se debe llamar a ActivateAudioInterfaceAsync en un subproceso en un com Single-Threaded Apartment (STA), al abrir un dispositivo para la captura de audio. El completionHandler que se pasa a ActivateAudioInterfaceAsync debe implementar IAgileObject para asegurarse de que no hay ningún interbloqueo cuando se llama a completionHandler desde el MTA. De lo contrario, se producirá un E_ILLEGAL_METHOD_CALL .

Requisitos

   
Cliente mínimo compatible Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado mmdeviceapi.h (include Mmdevapi.idl)
Library Mmdevapi.lib
Archivo DLL Mmdevapi.dll
IRQL No

Consulte también

Funciones principales de audio

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler