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

O método IsFormatSupported indica se o dispositivo de ponto de extremidade de áudio dá suporte a um formato de fluxo específico.

Sintaxe

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

Parâmetros

[in] ShareMode

O modo de compartilhamento para o formato de fluxo. Por meio desse parâmetro, o cliente indica se deseja usar o formato especificado no modo exclusivo ou no modo compartilhado. O cliente deve definir esse parâmetro como um dos seguintes valores de enumeração AUDCLNT_SHAREMODE :

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

Ponteiro para o formato de fluxo especificado. Esse parâmetro aponta para um descritor de formato alocado pelo chamador do tipo WAVEFORMATEX ou WAVEFORMATEXTENSIBLE. O cliente grava uma descrição de formato nessa estrutura antes de chamar esse método. Para obter informações sobre WAVEFORMATEX e WAVEFORMATEXTENSIBLE, consulte a documentação do DDK do Windows.

[out] ppClosestMatch

Ponteiro para uma variável de ponteiro na qual o método grava o endereço de uma estrutura WAVEFORMATEX ou WAVEFORMATEXTENSIBLE . Essa estrutura especifica o formato com suporte mais próximo do formato especificado pelo cliente por meio do parâmetro pFormat . Para o modo compartilhado (ou seja, se o parâmetro ShareMode for AUDCLNT_SHAREMODE_SHARED), defina ppClosestMatch para apontar para uma variável de ponteiro válida e não NULL . Para o modo exclusivo, defina ppClosestMatch comoNULL. O método aloca o armazenamento para a estrutura. O chamador é responsável por liberar o armazenamento, quando ele não é mais necessário, chamando a função CoTaskMemFree . Se a chamada IsFormatSupported falhar e ppClosestMatch não for NULL, o método definirá *ppClosestMatch comoNULL. Para obter informações sobre CoTaskMemFree, consulte a documentação do SDK do Windows.

Retornar valor

Código de retorno	Descrição
S_OK	Bem-sucedido e o dispositivo de ponto de extremidade de áudio dá suporte ao formato de fluxo especificado.
S_FALSE	Êxito com uma correspondência mais próxima ao formato especificado.
AUDCLNT_E_UNSUPPORTED_FORMAT	Êxito, mas não há suporte para o formato especificado no modo exclusivo.

 

Se a operação 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 pFormat é NULL ou ppClosestMatch é NULL e ShareMode é AUDCLNT_SHAREMODE_SHARED.
E_INVALIDARG	O Parâmetro ShareMode é um valor diferente de AUDCLNT_SHAREMODE_SHARED ou AUDCLNT_SHAREMODE_EXCLUSIVE.
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 fornece uma maneira de um cliente determinar, antes de chamar IAudioClient::Initialize, se o mecanismo de áudio dá suporte a um formato de fluxo específico.

Para o modo exclusivo, IsFormatSupported retornará S_OK se o dispositivo de ponto de extremidade de áudio der suporte ao formato especificado pelo chamador ou retornará AUDCLNT_E_UNSUPPORTED_FORMAT se o dispositivo não oferecer suporte ao formato. O parâmetro ppClosestMatch pode ser NULL. Se não for NULL, o método gravará NULL em *ppClosestMatch.

Para o modo compartilhado, se o mecanismo de áudio der suporte ao formato especificado pelo chamador, IsFormatSupported definirá *ppClosestMatch como NULL e retornará S_OK. Se o mecanismo de áudio não der suporte ao formato especificado pelo chamador, mas oferecer suporte a um formato semelhante, o método recuperará o formato semelhante por meio do parâmetro ppClosestMatch e retornará S_FALSE. Se o mecanismo de áudio não der suporte ao formato especificado pelo chamador ou a qualquer formato semelhante, o método definirá *ppClosestMatch comoNULL e retornará AUDCLNT_E_UNSUPPORTED_FORMAT.

No modo compartilhado, o mecanismo de áudio sempre dá suporte ao formato de combinação, que o cliente pode obter chamando o método IAudioClient::GetMixFormat . Além disso, o mecanismo de áudio pode dar suporte a formatos semelhantes que têm a mesma taxa de exemplo e número de canais que o formato de combinação, mas diferem na representação de valores de exemplo de áudio. O mecanismo de áudio representa valores de exemplo internamente como números de ponto flutuante, mas se o formato especificado pelo chamador representar valores de exemplo como inteiros, o mecanismo de áudio normalmente poderá converter entre os valores de exemplo inteiros e sua representação de ponto flutuante interno.

O mecanismo de áudio poderá dar suporte a uma gama ainda maior de formatos de modo compartilhado se o pacote de instalação do dispositivo de áudio incluir um APO (objeto de processamento de áudio) de efeitos locais (LFX) que possa lidar com conversões de formato. Um APO LFX é um módulo de software que executa o processamento específico do dispositivo de um fluxo de áudio. O construtor de grafo de áudio no serviço de áudio do Windows insere o APO LFX no fluxo entre cada cliente e o mecanismo de áudio. Quando um cliente chama o método IsFormatSupported e o método determina que um APO LFX está instalado para uso com o dispositivo, o método direciona a consulta para o APO LFX, o que indica se ele dá suporte ao formato especificado pelo chamador.

Por exemplo, um APO LFX específico pode aceitar um fluxo de som surround de 6 canais de um cliente e converter o fluxo em um formato estéreo que pode ser reproduzido por meio de fones de ouvido. Normalmente, um APO LFX dá suporte apenas a formatos de cliente com taxas de exemplo que correspondem à taxa de exemplo do formato de combinação.

Para obter mais informações sobre APOs, consulte Objetos de Processamento de Áudio do Windows. Para obter mais informações sobre o método IsFormatSupported , consulte Formatos de dispositivo.

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

Confira também

IAudioClient Interface

IAudioClient::GetMixFormat

IAudioClient::Initialize