PCHANGE_BANDWIDTH_ALLOCATION função de retorno de chamada (hdaudio.h)

Artigo
02/07/2025

A rotina de ChangeBandwidthAllocation altera a alocação de largura de banda de um mecanismo DMA no Link de Áudio HD.

O tipo de ponteiro de função para uma rotina de ChangeBandwidthAllocation é definido da seguinte maneira.

Sintaxe

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 o valor de contexto do de contexto membro da estrutura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2ou HDAUDIO_BUS_INTERFACE_BDL.

[in] Handle

Manipule a identificação do mecanismo de DMA. Esse valor de identificador foi obtido de uma chamada anterior para AllocateCaptureDmaEngine ou AllocateRenderDmaEngine.

[in] StreamFormat

Especifica o formato de fluxo solicitado. Esse parâmetro aponta para uma estrutura alocada por chamador do tipo HDAUDIO_STREAM_FORMAT que especifica um formato de dados para o fluxo.

[out] ConverterFormat

Recupera o formato do conversor. Esse parâmetro aponta para uma estrutura alocada por chamador do tipo HDAUDIO_CONVERTER_FORMAT na qual a rotina grava o formato codificado. Para obter mais informações, consulte a seção Comentários a seguir.

Valor de retorno

ChangeBandwidthAllocation retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, a rotina retornará um código de erro apropriado. A tabela a seguir mostra alguns dos possíveis códigos de erro de retorno.

Código de retorno	Descrição
STATUS_UNSUCCESSFUL	Indica que o chamador está em execução em um IRQL que é muito alto.
STATUS_INVALID_HANDLE	Indica que o identificador valor do parâmetro é inválido.
STATUS_INVALID_PARAMETER	Indica que um dos valores de parâmetro não está correto (ponteiro incorreto ou formato de fluxo inválido).
STATUS_BUFFER_TOO_SMALL	Indica que o mecanismo de DMA não consegue alocar armazenamento fifo interno suficiente para dar suporte ao formato de fluxo solicitado.
STATUS_INSUFFICIENT_RESOURCES	Indica que a largura de banda insuficiente está disponível para atender à solicitação.
STATUS_INVALID_DEVICE_REQUEST	Indica que o fluxo não está no estado de redefinição ou que um buffer ainda está alocado para o mecanismo de DMA.

Observações

O chamador obtém uma alocação inicial de largura de banda para um mecanismo DMA chamando AllocateCaptureDmaEngine ou AllocateRenderDmaEngine. Depois disso, o chamador pode alterar a alocação de largura de banda chamando ChangeBandwidthAllocation.

Por meio do parâmetro converterFormat, a rotina gera um valor de descritor de fluxo que o chamador pode usar para programar os conversores de entrada ou saída. A rotina codifica as informações do parâmetro streamFormat em um inteiro de 16 bits. Para obter mais informações, consulte HDAUDIO_CONVERTER_FORMAT.

Essa rotina falha e retorna o código de erro STATUS_INVALID_DEVICE_REQUEST em qualquer uma das seguintes circunstâncias:

Nenhum buffer de DMA alocado anteriormente não foi liberado (chamando FreeDmaBuffer ou FreeContiguousDmaBuffer).
O fluxo está em um estado diferente de redefinição.

Se a chamada ChangeBandwidthAllocation falhar, a reserva de largura de banda existente permanecerá em vigor. A alocação de largura de banda será alterada somente se a chamada for bem-sucedida.

No Windows Vista e posterior, um driver de miniporto de onda chama essa rotina durante a execução de seu método SetFormat (depois de chamar uma das rotinas do DmaEngineXxxno DDI de Áudio HD). Para obter mais informações, consulte IMiniportWavePciStream::SetFormat.