Função acmFormatEnumW (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 acmFormatEnumW(
  HACMDRIVER          had,
  LPACMFORMATDETAILSW pafd,
  ACMFORMATENUMCBW    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.

Retornar valor

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
ACMERR_NOTPOSSIBLE	Os detalhes do formato não podem ser retornados.
MMSYSERR_INVALFLAG	Pelo menos um sinalizador é inválido.
MMSYSERR_INVALHANDLE	O identificador especificado é inválido.
MMSYSERR_INVALPARAM	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

Requisito	Valor
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

Confira também

Funções de compactação de áudio

Gerenciador de Compactação de Áudio