通过

acmFormatEnumA 函数 （msacm.h）

  • 项目

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

语法

MMRESULT ACMAPI acmFormatEnumA(
  HACMDRIVER          had,
  LPACMFORMATDETAILSA pafd,
  ACMFORMATENUMCBA    fnCallback,
  DWORD_PTR           dwInstance,
  DWORD               fdwEnum
);

参数

had

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

pafd

指向 ACMFORMATDETAILS 结构的指针，该结构包含传递给 fnCallback 函数的格式详细信息。 此结构必须 cbStruct、pwfx，以及初始化 ACMFORMATDETAILS 结构的 cbwfx 成员。 还必须将 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 波形 结构的 wFormatTag 成员。 [ACMFORMATDETAILS]（./nf-msacm-acmformatdetails.md） 结构有效。 枚举器将仅枚举符合此属性的格式。 [ACMFORMATDETAILS]（./nf-msacm-acmformatdetails.md） 结构有效。 枚举器将枚举给定 pwfx 格式的所有建议目标格式。 可以使用此机制来代替 acmFormatSuggest 函数，以允许应用程序选择最佳建议的格式进行转换。 dwFormatIndex 成员在返回时始终设置为零。如果使用此标志，则无法WAVE_FORMAT_UNKNOWN 波形 结构的 wFormatTag 成员。
价值 意义
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 成员指向的 波形曲线结构 成员的 nSamplesPerSec 成员有效。 枚举器将仅枚举符合此属性的格式。
ACM_FORMATENUMF_OUTPUT 枚举器应仅枚举输出支持的格式（播放）。
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE wBitsPerSample波形图X 结构的成员，pwfxACMFORMATDETAILS 结构的成员有效。 枚举器将仅枚举符合此属性的格式。
ACM_FORMATENUMF_WFORMATTAG pwfxACMFORMATDETAILS 结构所指向的 波形图X 结构的 wFormatTag 成员有效。 枚举器将仅枚举符合此属性的格式。 ACMFORMATDETAILS 结构的 dwFormatTag 成员必须等于 wFormatTag 成员 。在这种情况下，无法WAVE_FORMAT_UNKNOWN wFormatTag 的值。

返回值

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

返回代码 描述
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;
}

注意

msacm.h 标头将 acmFormatEnum 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows 2000 Professional [仅限桌面应用]
支持的最低服务器 Windows 2000 Server [仅限桌面应用]
目标平台 窗户
标头 msacm.h
库 Msacm32.lib
DLL Msacm32.dll

另请参阅

音频压缩函数

音频压缩管理器