acmFormatEnum-Funktion (msacm.h)

Artikel
08/24/2023

Die Funktion acmFormatEnum listet Waveform-Audioformate auf, die für ein bestimmtes Formattag aus einem ACM-Treiber verfügbar sind. Diese Funktion wird weiterhin aufgelistet, bis keine geeigneten Formate für das Formattag vorhanden sind oder die Rückruffunktion FALSE zurückgibt.

Syntax

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

Parameter

had

Verarbeiten Sie den ACM-Treiber, um Details des Waveform-Audioformats abzufragen. Wenn dieser Parameter NULL ist, verwendet der ACM die Details des ersten geeigneten ACM-Treibers.

pafd

Zeiger auf eine ACMFORMATDETAILS-Struktur , die die Formatdetails enthält, die an die fnCallback-Funktion übergeben werden. Diese Struktur muss die Elemente cbStruct, pwfx und cbwfx der ACMFORMATDETAILS-Struktur initialisiert haben. Das dwFormatTag-Element muss auch für WAVE_FORMAT_UNKNOWN oder ein gültiges Formattag initialisiert werden.

Das fdwSupport-Element der Struktur muss mit 0 initialisiert werden.

Um die erforderliche Größe des pwfx-Puffers zu ermitteln, rufen Sie acmMetrics mit dem flag ACM_METRIC_MAX_SIZE_FORMAT auf.

fnCallback

Adresse einer anwendungsdefinierten Rückruffunktion. Siehe acmFormatEnumCallback. Dieser Parameter darf nicht NULL sein.

dwInstance

Ein anwendungsdefinierter 64-Bit- (DWORD_PTR) oder 32-Bit-Wert (DWORD), der zusammen mit ACM-Formatdetails an die Rückruffunktion übergeben wird.

fdwEnum

Flags zum Auflisten der Formate für ein bestimmtes Formattag. Die folgenden Werte werden definiert.

[ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md)-Struktur ist gültig. Der Enumerator listet nur Zielformate auf, die aus dem angegebenen pwfx-Format konvertiert werden können. Wenn dieses Flag verwendet wird, kann das wFormatTag-Element der WAVEFORMATEX-Struktur nicht WAVE_FORMAT_UNKNOWN werden. [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md)-Struktur ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht. [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md)-Struktur ist gültig. Der Enumerator listet alle vorgeschlagenen Zielformate für das angegebene pwfx-Format auf . Dieser Mechanismus kann anstelle der acmFormatSuggest-Funktion verwendet werden, damit eine Anwendung das am besten vorgeschlagene Format für die Konvertierung auswählen kann. Das dwFormatIndex-Element wird bei der Rückgabe immer auf 0 festgelegt. Wenn dieses Flag verwendet wird, kann das wFormatTag-Element der WAVEFORMATEX-Struktur nicht WAVE_FORMAT_UNKNOWN werden.

Wert	Bedeutung
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE	Der Enumerator sollte nur Formate aufzählen, die als native Eingabe- oder Ausgabeformate auf einem oder mehreren installierten Waveform-Audiogeräten unterstützt werden. Dieses Flag bietet eine Möglichkeit für eine Anwendung, nur native Formate für ein installiertes Waveform-Audiogerät auszuwählen. Dieses Flag muss mit einem oder beiden ACM_FORMATENUMF_INPUT- und ACM_FORMATENUMF_OUTPUT-Flags verwendet werden. Wenn Sie sowohl ACM_FORMATENUMF_INPUT als auch ACM_FORMATENUMF_OUTPUT angeben, werden nur Formate aufgelistet, die für die Eingabe oder Ausgabe geöffnet werden können. Dies gilt unabhängig davon, ob dieses Flag angegeben wird.
ACM_FORMATENUMF_INPUT	Der Enumerator sollte nur Formate aufzählen, die für die Eingabe (Aufzeichnung) unterstützt werden.
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	Das nSamplesPerSec-Element der WAVEFORMATEX-Struktur , auf das vom pwfx-Element der ACMFORMATDETAILS-Struktur verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht.
ACM_FORMATENUMF_OUTPUT	Enumerator sollte nur Formate aufzählen, die für die Ausgabe (Wiedergabe) unterstützt werden.
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE	Das wBitsPerSample-Element der WAVEFORMATEX-Struktur , auf das vom pwfx-Member der ACMFORMATDETAILS-Struktur verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht.
ACM_FORMATENUMF_WFORMATTAG	Das wFormatTag-Element der WAVEFORMATEX-Struktur , auf das vom pwfx-Element der ACMFORMATDETAILS-Struktur verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht. Das dwFormatTag-Element der ACMFORMATDETAILS-Struktur muss gleich dem wFormatTag-Member sein. Der Wert von wFormatTag kann in diesem Fall nicht WAVE_FORMAT_UNKNOWN werden.

Rückgabewert

Gibt null zurück, wenn der Vorgang erfolgreich war oder andernfalls ein Fehler. Mögliche Fehlerwerte sind:

Rückgabecode	Beschreibung
ACMERR_NOTPOSSIBLE	Die Details für das Format können nicht zurückgegeben werden.
MMSYSERR_INVALFLAG	Mindestens ein Flag ist ungültig.
MMSYSERR_INVALHANDLE	Das angegebene Handle ist ungültig.
MMSYSERR_INVALPARAM	Mindestens ein Parameter ist ungültig.

Hinweise

Diese Funktion gibt MMSYSERR_NOERROR (null) zurück, wenn keine geeigneten ACM-Treiber installiert sind. Darüber hinaus wird die Rückruffunktion nicht aufgerufen.

Beispiele

Im folgenden Beispiel wird gezeigt, wie Formate aufgelistet werden, die das Tag WAVE_FORMAT_MPEGLAYER3 format aufweisen.


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;
}

Das nächste Beispiel zeigt die Rückruffunktion für das vorherige Beispiel. Die Rückruffunktion wird für jedes übereinstimmende Format einmal aufgerufen oder bis der Rückruf FALSE zurückgibt.


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;
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	msacm.h
Bibliothek	Msacm32.lib
DLL	Msacm32.dll

Weitere Informationen

Audiokomprimierungsfunktionen

Audiokomprimierungs-Manager

Freigeben über