Método IAudioClient::GetService (audioclient.h)

Artigo
02/28/2024

O método GetService acessa serviços adicionais do objeto cliente de áudio.

Sintaxe

HRESULT GetService(
  [in]  REFIID riid,
  [out] void   **ppv
);

Parâmetros

[in] riid

A ID da interface do serviço solicitado. O cliente deve definir esse parâmetro como um dos seguintes valores REFIID:

IID_IAudioCaptureClient

IID_IAudioClientDuckingControl

IID_IAudioClock

IID_IAudioRenderClient

IID_IAudioSessionControl

IID_IAudioStreamVolume

IID_IChannelAudioVolume

IID_IMFTrustedOutput

IID_ISimpleAudioVolume

Para obter mais informações, consulte Comentários.

[out] ppv

Ponteiro para uma variável de ponteiro na qual o método grava o endereço de uma instância da interface solicitada. Por meio desse método, o chamador obtém uma referência contada à interface . O chamador é responsável por liberar a interface, quando ela não é mais necessária, chamando o método Release da interface. Se a chamada GetService falhar, *ppv será NULL.

Retornar valor

Se o método for bem-sucedido, retornará S_OK. Se falhar, os códigos de retorno possíveis incluem, mas não se limitam a, os valores mostrados na tabela a seguir.

Código de retorno	Descrição
E_POINTER	O parâmetro ppv é NULL.
E_NOINTERFACE	A interface solicitada não está disponível.
AUDCLNT_E_NOT_INITIALIZED	O fluxo de áudio não foi inicializado.
AUDCLNT_E_WRONG_ENDPOINT_TYPE	O chamador tentou acessar uma interface IAudioCaptureClient em um ponto de extremidade de renderização ou uma interface IAudioRenderClient em um ponto de extremidade de captura.
AUDCLNT_E_DEVICE_INVALIDATED	O dispositivo de ponto de extremidade de áudio foi desconectado ou o hardware de áudio ou os recursos de hardware associados foram reconfigurados, desabilitados, removidos ou não estão disponíveis para uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	O serviço de áudio do Windows não está em execução.

Comentários

Esse método requer a inicialização prévia da interface IAudioClient . Todas as chamadas para esse método falharão com o erro AUDCLNT_E_NOT_INITIALIZED até que o cliente inicialize o fluxo de áudio chamando com êxito o método IAudioClient::Initialize .

O método GetService dá suporte às seguintes interfaces de serviço:

No Windows 7, um novo identificador de serviço, IID_IMFTrustedOutput, foi adicionado que facilita o uso de objetos OTA (autoridade de confiança de saída). Esses objetos podem operar dentro ou fora do PMP (caminho de mídia protegido) da Media Foundation e enviar conteúdo fora do pipeline do Media Foundation. Se o chamador estiver fora do PMP, o OTA poderá não operar no PMP e as configurações de proteção serão menos robustas. Os OTAs devem implementar a interface IMFTrustedOutput . Ao passar IID_IMFTrustedOutput em GetService, um aplicativo pode recuperar um ponteiro para a interface IMFTrustedOutput do objeto. Para obter mais informações sobre objetos protegidos e IMFTrustedOutput, consulte "Caminho da mídia protegida" na documentação do SDK do Media Foundation.

Para obter informações sobre como usar drivers de áudio confiáveis em OTAs, consulte PUMA (Áudio do Modo de Usuário Protegido).

Observe que ativar IMFTrustedOutput por meio desse mecanismo funciona independentemente de o chamador estiver em execução no PMP. No entanto, se o chamador não estiver em execução em um processo protegido (ou seja, o chamador não estiver dentro do PMP do Media Foundation), o OTA de áudio poderá não operar no PMP e as configurações de proteção serão menos robustas.

Para obter a ID da interface de uma interface de serviço, use o operador __uuidof . Por exemplo, a ID da interface de IAudioCaptureClient é definida da seguinte maneira:


const IID IID_IAudioCaptureClient  __uuidof(IAudioCaptureClient)

Para obter informações sobre o operador __uuidof, consulte a documentação do SDK do Windows.

Para liberar o objeto IAudioClient e liberar todos os recursos associados, o cliente deve liberar todas as referências a todos os objetos de serviço criados chamando GetService, além de chamar Release na própria interface IAudioClient . O cliente deve liberar um serviço do mesmo thread que libera o objeto IAudioClient .

As interfaces IAudioSessionControl, IAudioStreamVolume, IChannelAudioVolume e ISimpleAudioVolume controlam e monitoram aspectos de sessões de áudio e fluxos de modo compartilhado. Essas interfaces não funcionam com fluxos de modo exclusivo.

Para obter exemplos de código que chamam o método GetService , consulte os seguintes tópicos:

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	audioclient.h