acmFormatEnumA 함수(msacm.h)

아티클
03/15/2023

acmFormatEnum 함수는 ACM 드라이버에서 지정된 형식 태그에 사용할 수 있는 파형 오디오 형식을 열거합니다. 이 함수는 서식 태그에 더 이상 적합한 형식이 없거나 콜백 함수가 FALSE를 반환할 때까지 계속 열거합니다.

구문

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

매개 변수

had

파형 오디오 형식 세부 정보를 쿼리하는 ACM 드라이버에 대한 핸들입니다. 이 매개 변수가 NULL인 경우 ACM은 첫 번째 적합한 ACM 드라이버의 세부 정보를 사용합니다.

pafd

fnCallback 함수에 전달된 형식 세부 정보를 포함하는 ACMFORMATDETAILS 구조체에 대한 포인터입니다. 이 구조체에는 ACMFORMATDETAILS 구조체의 cbStruct, pwfx 및 cbwfx 멤버가 초기화되어야 합니다. dwFormatTag 멤버도 WAVE_FORMAT_UNKNOWN 또는 유효한 형식 태그로 초기화해야 합니다.

구조체의 fdwSupport 멤버를 0으로 초기화해야 합니다.

pwfx 버퍼의 필요한 크기를 찾으려면 ACM_METRIC_MAX_SIZE_FORMAT 플래그를 사용하여 acmMetrics를 호출합니다.

fnCallback

애플리케이션 정의 콜백 함수의 주소입니다. acmFormatEnumCallback을 참조하세요. 이 매개 변수는 NULL일 수 없습니다.

dwInstance

ACM 형식 세부 정보와 함께 콜백 함수에 전달되는 64비트(DWORD_PTR) 또는 32비트(DWORD) 애플리케이션 정의 값입니다.

fdwEnum

지정된 형식 태그의 형식을 열거하기 위한 플래그입니다. 다음 값이 정의됩니다.

[ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 구조체가 유효합니다. 열거자는 지정된 pwfx 형식에서 변환할 수 있는 대상 형식만 열거합니다. 이 플래그를 사용하는 경우 WAVEFORMATEX 구조체의 wFormatTag 멤버를 WAVE_FORMAT_UNKNOWN 수 없습니다. [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 구조체가 유효합니다. 열거자는 이 특성을 준수하는 형식만 열거합니다. [ACMFORMATDETAILS] (./nf-msacm-acmformatdetails.md) 구조체가 유효합니다. 열거자는 지정된 pwfx 형식에 대해 제안된 모든 대상 형식을 열거합니다. 이 메커니즘은 acmFormatSuggest 함수 대신 사용하여 애플리케이션이 변환에 가장 적합한 형식을 선택할 수 있도록 할 수 있습니다. dwFormatIndex 멤버는 반환 시 항상 0으로 설정됩니다. 이 플래그를 사용하는 경우 WAVEFORMATEX 구조체의 wFormatTag 멤버를 WAVE_FORMAT_UNKNOWN 수 없습니다.

값	의미
ACM_FORMATENUMF_CONVERT
ACM_FORMATENUMF_HARDWARE	열거자는 하나 이상의 설치된 파형 오디오 디바이스에서 네이티브 입력 또는 출력 형식으로 지원되는 형식만 열거해야 합니다. 이 플래그는 애플리케이션이 설치된 파형 오디오 디바이스에 네이티브 형식만 선택할 수 있는 방법을 제공합니다. 이 플래그는 ACM_FORMATENUMF_INPUT 및 ACM_FORMATENUMF_OUTPUT 플래그 중 하나 또는 둘 다와 함께 사용해야 합니다. ACM_FORMATENUMF_INPUT 및 ACM_FORMATENUMF_OUTPUT 모두 지정하면 입력 또는 출력에 대해 열 수 있는 형식만 열거됩니다. 이 플래그가 지정되었는지 여부에 관계없이 true입니다.
ACM_FORMATENUMF_INPUT	열거자는 입력(녹음)에 지원되는 형식만 열거해야 합니다.
ACM_FORMATENUMF_NCHANNELS
ACM_FORMATENUMF_NSAMPLESPERSEC	ACMFORMATDETAILS 구조체의 pwfx 멤버가 가리키는 WAVEFORMATEX 구조체의 nSamplesPerSec 멤버가 유효합니다. 열거자는 이 특성을 준수하는 형식만 열거합니다.
ACM_FORMATENUMF_OUTPUT	열거자는 출력(재생)에 지원되는 형식만 열거해야 합니다.
ACM_FORMATENUMF_SUGGEST
ACM_FORMATENUMF_WBITSPERSAMPLE	ACMFORMATDETAILS 구조체의 pwfx 멤버가 가리키는 WAVEFORMATEX 구조체의 wBitsPerSample 멤버가 유효합니다. 열거자는 이 특성을 준수하는 형식만 열거합니다.
ACM_FORMATENUMF_WFORMATTAG	ACMFORMATDETAILS 구조체의 pwfx 멤버가 가리키는 WAVEFORMATEX 구조체의 wFormatTag 멤버가 유효합니다. 열거자는 이 특성을 준수하는 형식만 열거합니다. ACMFORMATDETAILS 구조체의 dwFormatTag 멤버는 wFormatTag 멤버와 같아야 합니다. 이 경우 wFormatTag 값을 WAVE_FORMAT_UNKNOWN 수 없습니다.

반환 값

성공하면 0을 반환하고, 그렇지 않으면 오류를 반환합니다. 가능한 오류 값은 다음과 같습니다.

반환 코드	설명
ACMERR_NOTPOSSIBLE	형식에 대한 세부 정보를 반환할 수 없습니다.
MMSYSERR_INVALFLAG	하나 이상의 플래그가 잘못되었습니다.
MMSYSERR_INVALHANDLE	지정한 핸들이 잘못되었습니다.
MMSYSERR_INVALPARAM	하나 이상의 매개 변수가 잘못되었습니다.

설명

이 함수는 적합한 ACM 드라이버가 설치되지 않은 경우 MMSYSERR_NOERROR(0)을 반환합니다. 또한 콜백 함수는 호출되지 않습니다.

예제

다음 예제에서는 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;
}

다음 예제에서는 이전 예제의 콜백 함수를 보여줍니다. 콜백 함수는 일치하는 각 형식에 대해 한 번 호출되거나 콜백이 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;
}

참고

msacm.h 헤더는 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 acmFormatEnum을 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	msacm.h
라이브러리	Msacm32.lib
DLL	Msacm32.dll

참고 항목

오디오 압축 함수

오디오 압축 관리자

Share via

acmFormatEnumA 함수(msacm.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

참고 항목

피드백

피드백

추가 리소스