IAudioClient::IsFormatSupported メソッド (audioclient.h)

  • [アーティクル]

IsFormatSupported メソッドは、オーディオ エンドポイント デバイスが特定のストリーム形式をサポートしているかどうかを示します。

構文

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

パラメーター

[in] ShareMode

ストリーム形式の共有モード。 このパラメーターを使用すると、クライアントは、指定した形式を排他モードまたは共有モードで使用するかどうかを示します。 クライアントは、このパラメーターを次のいずれかのAUDCLNT_SHAREMODE列挙値 に 設定する必要があります。

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

指定したストリーム形式へのポインター。 このパラメーターは、 WAVEFORMATEX 型または WAVEFORMATEXTENSIBLE 型の呼び出し元によって割り当てられたフォーマット記述子を指します。 クライアントは、このメソッドを呼び出す前に、この構造体に書式の説明を書き込みます。 WAVEFORMATEX と WAVEFORMATEXTENSIBLE の詳細については、Windows DDK のドキュメントを参照してください。

[out] ppClosestMatch

メソッドが WAVEFORMATEX または WAVEFORMATEXTENSIBLE 構造体のアドレスを書き込むポインター変数へのポインター。 この構造体は、 クライアントが pFormat パラメーターで指定した形式に最も近い、サポートされている形式を指定します。 共有モードの場合 (つまり、 ShareMode パラメーターがAUDCLNT_SHAREMODE_SHAREDの場合)、有効な NULL 以外のポインター変数を指すように ppClosestMatchを 設定します。 排他モードの場合は、 ppClosestMatch を NULL に設定 します。 メソッドは、 構造体にストレージを割り当てます。 呼び出し元は、不要になったときに CoTaskMemFree 関数を呼び出すことによって、ストレージを解放する役割を担います。 IsFormatSupported 呼び出しが失敗し、ppClosestMatch が NULL 以外の場合、メソッドは *ppClosestMatch を NULL に設定します。 CoTaskMemFree の詳細については、Windows SDK のドキュメントを参照してください。

戻り値

リターン コード 説明
S_OK
 成功し、オーディオ エンドポイント デバイスで指定されたストリーム形式がサポートされます。
S_FALSE
 指定した形式に最も近い一致で成功しました。
AUDCLNT_E_UNSUPPORTED_FORMAT
 成功しましたが、指定された形式は排他モードではサポートされていません。
 

操作が失敗した場合、次の表に示す値が、可能なリターン コードに含まれますが、これらに限定されません。

リターン コード 説明
E_POINTER
 パラメーター pFormat が NULL であるか、 ppClosestMatch が NULL で ShareMode がAUDCLNT_SHAREMODE_SHARED。
E_INVALIDARG
 パラメーター ShareMode は、AUDCLNT_SHAREMODE_SHAREDまたはAUDCLNT_SHAREMODE_EXCLUSIVE以外の値です。
AUDCLNT_E_DEVICE_INVALIDATED
 オーディオ エンドポイント デバイスが取り外されているか、オーディオ ハードウェアまたは関連するハードウェア リソースが再構成、無効、削除、またはその他の方法で使用できなくなります。
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows オーディオ サービスが実行されていません。

注釈

このメソッドは、 クライアントが IAudioClient::Initialize を呼び出す前に、オーディオ エンジンが特定のストリーム形式をサポートしているかどうかを判断する方法を提供します。

排他モードの場合、 IsFormatSupported は 、オーディオ エンドポイント デバイスが呼び出し元指定の形式をサポートしている場合はS_OKを返し、デバイスが形式をサポートしていない場合はAUDCLNT_E_UNSUPPORTED_FORMATを返します。 ppClosestMatch パラメーターには NULL を指定できます。 NULL でない場合、メソッドは NULL を*ppClosestMatch に書き込みます。

共有モードの場合、オーディオ エンジンが呼び出し元指定の形式をサポートしている場合、 IsFormatSupportedは *ppClosestMatch を NULL に設定し、S_OKを返します。 オーディオ エンジンが呼び出し元指定の形式をサポートしていないが、同様の形式をサポートしている場合、メソッドは ppClosestMatch パラメーターを使用して同様の形式を取得し、S_FALSEを返します。 オーディオ エンジンが呼び出し元指定の形式または同様の形式をサポートしていない場合、メソッド は *ppClosestMatch を NULL に設定し、AUDCLNT_E_UNSUPPORTED_FORMATを返します。

共有モードでは、オーディオ エンジンは常にミックス形式をサポートします。この形式は、 クライアントが IAudioClient::GetMixFormat メソッドを呼び出すことによって取得できます。 さらに、オーディオ エンジンは、ミックス形式と同じサンプル レートとチャネル数を持つが、オーディオ サンプル値の表現が異なる同様の形式をサポートする場合があります。 オーディオ エンジンは内部的にサンプル値を浮動小数点数として表しますが、呼び出し元が指定した形式でサンプル値を整数として表す場合、オーディオ エンジンは通常、整数のサンプル値とその内部浮動小数点表現の間で変換できます。

オーディオ デバイスのインストール パッケージに、フォーマット変換を処理できるローカル エフェクト (LFX) オーディオ処理オブジェクト (APO) が含まれている場合、オーディオ エンジンは、さらに広い範囲の共有モード形式をサポートできる場合があります。 LFX APO は、オーディオ ストリームのデバイス固有の処理を実行するソフトウェア モジュールです。 Windows オーディオ サービスのオーディオ グラフ ビルダーは、各クライアントとオーディオ エンジンの間のストリームに LFX APO を挿入します。 クライアントが IsFormatSupported メソッドを呼び出し、デバイスで使用するために LFX APO がインストールされているとメソッドが判断すると、メソッドは、呼び出し元が指定した形式をサポートしているかどうかを示す LFX APO にクエリを送信します。

たとえば、特定の LFX APO では、クライアントから 6 チャネルのサラウンド サウンド ストリームを受け入れ、ストリームをヘッドフォンで再生できるステレオ形式に変換できます。 通常、LFX APO では、ミックス形式のサンプル レートと一致するサンプル レートを持つクライアント形式のみがサポートされます。

API の詳細については、「 Windows オーディオ処理オブジェクト」を参照してください。 IsFormatSupported メソッドの詳細については、「デバイス形式」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー audioclient.h

こちらもご覧ください

IAudioClient インターフェイス

IAudioClient::GetMixFormat

IAudioClient::Initialize