Функция acmFormatEnum (msacm.h)

  • Статья

Функция acmFormatEnum перечисляет форматы waveform-audio, доступные для заданного тега формата из драйвера ACM. Эта функция продолжает перечисление, пока не будет больше подходящих форматов для тега format или функция обратного вызова не вернет значение FALSE.

Синтаксис

MMRESULT ACMAPI acmFormatEnum(
  HACMDRIVER         had,
  LPACMFORMATDETAILS pafd,
  ACMFORMATENUMCB    fnCallback,
  DWORD_PTR          dwInstance,
  DWORD              fdwEnum
);

Параметры

had

Выполните запрос к драйверу ACM для запроса сведений о формате waveform-audio. Если этот параметр имеет значение NULL, ACM использует сведения из первого подходящего драйвера ACM.

pafd

Указатель на структуру ACMFORMATDETAILS , которая содержит сведения о формате, передаваемые функции fnCallback . В этой структуре должны быть инициализированы элементы cbStruct, pwfx и cbwfx структуры ACMFORMATDETAILS . Член dwFormatTag также должен быть инициализирован WAVE_FORMAT_UNKNOWN или допустимым тегом формата.

Элемент fdwSupport структуры должен быть инициализирован до нуля.

Чтобы найти требуемый размер буфера pwfx , вызовите acmMetrics с флагом ACM_METRIC_MAX_SIZE_FORMAT.

fnCallback

Адрес функции обратного вызова, определяемой приложением. См . раздел acmFormatEnumCallback. Этот параметр не может иметь значение NULL.

dwInstance

64-разрядное (DWORD_PTR) или 32-разрядное (DWORD) значение, определяемое приложением, которое передается функции обратного вызова вместе со сведениями о формате ACM.

fdwEnum

Флаги для перечисления форматов для заданного тега формата. Определены следующие значения.

[ACMFORMATDETAILS] Допустимая структура (./nf-msacm-acmformatdetails.md). Перечислитель будет перечислять только целевые форматы, которые можно преобразовать из заданного формата pwfx . Если используется этот флаг, член wFormatTag структуры WAVEFORMATEX не может быть WAVE_FORMAT_UNKNOWN. [ACMFORMATDETAILS] Допустимая структура (./nf-msacm-acmformatdetails.md). Перечислитель будет перечислять только формат, соответствующий этому атрибуту. [ACMFORMATDETAILS] Допустимая структура (./nf-msacm-acmformatdetails.md). Перечислитель перечислит все предлагаемые форматы назначения для заданного формата pwfx . Этот механизм можно использовать вместо функции acmFormatSuggest , чтобы позволить приложению выбрать оптимальный формат для преобразования. При возврате член dwFormatIndex всегда будет иметь значение ноль. Если используется этот флаг, член wFormatTag структуры WAVEFORMATEX не может быть WAVE_FORMAT_UNKNOWN.
Значение Значение
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE Перечислитель должен перечислять только форматы, которые поддерживаются в качестве собственных форматов ввода или вывода на одном или нескольких установленных устройствах waveform-audio. Этот флаг позволяет приложению выбрать только собственные форматы для установленного устройства waveform-audio. Этот флаг должен использоваться с одним или обоими флагами ACM_FORMATENUMF_INPUT и ACM_FORMATENUMF_OUTPUT. При указании ACM_FORMATENUMF_INPUT и ACM_FORMATENUMF_OUTPUT перечисляются только форматы, которые можно открыть для ввода или вывода. Это верно независимо от того, указан ли этот флаг.
ACM_FORMATENUMF_INPUT Перечислитель должен перечислять только форматы, поддерживаемые для входных данных (записи).
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC Элемент nSamplesPerSec структуры WAVEFORMATEX , на который указывает элемент pwfx структуры ACMFORMATDETAILS , является допустимым. Перечислитель будет перечислять только формат, соответствующий этому атрибуту.
ACM_FORMATENUMF_OUTPUT Перечислитель должен перечислять только форматы, поддерживаемые для вывода (воспроизведения).
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE Элемент wBitsPerSample структуры WAVEFORMATEX , на который указывает элемент pwfx структуры ACMFORMATDETAILS , является допустимым. Перечислитель будет перечислять только формат, соответствующий этому атрибуту.
ACM_FORMATENUMF_WFORMATTAG Элемент wFormatTag структуры WAVEFORMATEX , на который указывает элемент pwfx структуры ACMFORMATDETAILS , является допустимым. Перечислитель будет перечислять только формат, соответствующий этому атрибуту. Элемент dwFormatTag структуры ACMFORMATDETAILS должен быть равен члену wFormatTag . Значение wFormatTag в этом случае не может быть WAVE_FORMAT_UNKNOWN.

Возвращаемое значение

Возвращает ноль при успешном выполнении или ошибке в противном случае. Возможные значения ошибок:

Код возврата Описание
ACMERR_NOTPOSSIBLE
 Не удается вернуть сведения о формате.
MMSYSERR_INVALFLAG
 По крайней мере один флаг недопустим.
MMSYSERR_INVALHANDLE
 Указанный дескриптор недопустим.
MMSYSERR_INVALPARAM
 По крайней мере один параметр недопустим.

Комментарии

Эта функция возвращает MMSYSERR_NOERROR (ноль), если не установлены подходящие драйверы ACM. Кроме того, функция обратного вызова вызываться не будет.

Примеры

В следующем примере показано, как перечислить форматы с тегом формата 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;
}

В следующем примере показана функция обратного вызова для предыдущего примера. Функция обратного вызова вызывается один раз для каждого соответствующего формата или до тех пор, пока обратный вызов не вернет значение 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;
}

Требования

   
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header msacm.h
Библиотека Msacm32.lib
DLL Msacm32.dll

См. также раздел

Функции сжатия звука

Диспетчер сжатия аудио