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

Artículo
07/27/2023

La rutina TransferCodecVerbs transfiere uno o varios comandos a un códec o códecs y recupera las respuestas a esos comandos.

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

Sintaxis

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 el valor de contexto del miembro Context de la estructura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2 o HDAUDIO_BUS_INTERFACE_BDL.

[in] Count

Especifica el número de elementos de la matriz codecTransfer .

[in, out] CodecTransfer

Puntero a una matriz de estructuras de HDAUDIO_CODEC_TRANSFER . Cada elemento de matriz es una estructura que contiene almacenamiento para un comando de salida del autor de la llamada y la respuesta de entrada correspondiente del códec.

[in] Callback

Puntero de función a una rutina de devolución de llamada. Este parámetro es un puntero de función de tipo HDAUDIO_TRANSFER_COMPLETE_CALLBACK. El parámetro se puede especificar como NULL. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in] Context

Valor de contexto para la rutina de devolución de llamada. El autor de la llamada convierte el valor de contexto en el tipo PVOID. Después de completar los comandos de forma asincrónica, el controlador de hd Audio bus pasa el valor de contexto a la rutina de devolución de llamada como parámetro de llamada.

Valor devuelto

TransferCodecVerbs 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 muestra un posible código de estado de retorno.

Código devuelto	Descripción
STATUS_NO_MEMORY	Indica que la solicitud no se pudo agregar a la cola de comandos debido a una escasez de memoria no paginada.

Comentarios

Esta rutina envía uno o varios comandos de códec al controlador del bus de audio hd. El controlador de bus emite los comandos a los códecs, recupera las respuestas de los códecs a los comandos y genera las respuestas al autor de la llamada.

El autor de la llamada especifica los comandos de una matriz de estructuras de HDAUDIO_CODEC_TRANSFER. Cada estructura contiene almacenamiento para un comando y la respuesta del códec a ese comando. Antes de llamar a TransferCodecVerbs, el autor de la llamada rellena los comandos de cada una de las estructuras de la matriz. A medida que se completa cada comando, el controlador hd Audio bus recupera la respuesta del códec y la escribe en la estructura. Una vez completado el último comando, el autor de la llamada puede leer las respuestas de la matriz.

La rutina puede funcionar de forma sincrónica o asincrónica:

Si el autor de la llamada especifica NULL para el valor de devolución de llamada del parámetro de entrada, el controlador del bus de audio HD completa los comandos de la matriz codecTransfer de forma sincrónica. (Es decir, la rutina solo devuelve después de que los códecs hayan procesado todos los comandos y las respuestas a esos comandos estén disponibles).
Si el autor de la llamada especifica un valor distinto de NULL para el parámetro de devolución de llamada , la rutina funciona de forma asincrónica. (Es decir, la rutina vuelve inmediatamente después de agregar los comandos a su cola interna sin esperar a que los códecs procesen todos los comandos). Después de que los códecs procesen los comandos, el controlador de HD Audio bus llama a la rutina de devolución de llamada. En el caso asincrónico, el autor de la llamada no debe intentar leer las respuestas a los comandos antes de que el controlador de bus llame a la rutina de devolución de llamada.

El tipo de puntero de función para el parámetro de devolución de llamada se define como:

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

El primer parámetro de llamada es un puntero al elemento de matriz codecTransfer que contiene el comando codec y la respuesta que desencadenó la devolución de llamada. El segundo parámetro de llamada es el mismo valor de contexto que se especificó anteriormente en el parámetro callbackContext de la rutina TransferCodecVerbs.

Si se ejecuta correctamente, TransferCodecVerbs devuelve STATUS_SUCCESS. El significado de este código de estado depende de si la rutina funciona de forma sincrónica o asincrónica:

En el caso sincrónico (la devolución de llamada es NULL), STATUS_SUCCESS significa que el controlador de bus tiene todos los comandos de la matriz codecTransfer en los códecs y que la rutina ha escrito todas las respuestas a esos comandos en la matriz. Sin embargo, el autor de la llamada debe comprobar las respuestas individuales para determinar si son válidas. Las respuestas individuales podrían no ser válidas debido a tiempos de espera de códec o a la saturación de FIFO.
En el caso asincrónico (la devolución de llamada no es NULL), STATUS_SUCCESS significa que la rutina ha agregado correctamente los comandos a la cola interna del controlador de HD Audio Bus. El autor de la llamada no debe intentar leer las respuestas a esos comandos hasta que el controlador de bus llame a la rutina de devolución de llamada.

Si una respuesta no es válida debido a una saturación de FIFO, la causa probable es que el códec respondió al comando, pero la respuesta se perdió debido a un búfer de anillo de entrada de respuesta (RIRB) de tamaño insuficiente. Si una saturación de FIFO no es la causa de la respuesta no válida, es probable que se produzca el error porque el códec no respondió a tiempo (se agotó el tiempo de espera). En este caso, el autor de la llamada puede suponer que el comando no alcanzó el códec.

Si el parámetro de devolución de llamada es NULL, el llamador debe ejecutarse en IRQL PASSIVE_LEVEL. Si la devolución de llamada no es NULL, el autor de la llamada puede llamar a TransferCodecVerbs en IRQL <= DISPATCH_LEVEL, en cuyo caso la llamada se devuelve inmediatamente sin esperar a que los códecs procesen todos los comandos; una vez completados los comandos, el controlador de HD Audio bus llama a la rutina de devolución de llamada en IRQL DISPATCH_LEVEL.

El autor de la llamada debe asignar la matriz codecTransfer del grupo no paginado.