Compartilhar via

Função ActivateAudioInterfaceAsync (mmdeviceapi.h)

  • Artigo

Permite que os aplicativos da Windows Store acessem interfaces COM (modelo de objeto de componente) 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 da interface do dispositivo para um dispositivo de áudio. Normalmente, isso é recuperado de um objeto DeviceInformation ou um dos métodos da classe MediaDevice.

Os GUIDs DEVINTERFACE_AUDIO_CAPTURE e DEVINTERFACE_AUDIO_RENDER representam o dispositivo de renderização e captura de áudio padrão, respectivamente. Chame StringFromIID para converter qualquer 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 a captura de loopback do 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

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

[in] activationParams

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

A partir do Windows 10 Build 20438, 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 de WASAPI solicitada.

Valor de retorno

A função retorna umHRESULT . Os valores possíveis incluem, mas não se limitam a, 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 apartamento COM incorreto ou se o IActivateAudioInterfaceCompletionHandler não for implementado em um objeto agile (agregando um marshaler de thread livre).

Observações

Essa função permite que os aplicativos da Windows Store ativem determinadas interfaces COM WASAPI depois de usar APIs do Windows Runtime no windows.devices e windows.media.devices namespaces para selecionar um dispositivo de áudio.

Para muitas implementações, um aplicativo deve chamar essa função do thread principal da interface do usuário para ativar uma interface COM no família de WASAPI para que o sistema possa mostrar uma caixa de diálogo para o usuário. O aplicativo passa uma interface COM IActivateAudioInterfaceCompletionHandler por meio de completionHandler. O Windows chama um método na interface de IActivateAudioInterfaceCompletionHandler do aplicativo de um thread de trabalho no MTA (Apartamento Multi-threaded) COM quando os resultados da ativação estiverem disponíveis. Em seguida, o aplicativo pode chamar um método na interface IActivateAudioInterfaceAsyncOperation para recuperar o código de resultado e a interface de WASAPI solicitada. Há algumas ativações explicitamente seguras e, portanto, não exigem que essa função seja chamada do thread principal da interface do usuário. 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 .
  • Chamar ActivateAudioInterfaceAsync de um serviço de sessão 0. Para obter mais informações, consulte Services.
O Windows mantém uma referência à interface de 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 de WASAPI é ativada, essa função pode exibir um prompt de consentimento na primeira vez em 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 principal da interface do usuário 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

Requisito Valor
de cliente com suporte mínimo Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
da Plataforma de Destino Windows
cabeçalho mmdeviceapi.h (include Mmdevapi.idl)
biblioteca Mmdevapi.lib
de DLL Mmdevapi.dll
IRQL Não

Consulte também

principais funções de áudio

IActivateAudioInterfaceAsyncOperation

IActivateAudioInterfaceCompletionHandler