acmFormatEnum 函数 (msacm.h)

acmFormatEnum 函数枚举 ACM 驱动程序中给定格式标记可用的波形音频格式。 此函数将继续枚举,直到格式标记没有更合适的格式或回调函数返回 FALSE

语法

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

参数

had

用于查询波形音频格式详细信息的 ACM 驱动程序的句柄。 如果此参数为 NULL,ACM 将使用第一个合适的 ACM 驱动程序中的详细信息。

pafd

指向 ACMFORMATDETAILS 结构的指针,该结构包含传递给 fnCallback 函数的格式详细信息。 此结构必须初始化 ACMFORMATDETAILS 结构的 cbStructpwfxcbwfx 成员。 dwFormatTag 成员还必须初始化为WAVE_FORMAT_UNKNOWN或有效的格式标记。

结构的 fdwSupport 成员必须初始化为零。

若要查找 pwfx 缓冲区所需的大小,请使用 ACM_METRIC_MAX_SIZE_FORMAT 标志调用 acmMetrics

fnCallback

应用程序定义的回调函数的地址。 请参阅 acmFormatEnumCallback。 此参数不能为 NULL

dwInstance

64 位 (DWORD_PTR) 或 32 位 (DWORD) 传递给回调函数的应用程序定义值以及 ACM 格式详细信息。

fdwEnum

用于枚举给定格式标记的格式的标志。 定义了以下值。

[ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 结构有效。 枚举器将仅枚举可从给定 pwfx 格式转换的目标格式。如果使用此标志,则不能WAVE_FORMAT_UNKNOWN波形图X 结构的 wFormatTag 成员。 [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 结构有效。 枚举器将仅枚举符合此属性的格式。 [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 结构有效。 枚举器将枚举给定 pwfx 格式的所有建议目标格式。 可以使用此机制代替 acmFormatSuggest 函数,以允许应用程序选择最佳建议格式进行转换。 dwFormatIndex 成员在返回时始终设置为零。如果使用此标志,则不能WAVE_FORMAT_UNKNOWN波形图X 结构的 wFormatTag 成员。
Value 含义
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE 枚举器应仅枚举在一个或多个已安装波形音频设备上作为本机输入或输出格式支持的格式。 此标志为应用程序仅选择本机到已安装波形音频设备的格式提供了一种方法。 此标志必须与一个或两个ACM_FORMATENUMF_INPUT和ACM_FORMATENUMF_OUTPUT标志一起使用。 指定ACM_FORMATENUMF_INPUT和ACM_FORMATENUMF_OUTPUT将仅枚举可为输入或输出打开的格式。 无论是否指定此标志,此标志都是如此。
ACM_FORMATENUMF_INPUT 枚举器应仅枚举输入 (录制) 支持的格式。
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC ACMFORMATDETAILS 结构的 pwfx 成员指向的波形值X 结构的 nSamplesPerSec 成员有效。 枚举器将仅枚举符合此属性的格式。
ACM_FORMATENUMF_OUTPUT 枚举器应仅枚举输出 (播放) 支持的格式。
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE 由 ACMFORMATDETAILS 结构 pwfx 成员指向的波形图 X 结构的 wBitsPerSample 成员有效。 枚举器将仅枚举符合此属性的格式。
ACM_FORMATENUMF_WFORMATTAG 由 ACMFORMATDETAILS 结构 pwfx 成员指向的波形符结构wFormatTag 成员有效。 枚举器将仅枚举符合此属性的格式。 ACMFORMATDETAILS 结构的 dwFormatTag 成员必须等于 wFormatTag 成员。在这种情况下,wFormatTag 的值不能WAVE_FORMAT_UNKNOWN。

返回值

如果成功,则返回零;否则返回错误。 可能的错误值包括以下内容。

返回代码 说明
ACMERR_NOTPOSSIBLE
无法返回格式的详细信息。
MMSYSERR_INVALFLAG
至少有一个标志无效。
MMSYSERR_INVALHANDLE
指定的句柄无效。
MMSYSERR_INVALPARAM
至少有一个参数无效。

注解

如果未安装合适的 ACM 驱动程序,此函数将返回MMSYSERR_NOERROR (零) 。 此外,不会调用回调函数。

示例

以下示例演示如何枚举具有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
标头 msacm.h
Library Msacm32.lib
DLL Msacm32.dll

请参阅

音频压缩函数

音频压缩管理器