Funzione acmFormatEnumA (msacm.h)

Articolo
11/20/2024

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

Sintassi

MMRESULT ACMAPI acmFormatEnumA(
  HACMDRIVER          had,
  LPACMFORMATDETAILSA pafd,
  ACMFORMATENUMCBA    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 di ACMFORMATDETAILS per contenere i dettagli del formato passati alla funzione fnCallback . Questa struttura deve avere cbStruct, pwfxe membri cbwfx della struttura ACMFORMATDETAILS inizializzata. Anche il membro dwFormatTag deve essere inizializzato in WAVE_FORMAT_UNKNOWN o in un tag di formato valido.

Il fdwSupport membro della struttura deve essere inizializzato su zero.

Per trovare le dimensioni necessarie del buffer di pwfx , chiamare acmMetrics con il flag di 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 viene utilizzato questo flag, non è possibile WAVE_FORMAT_UNKNOWN membro wFormatTag della struttura WAVEFORMATEX . [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 viene utilizzato questo flag, non è possibile WAVE_FORMAT_UNKNOWN membro wFormatTag della struttura WAVEFORMATEX .

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 i formati nativi di un dispositivo waveform-audio 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. Questo 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 di 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 di wBitsPerSample della struttura WAVEFORMATEX a cui punta il membro pwfx della struttura ACMFORMATDETAILS è valida. 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 . L'enumeratore enumera solo un formato conforme a questo attributo. Il membro dwFormatTag del 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 possibili valori di errore 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.

Osservazioni

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

Esempi

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

Nota

L'intestazione msacm.h definisce acmFormatEnum come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	msacm.h
libreria	Msacm32.lib
dll	Msacm32.dll

Vedere anche

funzioni di compressione audio

gestione compressione audio

Condividi tramite