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結構的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要有此旗標的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只會列舉只能針對輸入或輸出開啟的格式。 不論是否已指定此旗標，這都是 true。
ACM_FORMATENUMF_INPUT	列舉值應該只列舉輸入 (錄製) 支援的格式。
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	ACMFORMATDETAILS結構之 pwfx成員所指向之 GEOMETRATEX結構的nSamplesPerSec成員有效。 列舉值只會列舉符合此屬性的格式。
ACM_FORMATENUMF_OUTPUT	列舉值應該只列舉輸出 (播放) 支援的格式。
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE	ACMFORMATDETAILS結構之 pwfx成員所指向之 GEOMETRATEX結構的wBitsPerSample成員有效。 列舉值只會列舉符合此屬性的格式。
ACM_FORMATENUMF_WFORMATTAG	ACMFORMATDETAILS結構之 pwfx成員所指向之 GEOMETRATEX結構的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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	msacm.h
程式庫	Msacm32.lib
Dll	Msacm32.dll

另請參閱

音訊壓縮函式

音訊壓縮管理員