Funzione acmFormatEnum (msacm.h)

Articolo
08/24/2023

La funzione acmFormatEnum enumera i formati waveform-audio disponibili per un tag di formato specificato da un driver ACM. Questa funzione continua l'enumerazione finché non sono presenti formati più adatti per il tag di formato o la funzione di callback restituisce FALSE.

Sintassi

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

Parametri

had

Gestire il driver ACM per eseguire una query per ottenere i dettagli del formato audio waveform. Se questo parametro è NULL, ACM usa i dettagli del primo driver ACM appropriato.

pafd

Puntatore a una struttura ACMFORMATDETAILS per contenere i dettagli del formato passati alla funzione fnCallback . Questa struttura deve avere i membri cbStruct, pwfx e cbwfx della struttura ACMFORMATDETAILS inizializzata. Il membro dwFormatTag deve essere inizializzato anche in WAVE_FORMAT_UNKNOWN o in un tag di formato valido.

Il membro fdwSupport della struttura deve essere inizializzato su zero.

Per trovare le dimensioni necessarie del buffer pwfx , chiamare acmMetrics con il flag ACM_METRIC_MAX_SIZE_FORMAT.

fnCallback

Indirizzo di una funzione di callback definita dall'applicazione. Vedere acmFormatEnumCallback. Questo parametro non può essere NULL.

dwInstance

Valore definito dall'applicazione a 64 bit (DWORD_PTR) o A 32 bit (DWORD) passato alla funzione di callback insieme ai dettagli del formato ACM.

fdwEnum

Flag per enumerare i formati per un tag di formato specificato. Vengono definiti i valori seguenti.

[ACMFORMATDETAILS] Struttura (./nf-msacm-acmformatdetails.md) valida. L'enumeratore enumera solo i formati di destinazione che possono essere convertiti dal formato pwfx specificato. Se questo flag viene utilizzato, il membro wFormatTag della struttura WAVEFORMATEX non può essere WAVE_FORMAT_UNKNOWN. [ACMFORMATDETAILS] Struttura (./nf-msacm-acmformatdetails.md) valida. L'enumeratore enumera solo un formato conforme a questo attributo. [ACMFORMATDETAILS] Struttura (./nf-msacm-acmformatdetails.md) valida. L'enumeratore enumera tutti i formati di destinazione suggeriti per il formato pwfx specificato. Questo meccanismo può essere usato invece della funzione acmFormatSuggest per consentire a un'applicazione di scegliere il formato consigliato migliore per la conversione. Il membro dwFormatIndex verrà sempre impostato su zero al ritorno. Se questo flag viene utilizzato, il membro wFormatTag della struttura WAVEFORMATEX non può essere WAVE_FORMAT_UNKNOWN.

Valore	Significato
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE	L'enumeratore deve enumerare solo i formati supportati come formati di input o output nativi in uno o più dispositivi waveform-audio installati. Questo flag consente a un'applicazione di scegliere solo formati nativi in un dispositivo audio waveform installato. Questo flag deve essere usato con uno o entrambi i flag ACM_FORMATENUMF_INPUT e ACM_FORMATENUMF_OUTPUT. Specificando sia ACM_FORMATENUMF_INPUT che ACM_FORMATENUMF_OUTPUT verranno enumerati solo i formati che possono essere aperti per l'input o l'output. Ciò vale indipendentemente dal fatto che questo flag sia specificato.
ACM_FORMATENUMF_INPUT	L'enumeratore deve enumerare solo i formati supportati per l'input (registrazione).
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	Il membro nSamplesPerSec della struttura WAVEFORMATEX a cui punta il membro pwfx della struttura ACMFORMATDETAILS è valido. L'enumeratore enumera solo un formato conforme a questo attributo.
ACM_FORMATENUMF_OUTPUT	L'enumeratore deve enumerare solo i formati supportati per l'output (riproduzione).
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE	Il membro wBitsPerSample della struttura WAVEFORMATEX a cui punta il membro pwfx della struttura ACMFORMATDETAILS è valido. L'enumeratore enumera solo un formato conforme a questo attributo.
ACM_FORMATENUMF_WFORMATTAG	Il membro wFormatTag della struttura WAVEFORMATEX a cui punta il membro pwfx della struttura ACMFORMATDETAILS è valido. L'enumeratore enumera solo un formato conforme a questo attributo. Il membro dwFormatTag della struttura ACMFORMATDETAILS deve essere uguale al membro wFormatTag . Il valore di wFormatTag non può essere WAVE_FORMAT_UNKNOWN in questo caso.

Valore restituito

Restituisce zero se l'operazione ha esito positivo o un errore in caso contrario. I valori di errore possibili includono quanto segue.

Codice restituito	Descrizione
ACMERR_NOTPOSSIBLE	Impossibile restituire i dettagli per il formato.
MMSYSERR_INVALFLAG	Almeno un flag non è valido.
MMSYSERR_INVALHANDLE	L'handle specificato non è valido.
MMSYSERR_INVALPARAM	Almeno un parametro non è valido.

Commenti

Questa funzione restituirà MMSYSERR_NOERROR (zero) se non sono installati driver ACM appropriati. Inoltre, la funzione di callback non verrà chiamata.

Esempio

Nell'esempio seguente viene illustrato come enumerare i formati con il tag di formato 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;
}

Nell'esempio seguente viene illustrata la funzione di callback per l'esempio precedente. La funzione di callback viene chiamata una volta per ogni formato corrispondente o finché il callback non restituisce 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;
}

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	msacm.h
Libreria	Msacm32.lib
DLL	Msacm32.dll

Vedi anche

Funzioni di compressione audio

Gestione compressione audio

Share via