PCHANGE_BANDWIDTH_ALLOCATION回呼函式 (hdaudio.h)

發行項
03/01/2024

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 結構之Context成員的內容值。

[in] Handle

處理識別 DMA 引擎。這個句柄值是從先前呼叫 AllocateCaptureDmaEngine 或 AllocateRenderDmaEngine 取得。

[in] StreamFormat

指定要求的數據流格式。此參數指向類型為呼叫端配置的結構，HDAUDIO_STREAM_FORMAT 指定數據流的數據格式。

[out] ConverterFormat

擷取轉換器格式。此參數指向呼叫端配置的型別結構，HDAUDIO_CONVERTER_FORMAT 例程寫入編碼格式。如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

ChangeBandwidthAllocation 如果呼叫成功，則會傳回STATUS_SUCCESS。否則，例程會傳回適當的錯誤碼。下表顯示一些可能的傳回錯誤碼。

傳回碼	Description
STATUS_UNSUCCESSFUL	表示呼叫端在太高 IRQL 上執行。
STATUS_INVALID_HANDLE	表示 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。