PCHANGE_BANDWIDTH_ALLOCATION回调函数（hdaudio.h）

项目
02/07/2025

ChangeBandwidthAllocation 例程更改 HD 音频链接上的 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 结构的 上下文 成员的上下文值。

[in] Handle

标识 DMA 引擎的句柄。此句柄值是从上一次调用 <AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine中获取的。

[in] StreamFormat

指定请求的流格式。此参数指向类型为 HDAUDIO_STREAM_FORMAT 的调用方分配的结构，该结构指定流的数据格式。

[out] ConverterFormat

检索转换器格式。此参数指向调用方分配的 HDAUDIO_CONVERTER_FORMAT 结构，例程将编码格式写入其中。有关详细信息，请参阅以下“备注”部分。

返回值

如果调用成功，则 ChangeBandwidthAllocation 返回STATUS_SUCCESS。否则，例程将返回适当的错误代码。下表显示了一些可能的返回错误代码。

返回代码	描述
STATUS_UNSUCCESSFUL	指示调用方在 IRQL 上运行，该 IRQL 太高。
STATUS_INVALID_HANDLE	指示句柄参数值无效。
STATUS_INVALID_PARAMETER	指示其中一个参数值不正确（指针错误或流格式无效）。
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 Audio DDI 中的分配XxxDmaEngine 例程之一后）调用此例程。有关详细信息，请参阅 IMiniportWavePciStream：：SetFormat。