通过

acmFormatEnum 函数 (msacm.h)

  • 项目

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

语法

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

parameters

had

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

pafd

指向 ACMFORMATDETAILS 结构的指针，该结构包含传递给 fnCallback 函数的格式详细信息。 此结构必须初始化 ACMFORMATDETAILS 结构的 cbStruct、pwfx 和 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 WAVEFORMATEX 结构的 wFormatTag 成员。 [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 结构有效。 枚举器将仅枚举符合此属性的格式。 [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 结构有效。 枚举器将枚举给定 pwfx 格式的所有建议目标格式。 可以使用此机制代替 acmFormatSuggest 函数，以允许应用程序选择最佳建议格式进行转换。 返回时，dwFormatIndex 成员将始终设置为零。如果使用此标志，则无法WAVE_FORMAT_UNKNOWN WAVEFORMATEX 结构的 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 成员所指向的 WAVEFORMATEX 结构的 nSamplesPerSec 成员有效。 枚举器将仅枚举符合此属性的格式。
ACM_FORMATENUMF_OUTPUT 枚举器应仅枚举输出 (播放) 支持的格式。
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE ACMFORMATDETAILS 结构的 pwfx 成员所指向的 WAVEFORMATEX 结构的 wBitsPerSample 成员有效。 枚举器将仅枚举符合此属性的格式。
ACM_FORMATENUMF_WFORMATTAG ACMFORMATDETAILS 结构的 pwfx 成员指向的 WAVEFORMATEX 结构的 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;
}

要求

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

另请参阅

音频压缩函数

音频压缩管理器