Função acmFormatEnumA (msacm.h)
A função acmFormatEnum enumera formatos waveform-audio disponíveis para uma determinada marca de formato de um driver do ACM. Essa função continua enumerando até que não haja formatos mais adequados para a marca de formato ou a função de retorno de chamada retorne FALSE.
Sintaxe
MMRESULT ACMAPI acmFormatEnumA(
HACMDRIVER had,
LPACMFORMATDETAILSA pafd,
ACMFORMATENUMCBA fnCallback,
DWORD_PTR dwInstance,
DWORD fdwEnum
);
Parâmetros
had
Manipule para o driver do ACM para consultar detalhes do formato waveform-audio. Se esse parâmetro for NULL, o ACM usará os detalhes do primeiro driver ACM adequado.
pafd
Ponteiro para uma estrutura ACMFORMATDETAILS para conter os detalhes de formato passados para a função fnCallback . Essa estrutura deve ter os membros cbStruct, pwfx e cbwfx da estrutura ACMFORMATDETAILS inicializados . O membro dwFormatTag também deve ser inicializado para WAVE_FORMAT_UNKNOWN ou uma marca de formato válida.
O membro fdwSupport da estrutura deve ser inicializado como zero.
Para localizar o tamanho necessário do buffer pwfx , chame acmMetrics com o sinalizador ACM_METRIC_MAX_SIZE_FORMAT.
fnCallback
Endereço de uma função de retorno de chamada definida pelo aplicativo. Consulte acmFormatEnumCallback. Esse parâmetro não pode ser NULL.
dwInstance
Um valor definido pelo aplicativo de 64 bits (DWORD_PTR) ou DWORD (32 bits) que é passado para a função de retorno de chamada junto com os detalhes do formato do ACM.
fdwEnum
Sinalizadores para enumerar os formatos de uma determinada marca de formato. Os valores a seguir são definidos.
[ACMFORMATDETAILS] A estrutura (./nf-msacm-acmformatdetails.md) é válida. O enumerador só enumerará formatos de destino que podem ser convertidos do formato pwfx fornecido. Se esse sinalizador for usado, o membro wFormatTag da estrutura WAVEFORMATEX não poderá ser WAVE_FORMAT_UNKNOWN. [ACMFORMATDETAILS] A estrutura (./nf-msacm-acmformatdetails.md) é válida. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo. [ACMFORMATDETAILS] A estrutura (./nf-msacm-acmformatdetails.md) é válida. O enumerador enumerará todos os formatos de destino sugeridos para o formato pwfx fornecido. Esse mecanismo pode ser usado em vez da função acmFormatSuggest para permitir que um aplicativo escolha o melhor formato sugerido para conversão. O membro dwFormatIndex sempre será definido como zero no retorno. Se esse sinalizador for usado, o membro wFormatTag da estrutura WAVEFORMATEX não poderá ser WAVE_FORMAT_UNKNOWN.| Valor | Significado |
|---|---|
| ACM_FORMATENUMF_CONVERT | |
| ACM_FORMATENUMF_HARDWARE | O enumerador deve enumerar apenas formatos com suporte como formatos nativos de entrada ou saída em um ou mais dos dispositivos de áudio waveform instalados. Esse sinalizador fornece uma maneira de um aplicativo escolher apenas formatos nativos para um dispositivo de áudio waveform instalado. Esse sinalizador deve ser usado com um ou ambos os sinalizadores ACM_FORMATENUMF_INPUT e ACM_FORMATENUMF_OUTPUT. Especificar ACM_FORMATENUMF_INPUT e ACM_FORMATENUMF_OUTPUT enumerará apenas formatos que podem ser abertos para entrada ou saída. Isso é verdadeiro, independentemente de esse sinalizador ser especificado. |
| ACM_FORMATENUMF_INPUT | O enumerador deve enumerar somente formatos com suporte para entrada (gravação). |
| ACM_FORMATENUMF_NCHANNELS | |
| ACM_FORMATENUMF_NSAMPLESPERSEC | O membro nSamplesPerSec da estrutura WAVEFORMATEX apontado pelo membro pwfx da estrutura ACMFORMATDETAILS é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo. |
| ACM_FORMATENUMF_OUTPUT | O enumerador deve enumerar apenas formatos com suporte para saída (reprodução). |
| ACM_FORMATENUMF_SUGGEST | |
| ACM_FORMATENUMF_WBITSPERSAMPLE | O membro wBitsPerSample da estrutura WAVEFORMATEX apontado pelo membro pwfx da estrutura ACMFORMATDETAILS é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo. |
| ACM_FORMATENUMF_WFORMATTAG | O membro wFormatTag da estrutura WAVEFORMATEX apontado pelo membro pwfx da estrutura ACMFORMATDETAILS é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo. O membro dwFormatTag da estrutura ACMFORMATDETAILS deve ser igual ao membro wFormatTag . O valor de wFormatTag não pode ser WAVE_FORMAT_UNKNOWN nesse caso. |
Valor retornado
Retornará zero se tiver êxito ou um erro, caso contrário. Os valores de erro possíveis incluem o seguinte.
| Código de retorno | Descrição |
|---|---|
|
Os detalhes do formato não podem ser retornados. |
|
Pelo menos um sinalizador é inválido. |
|
O identificador especificado é inválido. |
|
Pelo menos um parâmetro é inválido. |
Comentários
Essa função retornará MMSYSERR_NOERROR (zero) se nenhum driver ACM adequado estiver instalado. Além disso, a função de retorno de chamada não será chamada.
Exemplos
O exemplo a seguir mostra como enumerar formatos que têm a marca de formato WAVE_FORMAT_MPEGLAYER3.
MMRESULT EnumerateMP3Codecs()
{
DWORD cbMaxSize = 0;
MMRESULT result = MMSYSERR_NOERROR;
ACMFORMATDETAILS acmFormatDetails;
// Buffer to hold the format information.
BYTE *pFormat = NULL; // Caller allocated.
// Find the largest format buffer needed.
result = acmMetrics(NULL, ACM_METRIC_MAX_SIZE_FORMAT, &cbMaxSize);
if (result != MMSYSERR_NOERROR)
{
return result;
}
// Allocate the format buffer.
pFormat = new BYTE[cbMaxSize];
if (pFormat == NULL)
{
return MMSYSERR_NOMEM;
}
ZeroMemory(pFormat, cbMaxSize);
// Ask for WAVE_FORMAT_MPEGLAYER3 formats.
WAVEFORMATEX* pWaveFormat = (WAVEFORMATEX*)pFormat;
pWaveFormat->wFormatTag = WAVE_FORMAT_MPEGLAYER3;
// Set up the acmFormatDetails structure.
ZeroMemory(&acmFormatDetails, sizeof(acmFormatDetails));
acmFormatDetails.cbStruct = sizeof(ACMFORMATDETAILS);
acmFormatDetails.pwfx = pWaveFormat;
acmFormatDetails.cbwfx = cbMaxSize;
// For the ACM_FORMATENUMF_WFORMATTAG request, the format
// tag in acmFormatDetails must match the format tag in
// the pFormat buffer.
acmFormatDetails.dwFormatTag = WAVE_FORMAT_MPEGLAYER3;
result = acmFormatEnum(NULL, &acmFormatDetails, acmFormatEnumCallback,
0, ACM_FORMATENUMF_WFORMATTAG);
delete [] pFormat;
return result;
}
O exemplo a seguir mostra a função de retorno de chamada para o exemplo anterior. A função de retorno de chamada é chamada uma vez para cada formato correspondente ou até que o retorno de chamada retorne FALSE.
BOOL CALLBACK acmFormatEnumCallback(
HACMDRIVERID hadid,
LPACMFORMATDETAILS pafd,
DWORD_PTR dwInstance,
DWORD fdwSupport
)
{
BOOL bContinue = TRUE;
MPEGLAYER3WAVEFORMAT *pMP3WaveFormat = NULL;
if (pafd->pwfx->wFormatTag == WAVE_FORMAT_MPEGLAYER3)
{
pMP3WaveFormat = (MPEGLAYER3WAVEFORMAT*)pafd->pwfx;
// TODO: Examine the format.
// To halt the enumeration, set bContinue to FALSE.
}
return bContinue;
}
Observação
O cabeçalho msacm.h define acmFormatEnum como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | msacm.h |
| Biblioteca | Msacm32.lib |
| DLL | Msacm32.dll |