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函式的格式詳細資料。 此結構必須初始化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 WAVE_FORMAT_UNKNOWN的 [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 結構有效。 列舉值只會列舉符合此屬性的格式。 [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 結構有效。 列舉值會列舉給定 pwfx 格式的所有建議目的地格式。 您可以使用這個機制來取代 acmFormatSuggest 函式，以允許應用程式選擇最佳的建議格式進行轉換。 傳回時，dwFormatIndex成員一律會設定為零。如果使用這個旗標，則無法WAVE_FORMAT_UNKNOWN WAVE_FORMAT_UNKNOWN的

值	意義
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	ACMFORMATDETAILS結構之 pwfx成員所指向的WAATEX結構的wBitsPerSample成員有效。 列舉值只會列舉符合此屬性的格式。
ACM_FORMATENUMF_WFORMATTAG	ACMFORMATDETAILS結構之 pwfx成員所指向的WASATEX結構的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;
}

注意

msacm.h 標頭會將 acmFormatEnum 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

需求

最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	msacm.h
程式庫	Msacm32.lib
Dll	Msacm32.dll

另請參閱

音訊壓縮函式

音訊壓縮管理員