acmFormatEnum 関数 (msacm.h)

  • [アーティクル]

acmFormatEnum 関数は、ACM ドライバーから特定のフォーマット タグで使用できる波形オーディオ形式を列挙します。 この関数は、書式タグに適した形式がなくなったか、コールバック関数が FALSE を返すまで列挙を続けます。

構文

MMRESULT ACMAPI acmFormatEnum(
  HACMDRIVER         had,
  LPACMFORMATDETAILS pafd,
  ACMFORMATENUMCB    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;
}

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー msacm.h
Library Msacm32.lib
[DLL] Msacm32.dll

関連項目

オーディオ圧縮関数

オーディオ圧縮マネージャー