PCHANGE_BANDWIDTH_ALLOCATION コールバック関数 (hdaudio.h)

[アーティクル]
02/29/2024

このルーチンは ChangeBandwidthAllocation 、HD Audio Link での DMA エンジンの帯域幅割り当てを変更します。

ルーチンの関数ポインター型 ChangeBandwidthAllocation は、次のように定義されます。

構文

PCHANGE_BANDWIDTH_ALLOCATION PchangeBandwidthAllocation;

NTSTATUS PchangeBandwidthAllocation(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

パラメーター

[in] _context

HDAUDIO_BUS_INTERFACE、HDAUDIO_BUS_INTERFACE_V2、または HDAUDIO_BUS_INTERFACE_BDL 構造体の Context メンバーのコンテキスト値を指定します。

[in] Handle

DMA エンジンを識別するハンドル。このハンドル値は、 AllocateCaptureDmaEngine または AllocateRenderDmaEngine の以前の呼び出しから取得されました。

[in] StreamFormat

要求されたストリーム形式を指定します。このパラメーターは、ストリームのデータ形式を指定する HDAUDIO_STREAM_FORMAT 型の呼び出し元によって割り当てられた構造体を指します。

[out] ConverterFormat

コンバーター形式を取得します。このパラメーターは、ルーチンがエンコードされた形式を書き込む HDAUDIO_CONVERTER_FORMAT 型の呼び出し元によって割り当てられた構造体を指します。詳細については、「解説」を参照してください。

戻り値

ChangeBandwidthAllocation は、呼び出しが成功した場合は STATUS_SUCCESS を返します。それ以外の場合、ルーチンは適切なエラーコードを返します。次の表は、考えられるリターンエラーコードの一部を示しています。

リターンコード	説明
STATUS_UNSUCCESSFUL	呼び出し元が高すぎる IRQL で実行されていることを示します。
STATUS_INVALID_HANDLE	ハンドルパラメーターの値が無効であることを示します。
STATUS_INVALID_PARAMETER	パラメーター値の 1 つが正しくないことを示します (ポインターが正しくないか、ストリーム形式が無効です)。
STATUS_BUFFER_TOO_SMALL	DMA エンジンが、要求されたストリーム形式をサポートするのに十分な内部 FIFO ストレージを割り当てることができないことを示します。
STATUS_INSUFFICIENT_RESOURCES	要求を満たすために使用できる帯域幅が不足していることを示します。
STATUS_INVALID_DEVICE_REQUEST	ストリームがリセット状態ではないこと、または DMA エンジンにバッファーがまだ割り当てられていることを示します。

注釈

呼び出し元は、 AllocateCaptureDmaEngine または AllocateRenderDmaEngine を呼び出すことによって、DMA エンジンの初期帯域幅割り当てを取得します。その後、呼び出し元はを呼び出 ChangeBandwidthAllocationすことによって帯域幅の割り当てを変更できます。

converterFormat パラメーターを使用して、ルーチンは、呼び出し元が入力コンバーターまたは出力コンバーターをプログラムするために使用できるストリーム記述子値を出力します。このルーチンは、 streamFormat パラメーターの情報を 16 ビット整数にエンコードします。詳細については、「 HDAUDIO_CONVERTER_FORMAT」を参照してください。

このルーチンは失敗し、次のいずれかの状況でSTATUS_INVALID_DEVICE_REQUESTエラーコードを返します。

以前に割り当てられた DMA バッファーが解放されていません ( FreeDmaBuffer または FreeContiguousDmaBuffer を呼び出すことによって)。
ストリームがリセット以外の状態です。

呼び出しが ChangeBandwidthAllocation 失敗した場合、既存の帯域幅予約は引き続き有効です。帯域幅の割り当ては、呼び出しが成功した場合にのみ変更されます。

Windows Vista 以降では、ウェーブミニポートドライバーは 、SetFormat メソッドの実行中にこのルーチンを呼び出します (HD オーディオ DDI でXxxDmaEngine の割り当てルーチンのいずれかを呼び出した後)。詳細については、「 IMiniportWavePciStream::SetFormat」を参照してください。