fungsi acmFormatEnum (msacm.h)

Artikel
08/24/2023

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

Sintaks

MMRESULT ACMAPI acmFormatEnum(
  HACMDRIVER         had,
  LPACMFORMATDETAILS pafd,
  ACMFORMATENUMCB    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

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

Anggota fdwSupport 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 boleh 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 format pwfx yang diberikan. Jika bendera ini digunakan, anggota wFormatTag dari 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. Anggota dwFormatIndex akan selalu diatur ke nol saat dikembalikan. Jika bendera ini digunakan, anggota wFormatTag dari struktur WAVEFORMATEX tidak dapat WAVE_FORMAT_UNKNOWN.

Nilai	Makna
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 dari 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	Anggota nSamplesPerSec dari struktur WAVEFORMATEX yang diarahkan oleh anggota pwfx 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 diarahkan oleh anggota pwfx struktur ACMFORMATDETAILS valid. Enumerator hanya akan menghitung format yang sesuai dengan atribut ini.
ACM_FORMATENUMF_WFORMATTAG	Anggota wFormatTag dari struktur WAVEFORMATEX yang diarahkan oleh anggota pwfx struktur ACMFORMATDETAILS valid. Enumerator hanya akan menghitung format yang sesuai dengan atribut ini. Anggota dwFormatTag dari struktur ACMFORMATDETAILS harus sama dengan anggota wFormatTag . Nilai wFormatTag tidak dapat WAVE_FORMAT_UNKNOWN dalam kasus ini.

Nilai kembali

Mengembalikan nol jika berhasil atau kesalahan sebaliknya. Nilai kesalahan yang mungkin termasuk yang berikut ini.

Menampilkan 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.

Keterangan

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


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

Lihat juga

Fungsi Pemadatan Audio

Pengelola Pemadatan Audio

Bagikan melalui