PTRANSFER_CODEC_VERBS fonction de rappel (hdaudio.h)

Article
02/26/2024

La routine TransferCodecVerbs transfère une ou plusieurs commandes vers un codec ou des codecs et récupère les réponses à ces commandes.

Le type de pointeur de fonction pour une routine TransferCodecVerbs est défini comme suit.

Syntaxe

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
)
{...}

Paramètres

[in] _context

Spécifie la valeur de contexte du membre Context de la structure HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2ouHDAUDIO_BUS_INTERFACE_BDL.

[in] Count

Spécifie le nombre d’éléments dans le tableau codecTransfer .

[in, out] CodecTransfer

Pointeur vers un tableau de structures HDAUDIO_CODEC_TRANSFER . Chaque élément de tableau est une structure qui contient le stockage d’une commande de sortie de l’appelant et la réponse d’entrée correspondante du codec.

[in] Callback

Pointeur de fonction vers une routine de rappel. Ce paramètre est un pointeur de fonction de type HDAUDIO_TRANSFER_COMPLETE_CALLBACK. Le paramètre peut être spécifié comme NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in] Context

Valeur de contexte pour la routine de rappel. L’appelant caste la valeur de contexte pour qu’elle soit de type PVOID. Une fois les commandes terminées de manière asynchrone, le pilote de bus Audio HD transmet la valeur de contexte à la routine de rappel en tant que paramètre d’appel.

Valeur retournée

TransferCodecVerbs retourne STATUS_SUCCESS si l’appel réussit. Sinon, la routine retourne un code d’erreur approprié. Le tableau suivant montre un retour possible status code.

Code de retour	Description
STATUS_NO_MEMORY	Indique que la demande n’a pas pu être ajoutée à la file d’attente de commandes en raison d’une pénurie de mémoire non pagée.

Remarques

Cette routine envoie une ou plusieurs commandes de codec au pilote de bus Audio HD. Le pilote de bus envoie les commandes aux codecs, récupère les réponses des codecs aux commandes et génère les réponses à l’appelant.

L’appelant spécifie les commandes dans un tableau de structures HDAUDIO_CODEC_TRANSFER. Chaque structure contient du stockage pour une commande et la réponse du codec à cette commande. Avant d’appeler TransferCodecVerbs, l’appelant remplit les commandes de chacune des structures du tableau. À l’exécution de chaque commande, le pilote de bus Audio HD récupère la réponse du codec et l’écrit dans la structure. Une fois la dernière commande terminée, l’appelant peut lire les réponses du tableau.

La routine peut fonctionner de manière synchrone ou asynchrone :

Si l’appelant spécifie NULL pour la valeur du rappel de paramètre d’entrée, le pilote de bus Audio HD termine les commandes dans le tableau codecTransfer de manière synchrone. (En d’autres termes, la routine retourne uniquement une fois que les codecs ont traité toutes les commandes et que les réponses à ces commandes sont disponibles.)
Si l’appelant spécifie une valeur non NULL pour le paramètre de rappel , la routine fonctionne de manière asynchrone. (En d’autres termes, la routine retourne immédiatement après l’ajout des commandes à sa file d’attente interne sans attendre que les codecs traitent toutes les commandes.) Une fois que les codecs ont traité les commandes, le pilote de bus Audio HD appelle la routine de rappel. Dans le cas asynchrone, l’appelant ne doit pas tenter de lire les réponses aux commandes avant que le pilote de bus appelle la routine de rappel.

Le type de pointeur de fonction pour le paramètre de rappel est défini comme suit :

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

Le premier paramètre d’appel est un pointeur vers l’élément de tableau codecTransfer qui contient la commande de codec et la réponse qui a déclenché le rappel. Le deuxième paramètre d’appel est la même valeur de contexte que celle spécifiée précédemment dans le paramètre callbackContext de la routine TransferCodecVerbs.

En cas de réussite, TransferCodecVerbs retourne STATUS_SUCCESS. La signification de ce code status varie selon que la routine fonctionne de manière synchrone ou asynchrone :

Dans le cas synchrone (le rappel a la valeur NULL), STATUS_SUCCESS signifie que le pilote de bus a toutes les commandes dans le tableau codecTransfer vers les codecs et que la routine a écrit toutes les réponses à ces commandes dans le tableau. Toutefois, l’appelant doit case activée les réponses individuelles pour déterminer si elles sont valides. Les réponses individuelles peuvent être non valides en raison de délais d’expiration du codec ou d’un dépassement de FIFO.
Dans le cas asynchrone (le rappel n’est pas NULL), STATUS_SUCCESS signifie uniquement que la routine a correctement ajouté les commandes à la file d’attente interne du pilote de bus Audio HD. L’appelant ne doit pas tenter de lire les réponses à ces commandes tant que le pilote de bus n’appelle pas la routine de rappel.

Si une réponse n’est pas valide en raison d’un dépassement FIFO, la cause est probablement que le codec a répondu à la commande, mais que la réponse a été perdue en raison d’une mémoire tampon d’anneau d’entrée de réponse (RIRB) de taille insuffisante. Si un dépassement FIFO n’est pas à l’origine de la réponse non valide, l’échec s’est probablement produit parce que le codec n’a pas répondu dans le temps (délai d’expiration). Dans ce cas, l’appelant peut supposer que la commande n’a pas atteint le codec.

Si le paramètre de rappel a la valeur NULL, l’appelant doit s’exécuter au PASSIVE_LEVEL IRQL. Si le rappel n’est pas NULL, l’appelant peut appeler TransferCodecVerbs à l’adresse IRQL <= DISPATCH_LEVEL, auquel cas l’appel retourne immédiatement sans attendre que les codecs traitent toutes les commandes ; une fois les commandes terminées, le pilote de bus Audio HD appelle la routine de rappel au DISPATCH_LEVEL IRQL.

L’appelant doit allouer le tableau codecTransfer à partir du pool non paginé.