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

Artigo
03/08/2024

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

O tipo de ponteiro de função para uma ChangeBandwidthAllocation rotina é 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 membro Context da estrutura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 ou HDAUDIO_BUS_INTERFACE_BDL .

[in] Handle

Manipule a identificação do mecanismo de AMD. 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 pelo 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 pelo 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.

Retornar valor

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 muito alto.
STATUS_INVALID_HANDLE	Indica que o valor do parâmetro handle é inválido.
STATUS_INVALID_PARAMETER	Indica que um dos valores de parâmetro não está correto (ponteiro inválido ou formato de fluxo inválido).
STATUS_BUFFER_TOO_SMALL	Indica que o mecanismo de DMA não pode 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.

Comentários

O chamador obtém uma alocação de largura de banda inicial para um mecanismo de 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 AMD alocado anteriormente não foi liberado (chamando FreeDmaBuffer ou FreeContiguousDmaBuffer).
O fluxo está em um estado diferente de redefinir.

Se a ChangeBandwidthAllocation chamada 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 AllocateXxxDmaEngine na DDI de áudio HD). Para obter mais informações, consulte IMiniportWavePciStream::SetFormat.