функция acmFormatEnumW (msacm.h)

Статья
11/20/2024

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

Синтаксис

MMRESULT ACMAPI acmFormatEnumW(
  HACMDRIVER          had,
  LPACMFORMATDETAILSW pafd,
  ACMFORMATENUMCBW    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 будет перечислять только форматы, которые можно открыть для входных или выходных данных. Это значение имеет значение true, независимо от того, указан ли этот флаг.
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;
}

Заметка

Заголовок msacm.h определяет acmFormatEnum как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	msacm.h
библиотеки	Msacm32.lib
DLL	Msacm32.dll

См. также

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

диспетчер сжатия звука

Поделиться через