PCHANGE_BANDWIDTH_ALLOCATION función de devolución de llamada (hdaudio.h)

Artículo
08/07/2023

La ChangeBandwidthAllocation rutina cambia la asignación de ancho de banda de un motor DMA en HD Audio Link.

El tipo de puntero de función para una ChangeBandwidthAllocation rutina se define de la siguiente manera.

Sintaxis

PCHANGE_BANDWIDTH_ALLOCATION PchangeBandwidthAllocation;

NTSTATUS PchangeBandwidthAllocation(
  [in]  PVOID _context,
  [in]  HANDLE Handle,
  [in]  PHDAUDIO_STREAM_FORMAT StreamFormat,
  [out] PHDAUDIO_CONVERTER_FORMAT ConverterFormat
)
{...}

Parámetros

[in] _context

Especifica el valor de contexto del miembro Context de la estructura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 o HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Controle la identificación del motor DMA. Este valor de identificador se obtuvo de una llamada anterior a AllocateCaptureDmaEngine o AllocateRenderDmaEngine.

[in] StreamFormat

Especifica el formato de secuencia solicitado. Este parámetro apunta a una estructura asignada por el autor de la llamada de tipo HDAUDIO_STREAM_FORMAT que especifica un formato de datos para la secuencia.

[out] ConverterFormat

Recupera el formato del convertidor. Este parámetro apunta a una estructura asignada por el autor de la llamada de tipo HDAUDIO_CONVERTER_FORMAT en la que la rutina escribe el formato codificado. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

ChangeBandwidthAllocation devuelve STATUS_SUCCESS si la llamada se realiza correctamente. De lo contrario, la rutina devuelve un código de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de error de retorno.

Código devuelto	Descripción
STATUS_UNSUCCESSFUL	Indica que el autor de la llamada se está ejecutando en un IRQL que es demasiado alto.
STATUS_INVALID_HANDLE	Indica que el valor del parámetro handle no es válido.
STATUS_INVALID_PARAMETER	Indica que uno de los valores de parámetro no es correcto (puntero incorrecto o formato de secuencia no válido).
STATUS_BUFFER_TOO_SMALL	Indica que el motor DMA no puede asignar suficiente almacenamiento FIFO interno para admitir el formato de secuencia solicitado.
STATUS_INSUFFICIENT_RESOURCES	Indica que el ancho de banda insuficiente está disponible para satisfacer la solicitud.
STATUS_INVALID_DEVICE_REQUEST	Indica que la secuencia no está en el estado de restablecimiento o que un búfer todavía está asignado para el motor DMA.

Comentarios

El autor de la llamada obtiene una asignación de ancho de banda inicial para un motor DMA mediante una llamada a AllocateCaptureDmaEngine o AllocateRenderDmaEngine. A partir de entonces, el autor de la llamada puede cambiar la asignación de ancho de banda mediante una llamada a ChangeBandwidthAllocation.

A través del parámetro converterFormat , la rutina genera un valor de descriptor de flujo que el autor de la llamada puede usar para programar los convertidores de entrada o salida. La rutina codifica la información del parámetro streamFormat en un entero de 16 bits. Para obtener más información, consulte HDAUDIO_CONVERTER_FORMAT.

Esta rutina produce un error y devuelve el código de error STATUS_INVALID_DEVICE_REQUEST en cualquiera de las siguientes circunstancias:

No se ha liberado ningún búfer DMA asignado previamente (llamando a FreeDmaBuffer o FreeContiguousDmaBuffer).
La secuencia está en un estado distinto del restablecimiento.

Si se produce un error en la ChangeBandwidthAllocation llamada, la reserva de ancho de banda existente permanece en vigor. La asignación de ancho de banda solo cambia si la llamada se realiza correctamente.

En Windows Vista y versiones posteriores, un controlador de minipuerto de onda llama a esta rutina durante la ejecución de su método SetFormat (después de llamar a una de las rutinas AllocateXxxDmaEngine en hd Audio DDI). Para obtener más información, vea IMiniportWavePciStream::SetFormat.