fungsi acmFormatEnumA (msacm.h)

Fungsi acmFormatEnum menghitung format waveform-audio yang tersedia untuk tag format tertentu dari driver ACM. Fungsi ini terus menghitung sampai tidak ada format yang lebih cocok untuk tag format atau fungsi panggilan balik mengembalikan FALSE.

Sintaksis

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

Parameter

had

Tangani ke driver ACM untuk mengkueri detail format waveform-audio. Jika parameter ini NULL, ACM menggunakan detail dari driver ACM pertama yang sesuai.

pafd

Penunjuk ke struktur ACMFORMATDETAILS untuk berisi detail format yang diteruskan ke fungsi fnCallback . Struktur ini harus memilikicbStruct , pwfx, dan anggota cbwfx dari struktur ACMFORMATDETAILS yang diinisialisasi. Anggota dwFormatTag juga harus diinisialisasi ke WAVE_FORMAT_UNKNOWN atau tag format yang valid.

fdwSupport anggota struktur harus diinisialisasi ke nol.

Untuk menemukan ukuran buffer pwfx yang diperlukan, panggil acmMetrics dengan bendera ACM_METRIC_MAX_SIZE_FORMAT.

fnCallback

Alamat fungsi panggilan balik yang ditentukan aplikasi. Lihat acmFormatEnumCallback. Parameter ini tidak dapat null.

dwInstance

Nilai yang ditentukan aplikasi 64-bit (DWORD_PTR) atau 32-bit (DWORD) yang diteruskan ke fungsi panggilan balik bersama dengan detail format ACM.

fdwEnum

Bendera untuk menghitung format untuk tag format tertentu. Nilai berikut ditentukan.

[ACMFORMATDETAILS]Struktur (./nf-msacm-acmformatdetails.md) valid. Enumerator hanya akan menghitung format tujuan yang dapat dikonversi dari formatpwfx yang diberikan. Jika bendera ini digunakan, wFormatTag anggota struktur WAVEFORMATEX tidak dapat WAVE_FORMAT_UNKNOWN. [ACMFORMATDETAILS]Struktur (./nf-msacm-acmformatdetails.md) valid. Enumerator hanya akan menghitung format yang sesuai dengan atribut ini. [ACMFORMATDETAILS]Struktur (./nf-msacm-acmformatdetails.md) valid. Enumerator akan menghitung semua format tujuan yang disarankan untuk format pwfx yang diberikan. Mekanisme ini dapat digunakan alih-alih fungsi acmFormatSuggest untuk memungkinkan aplikasi memilih format terbaik yang disarankan untuk konversi. AnggotadwFormatIndex akan selalu diatur ke nol saat dikembalikan. Jika bendera ini digunakan, wFormatTag anggota struktur WAVEFORMATEX tidak dapat WAVE_FORMAT_UNKNOWN.

Nilai	Arti
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE	Enumerator hanya boleh menghitung format yang didukung sebagai format input atau output asli pada satu atau beberapa perangkat waveform-audio yang diinstal. Bendera ini menyediakan cara bagi aplikasi untuk memilih hanya format asli untuk perangkat waveform-audio yang diinstal. Bendera ini harus digunakan dengan satu atau kedua bendera ACM_FORMATENUMF_INPUT dan ACM_FORMATENUMF_OUTPUT. Menentukan ACM_FORMATENUMF_INPUT dan ACM_FORMATENUMF_OUTPUT hanya akan menghitung format yang dapat dibuka untuk input atau output. Ini benar terlepas dari apakah bendera ini ditentukan.
ACM_FORMATENUMF_INPUT	Enumerator harus menghitung hanya format yang didukung untuk input (perekaman).
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	nSamplesPerSec anggota struktur WAVEFORMATEX yang ditunjukkan oleh pwfx anggota struktur ACMFORMATDETAILS valid. Enumerator hanya akan menghitung format yang sesuai dengan atribut ini.
ACM_FORMATENUMF_OUTPUT	Enumerator harus menghitung hanya format yang didukung untuk output (pemutaran).
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE	Anggota wBitsPerSample dari struktur WAVEFORMATEX yang ditujukkan oleh anggota pwfx struktur ACMFORMATDETAILS yang valid. Enumerator hanya akan menghitung format yang sesuai dengan atribut ini.
ACM_FORMATENUMF_WFORMATTAG	wFormatTag anggota struktur WAVEFORMATEX yang ditunjukkan oleh pwfx anggota struktur ACMFORMATDETAILS valid. Enumerator hanya akan menghitung format yang sesuai dengan atribut ini. dwFormatTag anggota ACMFORMATDETAILS harus sama dengan anggota wFormatTag . Nilai wFormatTag tidak dapat WAVE_FORMAT_UNKNOWN dalam kasus ini.

Mengembalikan nilai

Mengembalikan nol jika berhasil atau kesalahan sebaliknya. Kemungkinan nilai kesalahan termasuk yang berikut ini.

Mengembalikan kode	Deskripsi
ACMERR_NOTPOSSIBLE	Detail untuk format tidak dapat dikembalikan.
MMSYSERR_INVALFLAG	Setidaknya satu bendera tidak valid.
MMSYSERR_INVALHANDLE	Handel yang ditentukan tidak valid.
MMSYSERR_INVALPARAM	Setidaknya satu parameter tidak valid.

Komentar

Fungsi ini akan mengembalikan MMSYSERR_NOERROR (nol) jika tidak ada driver ACM yang cocok yang diinstal. Selain itu, fungsi panggilan balik tidak akan dipanggil.

Contoh

Contoh berikut menunjukkan cara menghitung format yang memiliki tag format 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;
}

Contoh berikutnya menunjukkan fungsi panggilan balik untuk contoh sebelumnya. Fungsi panggilan balik dipanggil sekali untuk setiap format yang cocok atau sampai panggilan balik mengembalikan 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;
}

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Platform Target	Windows
Header	msacm.h
Pustaka	Msacm32.lib
DLL	Msacm32.dll

Lihat juga

Fungsi Kompresi Audio

Pengelola Kompresi Audio