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

Artigo
07/27/2023

A rotina TransferCodecVerbs 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 membro Context da estrutura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2ouHDAUDIO_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.

Retornar valor

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 retorno status código.

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.

Comentários

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 ao 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 retorno de chamada do parâmetro de entrada, o driver do barramento de áudio HD concluirá os comandos na matriz codecTransfer 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 não NULL 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 aos 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 de matriz codecTransfer 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 callbackContext da rotina TransferCodecVerbs.

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

No caso síncrono (o retorno de chamada é NULL), STATUS_SUCCESS significa que o driver de 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 marcar 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 estouro de FIFO.
No caso assíncrono (o retorno de chamada não é NULL), STATUS_SUCCESS significa apenas que a rotina adicionou com êxito os comandos à fila interna do driver de 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 um estouro 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 de tamanho insuficiente (RIRB). Se uma sobrecarga 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 IRQL PASSIVE_LEVEL. Se o retorno de chamada não for NULL, o chamador poderá chamar TransferCodecVerbs em IRQL <= DISPATCH_LEVEL, nesse caso, a chamada retornará imediatamente sem esperar que os codecs processem todos os comandos; depois que os comandos forem concluídos, o driver do barramento de áudio HD chamará a rotina de retorno de chamada no IRQL DISPATCH_LEVEL.

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