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 |
|---|---|
|
Bem-sucedido e o dispositivo de ponto de extremidade de áudio dá suporte ao formato de fluxo especificado. |
|
Êxito com uma correspondência mais próxima ao formato especificado. |
|
Ê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 |
|---|---|
|
O parâmetro pFormat é NULL ou ppClosestMatch é NULL e ShareMode é AUDCLNT_SHAREMODE_SHARED. |
|
O Parâmetro ShareMode é um valor diferente de AUDCLNT_SHAREMODE_SHARED ou AUDCLNT_SHAREMODE_EXCLUSIVE. |
|
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. |
|
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 |