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

Artigo
02/07/2025

O TransferCodecVerbs a rotina transfere um ou mais comandos para um codec ou codecs e recupera as respostas a esses comandos.

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

Sintaxe

PTRANSFER_CODEC_VERBS PtransferCodecVerbs;

NTSTATUS PtransferCodecVerbs(
  [in]      PVOID _context,
  [in]      ULONG Count,
  [in, out] PHDAUDIO_CODEC_TRANSFER CodecTransfer,
  [in]      PHDAUDIO_TRANSFER_COMPLETE_CALLBACK Callback,
  [in]      PVOID Context
)
{...}

Parâmetros

[in] _context

Especifica o valor de contexto do de contexto membro da estrutura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2, ou HDAUDIO_BUS_INTERFACE_BDL.

[in] Count

Especifica o número de elementos na matriz codecTransfer.

[in, out] CodecTransfer

Ponteiro para uma matriz de estruturas de HDAUDIO_CODEC_TRANSFER. Cada elemento de matriz é uma estrutura que contém armazenamento para um comando de saída do chamador e a resposta de entrada correspondente do codec.

[in] Callback

Ponteiro de função para uma rotina de retorno de chamada. Esse parâmetro é um ponteiro de função do tipo HDAUDIO_TRANSFER_COMPLETE_CALLBACK. O parâmetro pode ser especificado como NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in] Context

Um valor de contexto para a rotina de retorno de chamada. O chamador converte o valor de contexto para digitar PVOID. Depois de concluir os comandos de forma assíncrona, o driver do barramento de áudio HD passa o valor de contexto para a rotina de retorno de chamada como um parâmetro de chamada.

Valor de retorno

TransferCodecVerbs 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 um possível código de status de retorno.

Código de retorno	Descrição
STATUS_NO_MEMORY	Indica que a solicitação não pôde ser adicionada à fila de comandos devido à falta de memória não paga.

Observações

Essa rotina envia um ou mais comandos codec para o driver do barramento de áudio HD. O driver de barramento emite os comandos para os codecs, recupera as respostas dos codecs para os comandos e gera as respostas para o chamador.

O chamador especifica os comandos em uma matriz de estruturas de HDAUDIO_CODEC_TRANSFER. Cada estrutura contém armazenamento para um comando e a resposta do codec a esse comando. Antes de chamar TransferCodecVerbs, o chamador preenche os comandos em cada uma das estruturas na matriz. À medida que cada comando é concluído, o driver do barramento de áudio HD recupera a resposta do codec e a grava na estrutura. Depois que o último comando for concluído, o chamador poderá ler as respostas da matriz.

A rotina pode operar de forma síncrona ou assíncrona:

Se o chamador especificar NULL para o valor do parâmetro de entrada de retorno de chamada, o driver do barramento de áudio HD concluirá os comandos no codecTransfer matriz de forma síncrona. (Em outras palavras, a rotina retorna somente depois que os codecs processarem todos os comandos e as respostas a esses comandos estiverem disponíveis.)
Se o chamador especificar um valor deNULL não para o parâmetro de retorno de chamada, a rotina funcionará de forma assíncrona. (Em outras palavras, a rotina retorna imediatamente após adicionar os comandos à sua fila interna sem esperar que os codecs processem todos os comandos.) Depois que os codecs processam os comandos, o motorista do barramento de áudio HD chama a rotina de retorno de chamada. No caso assíncrono, o chamador não deve tentar ler as respostas para os comandos antes que o motorista do ônibus chame a rotina de retorno de chamada.

O tipo de ponteiro de função para o parâmetro de retorno de chamada é definido como:

typedef VOID
  (*PHDAUDIO_TRANSFER_COMPLETE_CALLBACK)
    (HDAUDIO_CODEC_TRANSFER *, PVOID);

O primeiro parâmetro de chamada é um ponteiro para o elemento codecTransfer matriz que contém o comando codec e a resposta que disparou o retorno de chamada. O segundo parâmetro de chamada é o mesmo valor de contexto especificado anteriormente no parâmetro TransferCodecVerbs.

Se bem-sucedido, TransferCodecVerbs retornará STATUS_SUCCESS. O significado desse código de status depende se a rotina opera de forma síncrona ou assíncrona:

No caso síncrono ( de retorno de chamada é NULL), STATUS_SUCCESS significa que o motorista do barramento tem todos os comandos na matriz codecTransfer para os codecs e que a rotina gravou todas as respostas a esses comandos na matriz. No entanto, o chamador deve verificar as respostas individuais para determinar se elas são válidas. As respostas individuais podem ser inválidas devido a tempos limite de codec ou sobrecarga de FIFO.
No caso assíncrono ( de retorno de chamada não éNULL), STATUS_SUCCESS significa apenas que a rotina adicionou com êxito os comandos à fila interna do driver do barramento de áudio HD. O chamador não deve tentar ler as respostas para esses comandos até que o motorista do ônibus chame a rotina de retorno de chamada.

Se uma resposta for inválida devido a uma sobrecarga de FIFO, a causa provável é que o codec respondeu ao comando, mas a resposta foi perdida devido a um buffer de anel de entrada de resposta insuficientemente dimensionado (RIRB). Se uma sobrecarga de FIFO não for a causa da resposta inválida, a falha provavelmente ocorreu porque o codec não respondeu a tempo (tempo limite). Nesse caso, o chamador pode assumir que o comando não atingiu o codec.

Se o parâmetro de retorno de chamada for NULL, o chamador deverá estar em execução no PASSIVE_LEVEL IRQL. Se de retorno de chamada não forNULL, o chamador poderá chamar TransferCodecVerbs no IRQL <= DISPATCH_LEVEL, nesse caso, a chamada retornará imediatamente sem esperar que os codecs processem todos os comandos; após a conclusão dos comandos, o motorista do barramento de áudio HD chama a rotina de retorno de chamada no DISPATCH_LEVEL IRQL.

O chamador deve alocar a matriz codecTransfer do pool nãopagado.