Compartilhar via


Função acmFormatEnum (msacm.h)

A função acmFormatEnum enumera formatos waveform-audio disponíveis para uma determinada marca de formato de um driver 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 acmFormatEnum(
  HACMDRIVER         had,
  LPACMFORMATDETAILS pafd,
  ACMFORMATENUMCB    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 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 apenas 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 somente 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

Retorna zero se tiver êxito ou um erro de outra forma. 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 drivers ACM adequados 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;
}

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

Confira também

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

Gerenciador de Compactação de Áudio