acmFormatEnumW, fonction (msacm.h)

Article
11/20/2024

La fonction acmFormatEnum énumère les formats audio de forme d’onde disponibles pour une balise de format donnée à partir d’un pilote ACM. Cette fonction continue d’énumérer jusqu’à ce qu’il n’y ait plus de formats appropriés pour la balise de format ou que la fonction de rappel retourne FALSE.

Syntaxe

MMRESULT ACMAPI acmFormatEnumW(
  HACMDRIVER          had,
  LPACMFORMATDETAILSW pafd,
  ACMFORMATENUMCBW    fnCallback,
  DWORD_PTR           dwInstance,
  DWORD               fdwEnum
);

Paramètres

had

Gérez le pilote ACM pour rechercher les détails du format audio waveform. Si ce paramètre est NULL, le gestionnaire de configuration ACM utilise les détails du premier pilote ACM approprié.

pafd

Pointeur vers une structure ACMFORMATDETAILS pour contenir les détails du format transmis à la fonction fnCallback. Cette structure doit avoir lecbStruct , pwfxet membres cbwfx de la structure ACMFORMATDETAILS initialisée. Le membre dwFormatTag doit également être initialisé pour WAVE_FORMAT_UNKNOWN ou une balise de format valide.

Le fdwSupport membre de la structure doit être initialisé à zéro.

Pour rechercher la taille requise de la mémoire tampon pwfx , appelez acmMetrics avec l’indicateur de ACM_METRIC_MAX_SIZE_FORMAT.

fnCallback

Adresse d’une fonction de rappel définie par l’application. Voir acmFormatEnumCallback. Ce paramètre ne peut pas être NULL.

dwInstance

Valeur définie par l’application 64 bits (DWORD_PTR) ou 32 bits (DWORD) transmise à la fonction de rappel, ainsi que les détails du format ACM.

fdwEnum

Indicateurs pour énumérer les formats d’une balise de format donnée. Les valeurs suivantes sont définies.

[ACMFORMATDETAILS]La structure (./nf-msacm-acmformatdetails.md) est valide. L’énumérateur énumère uniquement les formats de destination qui peuvent être convertis à partir du format pwfx donné. Si cet indicateur est utilisé, le membre wFormatTag de la structure WAVEFORMATEX ne peut pas être WAVE_FORMAT_UNKNOWN. [ACMFORMATDETAILS]La structure (./nf-msacm-acmformatdetails.md) est valide. L’énumérateur énumère uniquement un format conforme à cet attribut. [ACMFORMATDETAILS]La structure (./nf-msacm-acmformatdetails.md) est valide. L’énumérateur énumère tous les formats de destination suggérés pour le format pwfx donné. Ce mécanisme peut être utilisé au lieu de la fonction acmFormatSuggest pour permettre à une application de choisir le meilleur format suggéré pour la conversion. Le membredwFormatIndex est toujours défini sur zéro lors du retour. Si cet indicateur est utilisé, le membre wFormatTag de la structure WAVEFORMATEX ne peut pas être WAVE_FORMAT_UNKNOWN.

Valeur	Signification
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE	L’énumérateur ne doit énumérer que les formats pris en charge en tant que formats d’entrée ou de sortie natifs sur un ou plusieurs des appareils waveform-audio installés. Cet indicateur permet à une application de choisir uniquement les formats natifs d’un appareil waveform-audio installé. Cet indicateur doit être utilisé avec un ou les deux indicateurs ACM_FORMATENUMF_INPUT et ACM_FORMATENUMF_OUTPUT. La spécification de ACM_FORMATENUMF_INPUT et de ACM_FORMATENUMF_OUTPUT énumère uniquement les formats qui peuvent être ouverts pour l’entrée ou la sortie. Cela est vrai, que cet indicateur soit spécifié.
ACM_FORMATENUMF_INPUT	L’énumérateur doit énumérer uniquement les formats pris en charge pour l’entrée (enregistrement).
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	Le membre nSamplesPerSec de la structure WAVEFORMATEX pointée par le membre pwfx de la structure ACMFORMATDETAILS est valide. L’énumérateur énumère uniquement un format conforme à cet attribut.
ACM_FORMATENUMF_OUTPUT	L’énumérateur doit énumérer uniquement les formats pris en charge pour la sortie (lecture).
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE	Le membre wBitsPerSample de la structure WAVEFORMATEX pwfx membre de la structure ACMFORMATDETAILS est valide. L’énumérateur énumère uniquement un format conforme à cet attribut.
ACM_FORMATENUMF_WFORMATTAG	Le membre wFormatTag de la structure WAVEFORMATEX pointée par le membre pwfx de la structure ACMFORMATDETAILS est valide. L’énumérateur énumère uniquement un format conforme à cet attribut. Le membre dwFormatTag de la structure ACMFORMATDETAILS doit être égal au membre wFormatTag. La valeur de wFormatTag ne peut pas être WAVE_FORMAT_UNKNOWN dans ce cas.

Valeur de retour

Retourne zéro en cas de réussite ou d’erreur dans le cas contraire. Les valeurs d’erreur possibles sont les suivantes.

Retourner le code	Description
ACMERR_NOTPOSSIBLE	Les détails du format ne peuvent pas être retournés.
MMSYSERR_INVALFLAG	Au moins un indicateur n’est pas valide.
MMSYSERR_INVALHANDLE	Le handle spécifié n’est pas valide.
MMSYSERR_INVALPARAM	Au moins un paramètre n’est pas valide.

Remarques

Cette fonction retourne MMSYSERR_NOERROR (zéro) si aucun pilote ACM approprié n’est installé. De plus, la fonction de rappel n’est pas appelée.

Exemples

L’exemple suivant montre comment énumérer les formats qui ont la balise de 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;
}

L’exemple suivant montre la fonction de rappel de l’exemple précédent. La fonction de rappel est appelée une seule fois pour chaque format correspondant ou jusqu’à ce que le rappel retourne 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;
}

Note

L’en-tête msacm.h définit acmFormatEnum comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	msacm.h
bibliothèque	Msacm32.lib
DLL	Msacm32.dll

Voir aussi

fonctions de compression audio

du Gestionnaire de compression audio

Partager via