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 |
|---|---|
|
O objeto subjacente e a operação assíncrona foram criados com êxito. |
|
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.
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.
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 |