acmFormatEnumA-Funktion (msacm.h)

Artikel
11/20/2024

Die acmFormatEnum-Funktion listet Waveform-Audioformate auf, die für ein bestimmtes Formattag von einem ACM-Treiber verfügbar sind. Diese Funktion wird weiterhin aufgezählt, bis es keine geeigneten Formate für das Formattag gibt, oder die Rückruffunktion gibt FALSEzurück.

Syntax

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

Parameter

had

Behandeln Sie den ACM-Treiber, um Details im Waveform-Audioformat abzufragen. Wenn dieser Parameter NULL-ist, verwendet das ACM die Details des ersten geeigneten ACM-Treibers.

pafd

Zeigen Sie auf eine ACMFORMATDETAILS- Struktur, um die an die fnCallback--Funktion übergebenen Formatdetails zu enthalten. Diese Struktur muss die cbStruct, pwfxund cbwfx Member der ACMFORMATDETAILS Struktur initialisiert haben. Das dwFormatTag Member muss auch für WAVE_FORMAT_UNKNOWN oder ein gültiges Formattag initialisiert werden.

Das fdwSupport- Element der Struktur muss auf Null initialisiert werden.

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

fnCallback

Adresse einer anwendungsdefinierten Rückruffunktion. Siehe acmFormatEnumCallback. Dieser Parameter kann nicht NULL-werden.

dwInstance

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

fdwEnum

Flags zum Aufzählen der Formate für ein bestimmtes Formattag. Die folgenden Werte sind definiert.

[ACMFORMATDETAILS](./nf-msacm-acmformatdetails.md) Struktur ist gültig. Der Enumerator enumeriert nur Zielformate, die aus dem angegebenen pwfx--Format konvertiert werden können. Wenn dieses Flag verwendet wird, kann das wFormatTag Member der WAVEFORMATEX- Struktur nicht WAVE_FORMAT_UNKNOWN werden. [ACMFORMATDETAILS](./nf-msacm-acmformatdetails.md) Struktur ist gültig. Der Enumerator enumeriert nur ein Format, das diesem Attribut entspricht. [ACMFORMATDETAILS](./nf-msacm-acmformatdetails.md) Struktur ist gültig. Der Enumerator enumeriert alle vorgeschlagenen Zielformate für das angegebene pwfx--Format. 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- Member wird immer auf Null festgelegt, wenn es zurückgegeben wird. Wenn dieses Flag verwendet wird, kann das wFormatTag Member 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 systemeigene Eingabe- oder Ausgabeformate auf einem oder mehreren der installierten Waveform-Audiogeräte unterstützt werden. Dieses Kennzeichen bietet eine Möglichkeit für eine Anwendung, nur systemeigene Formate für ein installiertes Waveform-Audiogerät auszuwählen. Dieses Kennzeichen 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 Kennzeichen angegeben ist.
ACM_FORMATENUMF_INPUT	Enumerator sollte nur Formate aufzählen, die für die Eingabe (Aufzeichnung) unterstützt werden.
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	Das nSamplesPerSec Mitglied der WAVEFORMATEX- Struktur, auf die das pwfx- Mitglied der ACMFORMATDETAILS Struktur verweist, ist gültig. Der Enumerator enumeriert nur ein Format, 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 Mitglied der WAVEFORMATEX- Struktur, auf die pwfx Member der ACMFORMATDETAILS Struktur verweist, ist gültig. Der Enumerator enumeriert nur ein Format, das diesem Attribut entspricht.
ACM_FORMATENUMF_WFORMATTAG	Das wFormatTag- Mitglied der WAVEFORMATEX- Struktur, auf die das pwfx- Mitglied der ACMFORMATDETAILS Struktur verweist, ist gültig. Der Enumerator enumeriert nur ein Format, das diesem Attribut entspricht. Das dwFormatTag- Mitglied der ACMFORMATDETAILS--Struktur muss dem wFormatTag-element entsprechen. Der Wert von wFormatTag- kann in diesem Fall nicht WAVE_FORMAT_UNKNOWN werden.

Rückgabewert

Gibt Null zurück, wenn dies erfolgreich ist oder andernfalls ein Fehler auftritt. 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 Kennzeichen ist ungültig.
MMSYSERR_INVALHANDLE	Der angegebene Handle ist ungültig.
MMSYSERR_INVALPARAM	Mindestens ein Parameter ist ungültig.

Bemerkungen

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

Das folgende Beispiel zeigt, wie Formate mit dem WAVE_FORMAT_MPEGLAYER3 Formattag aufgezählt werden.


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 einmal für jedes übereinstimmende Format 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;
}

Anmerkung

Der msacm.h-Header definiert acmFormatEnum als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	msacm.h
Library	Msacm32.lib
DLL-	Msacm32.dll

Siehe auch

Audiokomprimierungsfunktionen

Audiokomprimierungs-Manager

Freigeben über