Compartilhar via


Função ActivateAudioInterfaceAsync (mmdeviceapi.h)

Permite que os aplicativos da Windows Store acessem interfaces COM (Component Object Model) pré-existentes na família WASAPI .

Sintaxe

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

Parâmetros

[in] deviceInterfacePath

Uma ID de interface do dispositivo para um dispositivo de áudio. Normalmente, isso é recuperado de um objeto DeviceInformation ou de um dos métodos da classe MediaDevice .

Os GUIDs DEVINTERFACE_AUDIO_CAPTURE e DEVINTERFACE_AUDIO_RENDER representam o dispositivo padrão de captura e renderização de áudio, respectivamente. Chame StringFromIID para converter um desses GUIDs em um LPCWSTR a ser usado para esse argumento.

Especifique AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK para ativar a interface de áudio para captura de loopback de processo. Para obter um código de exemplo que demonstra o cenário de captura de loopback de processo, consulte o Exemplo de Captura de API de Loopback de Aplicativo.

[in] riid

O IID de uma interface COM na família WASAPI , como IAudioClient.

[in] activationParams

Parâmetros de ativação específicos da interface. Para obter mais informações, consulte o parâmetro pActivationParams em IMMDevice::Activate.

A partir do TBD, você pode especificar AUDIOCLIENT_ACTIVATION_PARAMS para ativar a interface para incluir ou excluir fluxos de áudio associados a uma ID de processo especificada.

[in] completionHandler

Uma interface implementada pelo chamador que é chamada pelo Windows quando o resultado do procedimento de ativação está disponível.

activationOperation

Retorna uma interface IActivateAudioInterfaceAsyncOperation que representa a operação assíncrona de ativar a interface WASAPI solicitada.

Valor retornado

A função retorna um HRESULT. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir.

Código de retorno Descrição
S_OK
O objeto subjacente e a operação assíncrona foram criados com êxito.
E_ILLEGAL_METHOD_CALL
Em versões do Windows anteriores ao Windows 10, esse erro poderá resultar se a função for chamada de um apartment COM incorreto ou se o IActivateAudioInterfaceCompletionHandler aprovado não for implementado em um objeto agile (agregando um marshaler de thread livre).

Comentários

Essa função permite que os aplicativos da Windows Store ativem determinadas interfaces COM WASAPI depois de usar APIs Windows Runtime nos namespaces Windows.Devices e Windows.Media.Devices para selecionar um dispositivo de áudio.

Para muitas implementações, um aplicativo deve chamar essa função do thread de interface do usuário main para ativar uma interface COM na família WASAPI para que o sistema possa mostrar uma caixa de diálogo para o usuário. O aplicativo passa uma interface COM de retorno de chamada IActivateAudioInterfaceCompletionHandler por meio de completionHandler. O Windows chama um método na interface IActivateAudioInterfaceCompletionHandler do aplicativo de um thread de trabalho no MTA (Apartamento Multi-threaded) COM quando os resultados da ativação estão disponíveis. Em seguida, o aplicativo pode chamar um método na interface IActivateAudioInterfaceAsyncOperation para recuperar o código de resultado e a interface WASAPI solicitada. Há algumas ativações que são explicitamente seguras e, portanto, não exigem que essa função seja chamada do thread de interface do usuário main. Essas ativações explicitamente seguras incluem:

  • Chamar ActivateAudioInterfaceAsync com um deviceInterfacePath que especifica um dispositivo de renderização de áudio e um riid que especifica a interface IAudioClient .
  • Chamar ActivateAudioInterfaceAsync com um deviceInterfacePath que especifica um dispositivo de renderização de áudio e um riid que especifica a interface IAudioEndpointVolume .
  • Chamando ActivateAudioInterfaceAsync de um serviço de sessão 0. Para obter mais informações, consulte Serviços.
O Windows mantém uma referência à interface IActivateAudioInterfaceCompletionHandler do aplicativo até que a operação seja concluída e o aplicativo libere a interface IActivateAudioInterfaceAsyncOperation .
Importante  

Os aplicativos não devem liberar o objeto que implementa o IActivateAudioInterfaceCompletionHandler até que o retorno de chamada do manipulador de conclusão seja executado.

 
Dependendo de qual interface WASAPI está ativada, essa função pode exibir um prompt de consentimento na primeira vez que for chamada. Por exemplo, quando o aplicativo chama essa função para ativar IAudioClient para acessar um microfone, a finalidade do prompt de consentimento é obter a permissão do usuário para que o aplicativo acesse o microfone. Para obter mais informações sobre o prompt de consentimento, consulte Diretrizes para dispositivos que acessam dados pessoais.

ActivateAudioInterfaceAsync deve ser chamado no thread de interface do usuário main para que o prompt de consentimento possa ser mostrado. Se o prompt de consentimento não puder ser mostrado, o usuário não poderá conceder acesso ao dispositivo ao aplicativo.

Em versões do Windows anteriores ao Windows 10, ActivateAudioInterfaceAsync deve ser chamado em um thread em um STA (COM Single-Threaded Apartment), ao abrir um dispositivo para captura de áudio. O completionHandler que é passado para ActivateAudioInterfaceAsync precisa implementar IAgileObject para garantir que não haja deadlock quando o completionHandler for chamado do MTA. Caso contrário, ocorrerá um E_ILLEGAL_METHOD_CALL .

Requisitos

   
Cliente mínimo com suporte Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho mmdeviceapi.h (inclua Mmdevapi.idl)
Biblioteca Mmdevapi.lib
DLL Mmdevapi.dll
IRQL Não

Confira também

Principais funções de áudio

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler