acmFormatEnumA, fonction (msacm.h)

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 acmFormatEnumA(
  HACMDRIVER          had,
  LPACMFORMATDETAILSA pafd,
  ACMFORMATENUMCBA    fnCallback,
  DWORD_PTR           dwInstance,
  DWORD               fdwEnum
);

Paramètres

had

Gérez le pilote ACM pour interroger les détails du format audio de forme d’onde. Si ce paramètre a la valeur NULL, ACM utilise les détails du premier pilote ACM approprié.

pafd

Pointeur vers une structure ACMFORMATDETAILS pour contenir les détails de format transmis à la fonction fnCallback . Les membres cbStruct, pwfx et cbwfx de la structure ACMFORMATDETAILS doivent être initialisés pour cette structure. Le membre dwFormatTag doit également être initialisé à WAVE_FORMAT_UNKNOWN ou à une balise de format valide.

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

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

fnCallback

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

dwInstance

Valeur définie par l’application 64 bits (DWORD_PTR) ou 32 bits (DWORD) qui est passée à la fonction de rappel avec les détails du format ACM.

fdwEnum

Indicateurs permettant d’é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é à la place de la fonction acmFormatSuggest pour permettre à une application de choisir le meilleur format suggéré pour la conversion. Le membre dwFormatIndex 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 doit énumérer uniquement les formats pris en charge en tant que formats d’entrée ou de sortie natifs sur un ou plusieurs des appareils audio de forme d’onde 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 l’un des indicateurs ACM_FORMATENUMF_INPUT et ACM_FORMATENUMF_OUTPUT ou les deux. 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é ou non.
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 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_WFORMATTAG	Le membre wFormatTag de la structure WAVEFORMATEX pointé 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 retournée

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

Code de retour	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.

Notes

Cette fonction retourne MMSYSERR_NOERROR (zéro) si aucun pilote ACM approprié n’est installé. En outre, 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 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;
}

Notes

L’en-tête msacm.h définit acmFormatEnum en tant qu’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. La combinaison 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.

Spécifications

Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	msacm.h
Bibliothèque	Msacm32.lib
DLL	Msacm32.dll

Voir aussi

Fonctions de compression audio

Gestionnaire de compression audio