PCHANGE_BANDWIDTH_ALLOCATION回呼函式（hdaudio.h）

發行項
02/07/2025

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。