acmFormatEnumA 関数 (msacm.h)

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	列挙子は、インストールされている 1 つ以上の波形オーディオ デバイスでネイティブの入力または出力形式としてサポートされている形式のみを列挙する必要があります。 このフラグは、アプリケーションがインストールされている波形オーディオ デバイスにネイティブな形式のみを選択する方法を提供します。 このフラグは、ACM_FORMATENUMF_INPUTフラグとACM_FORMATENUMF_OUTPUTフラグの一方または両方で使用する必要があります。 ACM_FORMATENUMF_INPUTとACM_FORMATENUMF_OUTPUTの両方を指定すると、入力または出力用に開くことができる形式のみが列挙されます。 これは、このフラグが指定されているかどうかに関係なく当てはまります。
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	少なくとも 1 つのフラグが無効です。
MMSYSERR_INVALHANDLE	指定されたハンドルが無効です。
MMSYSERR_INVALPARAM	少なくとも 1 つのパラメーターが無効です。

備考

この関数は、適切な ACM ドライバーがインストールされていない場合、MMSYSERR_NOERROR (ゼロ) を返します。 さらに、コールバック関数は呼び出されません。

例

次の例は、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;
}

次の例は、前の例のコールバック関数を示しています。 コールバック関数は、一致する形式ごとに 1 回呼び出されるか、コールバックから 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 ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして acmFormatEnum を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000 Professional [デスクトップ アプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップ アプリのみ]
ターゲット プラットフォーム の	ウィンドウズ
ヘッダー	msacm.h
ライブラリ	Msacm32.lib
DLL	Msacm32.dll

関連項目

オーディオ圧縮機能 を する

Audio Compression Manager