PCHANGE_BANDWIDTH_ALLOCATION回调函数 (hdaudio.h)

项目
02/26/2024

该 ChangeBandwidthAllocation 例程更改 DMA 引擎在 HD 音频链路上的带宽分配。

例程的 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	指示其中一个参数值不正确， (指针错误或流格式) 无效。
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) 中的一个 AllocateXxxDmaEngine 例程。有关详细信息，请参阅 IMiniportWavePciStream：：SetFormat。