PCHANGE_BANDWIDTH_ALLOCATION callback function (hdaudio.h)
The ChangeBandwidthAllocation routine changes a DMA engine's bandwidth allocation on the HD Audio Link.
The function pointer type for a ChangeBandwidthAllocation routine is defined as follows.
Syntax
PCHANGE_BANDWIDTH_ALLOCATION PchangeBandwidthAllocation;
NTSTATUS PchangeBandwidthAllocation(
[in] PVOID _context,
[in] HANDLE Handle,
[in] PHDAUDIO_STREAM_FORMAT StreamFormat,
[out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}
Parameters
[in] _context
Specifies the context value from the Context member of the HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2, or HDAUDIO_BUS_INTERFACE_BDL structure.
[in] Handle
Handle identifying the DMA engine. This handle value was obtained from a previous call to AllocateCaptureDmaEngine or AllocateRenderDmaEngine.
[in] StreamFormat
Specifies the requested stream format. This parameter points to a caller-allocated structure of type HDAUDIO_STREAM_FORMAT that specifies a data format for the stream.
[out] ConverterFormat
Retrieves the converter format. This parameter points to a caller-allocated structure of type HDAUDIO_CONVERTER_FORMAT into which the routine writes the encoded format. For more information, see the following Remarks section.
Return value
ChangeBandwidthAllocation returns STATUS_SUCCESS if the call succeeds. Otherwise, the routine returns an appropriate error code. The following table shows some of the possible return error codes.
| Return code | Description |
|---|---|
|
Indicates that the caller is running at an IRQL that is too high. |
|
Indicates that the handle parameter value is invalid. |
|
Indicates that one of the parameter values is not correct (bad pointer or invalid stream format). |
|
Indicates that the DMA engine is unable to allocate sufficient internal FIFO storage to support the requested stream format. |
|
Indicates that insufficient bandwidth is available to satisfy the request. |
|
Indicates that the stream is not in the reset state or that a buffer is still allocated for the DMA engine. |
Remarks
The caller obtains an initial bandwidth allocation for a DMA engine by calling AllocateCaptureDmaEngine or AllocateRenderDmaEngine. Thereafter, the caller can change the bandwidth allocation by calling ChangeBandwidthAllocation.
Through the converterFormat parameter, the routine outputs a stream descriptor value that the caller can use to program the input or output converters. The routine encodes the information from the streamFormat parameter into a 16-bit integer. For more information, see HDAUDIO_CONVERTER_FORMAT.
This routine fails and returns error code STATUS_INVALID_DEVICE_REQUEST in either of the following circumstances:
- Any previously allocated DMA buffer has not been freed (by calling FreeDmaBuffer or FreeContiguousDmaBuffer).
- The stream is in a state other than reset.
ChangeBandwidthAllocation call fails, the existing bandwidth reservation remains in effect. The bandwidth allocation changes only if the call succeeds.
In Windows Vista and later, a wave miniport driver calls this routine during execution of its SetFormat method (after calling one of the AllocateXxxDmaEngine routines in the HD Audio DDI). For more information, see IMiniportWavePciStream::SetFormat.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | hdaudio.h (include Hdaudio.h) |
| IRQL | PASSIVE_LEVEL |